From 87bbd7fc4a793a951fcd131236101d15fb004231 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:31:37 +0200 Subject: [PATCH 01/47] add emoji --- S26-documentation.pod | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 93741115..9204d691 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2364,6 +2364,20 @@ single C> code, separated by semicolons: Perl 6 makes considerable use of E. +=head3 Emoji + +To include emoji codes in a Pod document, you can use the C> code along +with the colon-prefixed and postfix emoji code: + + Pod uses emoji codes to express emotions and actions, + such as E<:thumbsup:> for approval and E<:smile:> for happiness. + +In this example, C<:smile:> and C<:thumbsup:> are emoji codes representing +the respective emojis. You can use any valid emoji code in this format +to include emojis in your Pod document. + +Note that the specific emoji codes and the emojis they represent may vary +depending on the platform or system you are using. =head3 Indexing terms From 6bdd79c14c87ad77432597a68da34c2b2f85a167 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:37:11 +0200 Subject: [PATCH 02/47] update --- S26-documentation.pod | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 9204d691..b3489c73 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -6,12 +6,11 @@ This file is deliberately specified in Perl 6 Pod format =TITLE Synopsis 26 - Documentation -=begin VERSION - =table - Maintainer: Damian Conway - Date: 9 Apr 2005 - Last Modified: 25 Jul 2014 -=end VERSION +=for AUTHOR +Damian Conway |mailto:damian@conway.org>> +Aliaksandr Zahatski |mailto:zag@cpan.org>> + +=VERSION pre-1.0.0 =head1 Pod @@ -2965,9 +2964,6 @@ create a self-converting documentation file like so: =end SUMMARY -=for AUTHOR -Damian Conway |mailto:damian@conway.org>> - -=comment vim: filetype=perl6 +=LICENCE Artistic license 2.0 =end pod From 2a1634406d8df8d5d2f8f8e4cac65d4e98f3e482 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:42:37 +0200 Subject: [PATCH 03/47] add Selectors; deprecate :margin --- S26-documentation.pod | 108 ++++++++++++++++++++++-------------------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index b3489c73..a226f501 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -608,70 +608,74 @@ within code blocks>. =end defn -=begin defn -C<:margin> +=head2 Selectors -This option specifies a character that indicates the left margin of the -contents of the block. Normally this left margin is determined by the column -at which the C<=> of the opening block-delimiter occurs. For example: +Selectors consist of patterns that help identify and filter specific blocks +within documents. Each pattern contains optional source of blocks and block names. -=begin code - =head1 Indenting Pod blocks +The general syntax is: - =begin para - This text is flush with the (virtual) left margin of - the Pod block because that margin is implicitly specified - by the C<=> of the C<=begin> - =end para +=begin code :allow< R > +R +or +[ R | ] [R] =end code -However, by using the C<:margin> option it is possible to specify a -character that acts like an explicit margin when it occurs as the first -non-whitespace character on any line within the block. For example: +...where -=begin code - =head1 Indenting Pod blocks +=item EXTERNAL_SOURCE - optional source of blocks for filtering, default current document, +=item BLOCK_SELECTOR - list of block names, filter for - =begin para :margin<|> - |This text is flush with the (virtual) left margin of - |the Pod block because that margin is explicitly marked - |by the C<|>, as specified by the block's C<:margin<|>> option. - =end para -=end code +For example: -The virtual margin can even be to the left of the opening delimiter, which can -be convenient to guide subsequent indentations. For example: +=begin table :nested -=begin code - sub foo { - - V<=begin> pod :margin<|> - |=head1 Hey Look: Indented Pod! - | - |You can indent Pod in Perl 6 - |which makes code look cleaner - |when documentation is interspersed - | - | my $this is Code; - | - |=end pod - - ... - } -=end code + Selector Description + _______________________________________ ___________________________________________________ + head1, head2, item1 all head1, head2 and item1 blocks from document -When a C<:margin> option is used, each subsequent line (until the -corresponding closing delimiter is encountered) simply has any text matching -C automatically removed. This may include a line that -then becomes the closing delimiter, as in the above example. + file:atricle.pod6 | head1, head2 all head1 and head2 blocks from atricle.pod6 file -Any line from which such a margin marker is removed automatically resets -the implicit margin for subsequent lines of the block, setting it to the -length of the "marginalized" indent that was just removed. This implicit -margin is then used until the next line with an explicit margin marker -is encountered, or the block terminates. + file:./includes/*.pod6 | head1, head2 all head1 and head2 blocks from pod6 files placed + in includes directory -=end defn + doc:Data::Dumper | code all code blocks from a module documentation + + file:/docs/**/*.md | head1 search headers with first level for all ".md" files + within the "docs" directory and its subdirectories. +=end table + +Please note that while the Selector blocks provide a way to query and filter specific elements +within Markdown files, Markdown itself doesn't have formal named blocks like the Pod syntax. +Instead, Markdown uses a lightweight markup to structure content. The above table provides a mapping +between Pod block names and their corresponding Markdown elements. + +=begin table :nested :caption("A table of correspondences for some Pod blocks and markdown blocks") + + Pod Markdown Describtion + _______________________________________ ______________ _____________________________________ + head1, head2, ... #, ##, ... Heading level 1,2... + + C<=nested> ">" blockquote + + C<=para> block of text paragraph + + C> [^1]: footnote. footnote + + C<=Html> text HTML block + + C> ~~text~~ Strikethrough, "O for Overstrike" + + C> ^text^ Superscript, "H for High text" + + C> ~text~ Subscript, "J for Junior text" + + C>, C<=formula> $,$$, ```math Mathematical formulas + +=end table + +The most common use of Selectors is to create L and +in L. =head2 Block types From e63a077d1e5ac53088592c0d1fcaf2136590a922 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:44:42 +0200 Subject: [PATCH 04/47] add =toc --- S26-documentation.pod | 52 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index a226f501..13daf7f6 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1740,6 +1740,58 @@ B<3.EI> =end code =end nested +=head3 Table of contents + +The C<=toc> block is used to make an autogenerated table of contents (TOC) +in a document. The TOC is an index of section titles within the document, +and its structure is determined by the document's organization. + +The first non-blank line of C<=toc> content is treated as a L + +For example: + +=begin code + =toc head1, head2, head3, item1, item2, table +=end code + +or + +=begin code + =toc head1, head2, head3 +=end code + +The TOC is, by default, displayed without a caption. +However, the value assigned to the C<:caption> +attribute of the C<=toc> block is used to generate a caption for the TOC. + +For example: + +=begin code :allow + =for toc B<:caption('Table of contents')> + head1, head2, head3 +=end code + +To build the entries in the TOC, the content of the C<:caption> attribute +within the block is used. If this attribute does not exist, then the text +presentation of the block's content is utilized as the TOC entry. + +The depth of the generated TOC is determined by the L<"Selector"|#Selectors> argument. +The selector processed, and headers or filtered blocks that +allow levels are used to build the TOC levels. If a block does not have an +associated level, it is rendered at a level one higher than the previous +block with a level in the TOC. + +Note also that all L are treated as equivalent to C headings, and the +C<=item1>/C<=item> equivalence is preserved. + +The TOC is inserted at the location of the C<=toc> block. + +To enable the autogenerated TOC, controlled and maintained by render, set the C<:toc> +document attribute for C<=pod> block. In this case, the specific configuration +and outcome of the TOC are influenced by the settings of the concrete render implementation. + + =head2 Formatting codes From 2c888c4bdfc31c0c1cf43db06f575a538462c375 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:45:02 +0200 Subject: [PATCH 05/47] add =include --- S26-documentation.pod | 48 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 13daf7f6..cedaf1c1 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1791,6 +1791,54 @@ To enable the autogenerated TOC, controlled and maintained by render, set the C document attribute for C<=pod> block. In this case, the specific configuration and outcome of the TOC are influenced by the settings of the concrete render implementation. +=head3 Include block + +The C<=include> block is a powerful tool that allows to reuse specific +parts of documents within project sources. This is particularly handy +when dealing with complex documents that require to include certain +sections from different files while keeping the overall context and +structure intact. + +The C<=include> block is followed by an L<"Selector"|#Selectors> that specifies the +content to be included. + +In this example, the content of the file "chapter01.pod6" located in the +"./includes" directory is included: + +=begin code + =include file:./includes/chapter01.pod6 +=end code + +A wildcard L<"Selector"|#Selectors> serves this purpose, enabling inclusion +of content from all the Markdown files: + +=begin code +=include file:./includes/*.md +=end code + +It's possible to include blocks from the same document being worked on. +This feature proves valuable when reusing parts of existing content. + +For instance, a semantic block "VERSION" can be included as demonstrated: + +=begin code :allow +B<=include VERSION> +=VERSION 1.0.0 +=end code + +or, equivalently: + +=begin code +=VERSION 1.0.0 +=VERSION 1.0.0 +=end code + +It's crucial to think about security concerns, as adding content from external +sources could potentially create vulnerabilities such as injecting harmful code +or malicious material. Tools responsible for displaying and handling the content +should be able to provide a warning in such situations. + + =head2 Formatting codes From 1d3676530211849dc2705f99c2a7aa1c4e7c198a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:45:22 +0200 Subject: [PATCH 06/47] =picture --- S26-documentation.pod | 56 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index cedaf1c1..c4ed44a0 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1838,6 +1838,62 @@ sources could potentially create vulnerabilities such as injecting harmful code or malicious material. Tools responsible for displaying and handling the content should be able to provide a warning in such situations. +=head3 Inserting pictures + +Pod allows to include images using a C<=picture> block with an inline version +represented as C>: + +=begin code :allow + B<=picture astronaut.png> + =para In the vast expanse of the cosmos, an intrepid B> + floats weightlessly above the Earth. +=end code + +The first non-blank line of content within the C<=picture> block specifies the +source of the image and the remaining content is treated as caption. + +This source can be either local or remote, and it can be +indicated using different schemas: C for remote images or C for local ones. +If no schema is provided, it defaults to C. + +=begin code :allow + =picture https://example.com/image.jpg + =picture file:/local/image.png + =picture /local/image.png + =picture ../image.png +=end code + +Following the source line, it possible to include an image caption. + +=begin code + =picture astronaut.png + In the vast expanse of the cosmos, an intrepid B + floats weightlessly above the Earth. +=end code + +in delimited form of C<=picture> it possible to include as match texts as needed: + +=begin code + =begin picture + astronaut.png + + In the vast expanse of the cosmos, an intrepid B + floats weightlessly above the Earth. + + This astronaut explores the vastness of space. + + =end picture +=end code + +It possible to use all inline markup codes that are +supported by L. + +Alternatively, you can define the image caption using the C<:caption> attribute. + +=begin code :allow + =for picture B<:caption> + diag01.png +=end code From ee4f3e70b1dba3e42f6ab92492d811ee7e8a35cd Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:48:18 +0200 Subject: [PATCH 07/47] mathematical formulas =formula>, F<> --- S26-documentation.pod | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index c4ed44a0..7e1b1678 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1895,6 +1895,32 @@ Alternatively, you can define the image caption using the C<:caption> attribute. diag01.png =end code +=head3 Mathematical formulas + +To include mathematical formulas, use a C<=formula> block with an inline version +represented as C>. + +To insert mathematical expressions, use LaTeX-style syntax, which is +a commonly used format for writing mathematical equations. + +=begin code :allow + B<=formula> + x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} + + In a right triangle, the length of the hypotenuse can be calculated + using the Pythagorean theorem: B>. + + Euler's identity, B>, is a fundamental equation in + complex analysis. + +=end code + +I possible to define the formule caption using the C<:caption> attribute. + +=begin code :allow + =formula B< :caption > + x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} +=end code =head2 Formatting codes From 24195806b9d0bc177ee1c1cfd5355f201eadd883 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:50:58 +0200 Subject: [PATCH 08/47] tables --- S26-documentation.pod | 173 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 7e1b1678..a6fb34d8 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1450,6 +1450,34 @@ This means you can create tables compactly, line-by-line: The Bowler Carol Pinnsler Haunted bowling ball =end code +With header: + +=begin code + =begin table + + Directive Specifies + _________ ____________________________________________________ + C<=begin> Start of an explicitly terminated block + C<=config> Lexical modifications to a block or formatting code + + =end table +=end code + +Or: + +=begin code + =begin table + + Programming Language Possible Values + + Python python + Raku raku + HTML html + CSS css + + =end table +=end code + or line-by-line with multi-line headers: =begin code @@ -1484,6 +1512,151 @@ or with multi-line headers I multi-line data: =end table =end code +=head4 Advanced Table Format + +Tables may construct using C<=row> and C<=cell> blocks. +The C<=row> blocks represent individual rows within the table. + +The C<=cell> blocks exist within rows and contain the actual content of the table. +These cells can contain text, data, or other blocks. + +=begin code + =begin table + + =begin row + =cell Fruits + =cell Bananas + =cell Yellow and ripe + =end row + + =begin row + =cell Vegetables + =cell Carrots + =begin cell + =para Crunchy and orange + =end cell + =end row + + =end table +=end code + +Each C<=row> block may have an optional C<:header> attribute, designating +it as a header row. Header rows typically contain labels or titles +for columns and are visually distinct. + + +=begin code :allow + =begin table + + =begin row B<:header> + =cell Category + =cell Product + =cell Description + =end row + + =begin row + =cell Fruits + =cell Bananas + =cell Yellow and ripe + =end row + + =begin row + =cell Vegetables + =cell Carrots + =cell Crunchy and orange + =end row + + =end table +=end code + +The C<=cell> blocks can also have two important attributes: + +=begin defn +C<:colspan> + +This attribute specifies the number of columns a cell should span horizontally. +It allows cells to merge and occupy multiple adjacent columns, creating a visually +unified cell. +=end defn + +=begin defn +C<:rowspan> + +This attribute determines how many rows a cell should span vertically. +Cells with C<:rowspan> can cover multiple rows in a table, creating a vertical merge effect. +=end defn + +These example demonstrate how C<:colspan> and C<:rowspan> attributes can be used +to create tables with merged cells, which is especially useful for complex +data structures. + +=begin code + =begin table + + =begin row :header + =for cell :colspan(2) + Item and Quantity + =cell Description + =end row + + =begin row + =cell Apples + =cell 5 + =for cell :rowspan(2) + Fruit for snacking + =end row + + =begin row + =cell Bananas + =cell 3 + =end row + + =end table +=end code + + +It draw somethink like this: + + --------------------------------------------------------------- + | Item and Quantity | Description | + |----------------------------------|--------------------------| + | Apples | 5 | | + |--------------|-------------------| Fruit for snacking | + | Bananas | 3 | | + --------------------------------------------------------------- + +Each C<=row> block may only contain C<=cell> blocks or blank lines as delimiters. +All other types of blocks within the C<=row> are implicitly wrapped +by C<=cell> blocks. + +For example: + +=begin code + + =begin table + + =begin row :header + =cell Diagram or Picture + =cell Description + =end row + + =begin row + =picture spacecraft_in_orbit.jpg + =para + A vehicle designed for space travel + =end row + + =begin row + =Mermaid + graph TD; + A[Space Station] --> B[Mars Base] + + A space station connected to a Mars base + =end row + + =end table + +=end code =head3 Named blocks From 2fb3a9f851e209c991d7796b02e3ae90bd36922e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:51:53 +0200 Subject: [PATCH 09/47] :id attrubute --- S26-documentation.pod | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index a6fb34d8..85a4093f 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -463,6 +463,14 @@ are used specifically to describe that declarand. Pod predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include: +=begin defn +C<:id> + +This option allows to explicitly define identificator for blocks and use +those IDs for linking, rather than relying on it content (see L<#Links>). + +=end defn + =begin defn C<:nested> @@ -2521,6 +2529,23 @@ The scheme name may also be omitted in that case: This mechanism is described under L> below. =end code +Pod include the possibility of assigning a unique identifier to a block. +These identifiers can be explicitly assigned to any blocks using +the C<:id> attribute. Later, these identifiers are utilized for adressing blocks +and creating links. + +=begin code :allow + =for head1 :id + Introduction + =for para B<:id> + This is an introductory paragraph. + + For more information, see L> and L> +=end code + +In this example, the link reference to the header block identified by "intro" +rather than the name "Introduction" and to the paragrapth block with identifier "id1". + Normally a link is presented as some rendered version of the link specification itself. However, you can specify an alternate presentation by prefixing the link with the desired text and a From 05509a973520788c094484e504a9a0781b2ecdef Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:54:27 +0200 Subject: [PATCH 10/47] :lang attrubute --- S26-documentation.pod | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 85a4093f..75a4ff18 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -588,6 +588,32 @@ addition to the extra "basis" and "important" formatting specified by C<:formatted>. =end defn +=begin defn +C<:lang> + +This option used to L about the programming language +used in a specific code block. This helps in ensuring that the code is +displayed and interpreted correctly by rendering engines or syntax highlighters. + +Here's a table that lists a few programming languages along with their possible +values for the C<:lang> attribute: + +=begin table :caption("Matching languages and lang attribute values") + + Programming Language Possible C<:lang> Values + + Python python + Raku raku + JavaScript javascript + Java java + C++ cpp + HTML html + CSS css + +=end table + +=end defn + =begin defn C<:like> @@ -953,6 +979,23 @@ Note that the use of the C<:allow> option also makes it possible for verbatim L (such as C> and C>) to L. +=head4 Assign programming language to code blocks + +The C<:lang> attribute will be used to provide information about the +programming language used in a particular block of code. This helps +in ensuring that the code is correctly rendered and interpreted by the +renderers or syntax highlighting tools. + +For example: + +=begin code :allow + =begin code B<:lang> + sub demo { + say 'Hello R'; + } + =end code +=end code + =head3 I/O blocks From 6199975493531460d8ce4aa39008ef9a49653766 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:54:54 +0200 Subject: [PATCH 11/47] O<>, J<>, H<> fromatting codes --- S26-documentation.pod | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 75a4ff18..6c5e6eac 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2229,6 +2229,41 @@ B or focus of the surrounding text; that it is of I. Such content would typically be rendered in a bold style or in C< ... > tags. +=head3 Mistake marking + +It possible strikethrough words using the code C, where 'O' stands +for "Overstrike." This is a way to indicate that certain words are a +mistake and should not be included in the document. + + O Our planet's sky is usually blue. + + +=head3 Text positioning + +Pod provides two formatting codes that allow positioning characters or words. + +=begin item +To create subscript text, you can use the C> formatting code, where 'J' represents +"Junior text." Subscript positions one or more characters slightly below the normal +line of type. + + HJ<2>O + +This code renders as "H2O," which signifies that the '2' is positioned +slightly below the baseline, as is often seen in chemical formulas like H₂O (water). +=end item + +=begin item +To create superscript text, it possible to use the C> formatting code, where 'H' +stands for "High text." Superscript positions one or more characters slightly +above the normal line of type + + XH<2> + +This code renders as "X2," indicating that the '2' is positioned +slightly above the baseline. This is commonly used for mathematical exponents, as in X². +=end item + =head3 Definitions From 56cf73c5d073f5fe3165aab540595ee618a25eea Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:56:27 +0200 Subject: [PATCH 12/47] task lists, :checked attribute --- S26-documentation.pod | 63 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 6c5e6eac..282bc81f 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -547,6 +547,26 @@ Note that numbering is never explicit; it is always implied by context. =end defn +=begin defn +C<:checked> + +This attribute indicates that a checkbox should be added to that block. +It possible to apply a C<:checked> attributes to any block. +The most common use of this option is to create L. + +For unchecked checkbox the C<:!checked> is used. + +The task list item marker (checkbox) is added to the output. +In an HTML output, this would be represented as an + C<> element. + +The specification does not define how these checkboxes are interacted with. +Implementors are free to choose whether they render them as disabled, +unchangeable elements, or handle dynamic interactions like checking and unchecking +in the final rendered document. + +=end defn + =begin defn C<:formatted> @@ -1297,6 +1317,49 @@ which produces: =para 3. Prophet! =end nested +=head4 Task lists + +In addition to the ordered list Pod also supports +task lists, which are commonly known as checklists or to-do lists. + +To create a task list item just apply a C<:checked> +attribute to C<=item> block. + +=begin code :allow + =for item B<:checked> + Buy groceries + =for item B<:!checked> + Clean the garage +=end code + +The rendered output looks like this: + + [ ] Buy groceries + [X] Clean the garage + +Alternatively, if item content starts with brackets with space (C<[ ]>) +the item is treated as having a C<:!checked> attribute. +To select a checkbox, add an C in between the brackets (C<[x]>). it eqvivalent +of C<:checked> attribute. + +For example: +=begin code :allow + =item B<[ ]> Buy groceries + =itme B<[x]> Clean the garage +=end code + +It possiible to create multilevel to-do lists, which permits the +inclusion of various task levels or sub-tasks. +Here's an example: + +=begin code :allow + B<=item1> [ ] Work + B<=item2> [ ] Prepare the presentation + =item2 [x] Send emails + =item1 [ ] Home + =item2 [ ] Vacuum the living room + =item2 [ ] Water the plants +=end code =head4 Unordered lists From e0b2ef9c672aefa4834912b13171b4e7d297acde Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:56:39 +0200 Subject: [PATCH 13/47] task lists, :checked attribute --- S26-documentation.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 282bc81f..37e9b4e1 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1363,7 +1363,7 @@ Here's an example: =head4 Unordered lists -List items that are not C<:numbered> are treated as defining unordered +List items that are not C<:numbered> or C<:checked> are treated as defining unordered lists. Typically, such lists are rendered with bullets. For example: =begin code From 2f68903152e1fd01ed7fb52e4c77da4dadeb340a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 08:59:25 +0200 Subject: [PATCH 14/47] deprecate P P P due =toc =include --- S26-documentation.pod | 25 +------------------------ 1 file changed, 1 insertion(+), 24 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 37e9b4e1..384a5d4a 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2761,31 +2761,8 @@ placement link: =item C and C =item C -=item C -=item C -=item C -The C form is a special pseudo-scheme that inserts a table of contents -in place of the C> code. After the colon, list the block types that you -wish to include in the table of contents. For example, to place a table of -contents listing only top- and second-level headings: - - P - -To place a table of contents that lists the top four levels of headings, as -well as any tables: - - P - -To place a table of diagrams (assuming a user-defined C block): - - P - -Note also that, for C>, all L are treated as equivalent to C headings, and the -C<=item1>/C<=item> equivalence is preserved. - -A document may have as many C> placements as necessary. +For L C> works as inline equivalent of a C<=picture> block. =head3 Alias placements From 33ac8f09af9a94b276d2f33e83aca109831b0a6a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 09:00:07 +0200 Subject: [PATCH 15/47] :caption attribute --- S26-documentation.pod | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 384a5d4a..3181533d 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -463,6 +463,16 @@ are used specifically to describe that declarand. Pod predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include: +=begin defn +C<:caption> + +This option specifies that the block may be given an associated description or title using the +C<:caption> option. + +Usually, this description uses for build L
. + +=end defn + =begin defn C<:id> From 534417c80a1e86bc33b5979db4f2058cf8ba5a2c Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:02:41 +0200 Subject: [PATCH 16/47] deprecate =encoding --- S26-documentation.pod | 48 +------------------------------------------ 1 file changed, 1 insertion(+), 47 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 3181533d..c1a4deb1 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -3005,51 +3005,6 @@ If the formatting code is unrecognized, the contents of the code (i.e. everything after the first colon) would normally be rendered as ordinary text. - -=head2 Encoding - -By default, Pod assumes that documents are Unicode, encoded in one -of the three common schemes (UTF-8, UTF-16, or UTF-32). The particular -scheme a document uses is autodiscovered by examination of the first few -bytes of the file (where possible). If the autodiscovery fails, UTF-8 is -assumed, and parsers may treat any non-UTF-8 bytes later in the -document as fatal errors. - -At any point in a document, you can explicitly set or change the encoding -of its content using the C<=encoding> directive: - -=begin code - =encoding ShiftJIS - - =encoding Macintosh - - =encoding KOI8-R -=end code - -The specified encoding is used from the start of the I line in -the document. If a second C<=encoding> directive is encountered, the -current encoding changes again after that line. Note, however, that -the second encoding directive must itself be encoded using the first -encoding scheme. - -This requirement also applies to an C<=encoding> directive at the very -beginning of the file. That is, it must itself be encoded in -the default UTF-8, -16, or -32. However, as a special case, the -autodiscovery mechanism will (as far as possible) also attempt to -recognize "self-encoded" C<=encoding> directives that begin at the first -byte of the file. For example, at the start of a ShiftJIS-encoded file -you can specify C<=encoding ShiftJIS> in the ShiftJIS encoding. - -An C<=encoding> directive affects any ambient code between the Pod -as well. That is, Perl 6 uses C<=encoding> directives to determine the -encoding of its source code as well as that of any documentation. - -Note that C<=encoding> is a fundamental Pod directive, like C<=begin> or -C<=for>; it is I an instance of an L. Hence there is no paragraph or delimited form of the C<=encoding> -directive (just as there is no paragraph or delimited form of C<=begin>). - - =head2 Block pre-configuration The C<=config> directive allows you to prespecify standard configuration @@ -3073,7 +3028,7 @@ The general syntax for configuration directives is: = R =end code -Like C<=encoding>, a C<=config> is a directive, not a block. Hence, +A C<=config> is a directive, not a block. Hence, there is no paragraph or delimited form of the C<=config> directive. Each C<=config> specification is lexically scoped to the surrounding block in which it is specified. @@ -3415,7 +3370,6 @@ create a self-converting documentation file like so: _________ ____________________________________________________ C<=begin> Start of an explicitly terminated block C<=config> Lexical modifications to a block or formatting code - C<=encoding> Encoding scheme for subsequent text C<=end> Explicit termination of a C<=begin> block C<=for> Start of an implicitly (blank-line) terminated block C<=alias> Define a Pod macro From 63e040650bc73bbec1129023ae47ddbdb564e113 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:05:52 +0200 Subject: [PATCH 17/47] add backward linking --- S26-documentation.pod | 46 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index c1a4deb1..3ab19263 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2840,6 +2840,52 @@ rather than: =nested The emergency signal is: dot dot dot dash dash dash dot dot dot. +=head3 Backward links + +Bidirectional or backward linking refers to the ability to navigate +from a destination page back to the source page through +a hyperlink or other means. + +Usual link are works by the following way: + +=begin code :allow + C> -> Perl data page + source destanation +=end code + +Backward is working in anothe manner: + +=begin code :allow + C> <- Perl data page + destanation source +=end code + +Here are examples of bidirectional or backward linking: + +=begin code :allow + This text can reveal the meaning of B> +=end code + +or: + +=begin code :allow + We discuss here about B>. +=end code + +A contextual backlink displays not only a reference +from another location, but the specific context around that +reference—for instance, the page of a book or the referencing +paragraph. + +Backward links operate similarly to standard links +but might be distinguished by color. + +Backward links may be highlighted by color, and it is essential +to see the context surrounding the backlink to understand +the implied meaning. Backlinks on the source page can be displayed +with surrounding text chunks or placed at the end of the text, +in the margin of the page, or highlighted in some other way. + =head3 Entities From 3a54aedd7bf5677b8267bce651c3e5b88ceb7e78 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:11:02 +0200 Subject: [PATCH 18/47] update for the Raku era --- S26-documentation.pod | 119 +++++++++++++++++++++++------------------- 1 file changed, 65 insertions(+), 54 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 3ab19263..5ab33cd1 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1,10 +1,10 @@ =begin pod =comment -This file is deliberately specified in Perl 6 Pod format +This file is deliberately specified in Raku Pod format =TITLE -Synopsis 26 - Documentation +Raku Documentation =for AUTHOR Damian Conway |mailto:damian@conway.org>> @@ -21,7 +21,7 @@ documentation, for documenting programs and modules, as well as for other types of document composition. Pod is an evolution of Perl 5's L|doc:perlpod> -(POD) markup. Compared to POD, Perl 6's Pod is much more +(POD) markup. Compared to POD, Raku Pod is much more uniform, somewhat more compact, and considerably more expressive. The Pod dialect also differs in that it is a purely descriptive mark-up notation, with no presentational components. @@ -32,7 +32,7 @@ notation, with no presentational components. Pod documents are specified using D, which are used to declare configuration information and to delimit blocks of textual content. All Pod directives are considered to be special types -of comments in Perl 6. +of comments in Raku. Every directive starts either with an equals sign (C<=>) followed immediately by an identifier N, or with @@ -41,7 +41,7 @@ a C<#=> or C<#|> followed immediately by whitespace or an opening bracket. Directives that start with C<=> can be indented like the code they interleave, but their initial C<=> must still be the first non-whitespace character on their line. Directives that start with C<#=> or C<#|> can be placed -anywhere that a Perl 6 comment can appear, though they are meaningful +anywhere that a Raku comment can appear, though they are meaningful only in a subset of those places; see L<#Declarator blocks>. An indented Pod block is considered to have a I, @@ -51,7 +51,7 @@ In other words, if a directive is indented from the left margin, the column at which the first character of its opening delimiter appears is thereafter considered the first column of the entire block's contents. -As with Perl 6 heredocs, the virtual margin treats leading tabs as +As with Raku heredocs, the virtual margin treats leading tabs as aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. =head2 @@ -75,7 +75,7 @@ will I ignore such blocks, but see L<#Aliases>. In Perl 5's POD format, once a POD directive is encountered, the parser considers everything that follows to be POD, until an explicit C<=cut> directive is encountered, at which point the parser flips back to -parsing ambient source code. The Perl 6 Pod format is different. All Pod +parsing ambient source code. The Raku Pod format is different. All Pod directives have a defined terminator and the Pod parser always reverts to "ambient" at the end of each Pod directive or block. To cause the parser to remain in Pod mode, you must enclose the desired Pod region in a @@ -96,7 +96,7 @@ C block: =head3 Delimited blocks Delimited blocks are bounded by C<=begin> and C<=end> markers, both of -which are followed by a valid Perl 6 identifier, which is the +which are followed by a valid Raku identifier, which is the D of the block. Typenames that are entirely lowercase (for example: C<=begin head1>) or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved. @@ -104,7 +104,7 @@ SYNOPSIS>) are reserved. After the typename, the rest of the C<=begin> marker line is treated as configuration information for the block. This information is used in different ways by different types of blocks, but is always specified using -Perl6-ish option pairs. That is, any of: +Raku-ish option pairs. That is, any of: =for table :nested Value is... Specify with... Or with... Or with... @@ -118,7 +118,7 @@ Perl6-ish option pairs. That is, any of: All option keys and values must, of course, be constants since Pod is a specification language, not a programming language. Specifically, option values cannot be closures. See Synopsis 2 for details of the various -Perl 6 pair notations. +Raku pair notations. The configuration section may be extended over subsequent lines by starting those lines with an C<=> in the first (virtual) column followed @@ -170,7 +170,7 @@ This is a universal feature of Pod. Note also that in the following specifications, a "blank line" is a line that is either empty or that contains only whitespace characters. That -is, a blank line matches the Perl 6 pattern: C. Pod uses +is, a blank line matches the Raku pattern: C. Pod uses blank lines as delimiters, rather than empty lines, to minimize unpleasant surprises when stray spaces or tabs mysteriously turn up in hitherto empty lines. @@ -246,16 +246,16 @@ configuration is required, use a C<=for> or C<=begin>/C<=end> instead. The fourth form of Pod block differs from the first three in that it does not specify an explicit typename. Instead, it obtains its identity -and purpose from the Perl 6 source code to which it is attached; +and purpose from the Raku source code to which it is attached; specifically, from some nearby declarator. -Declarator blocks are introduced by a special Perl comment: either C<#=> +Declarator blocks are introduced by a special Raku comment: either C<#=> or C<#|>, which must be immediately followed by either by a space or an opening bracket. If followed by a space, the block is terminated by the end of line; if followed by one or more opening brackets, the block is terminated by the matching sequence of closing brackets. -That is, declarator Pod blocks are syntactically like ordinary Perl 6 +That is, declarator Pod blocks are syntactically like ordinary Raku single-line comments and embedded comments. The general syntax is: =begin code :allow< R > @@ -274,11 +274,11 @@ single-line comments and embedded comments. The general syntax is: =end code -except that the bracketed forms may use I valid Perl 6 bracket delimiter +except that the bracketed forms may use I valid Raku bracket delimiter (including repeated opening brackets), as described in Synopsis 2. Declarator Pod blocks must either precede or immediately follow a valid -Perl 6 declarator, and are then said to be "attached" to it. They are +Raku declarator, and are then said to be "attached" to it. They are primarily intended to simplify the documentation of code interfaces. Declarator blocks that start with C<#|> attach to the declarator immediately @@ -1826,12 +1826,12 @@ uppercase letters are reserved. See L<#Semantic blocks>. =head3 Pod comments -All Pod blocks are intrinsically Perl 6 comments, but +All Pod blocks are intrinsically Raku comments, but D are comments that Pod renderers ignore too. That is, they are Pod blocks that are never to be rendered by any renderer. They are, of course, still included in any internal Pod representation, and are accessible via the Pod API...and via the -C<$=pod> variable within a Perl 6 program. +C<$=pod> variable within a Raku program. Comments are useful for meta-documentation (documenting the documentation): @@ -1853,9 +1853,9 @@ and for temporarily removing parts of a document: B<=end comment> =end code -Note that, since the Perl interpreter never executes embedded Pod +Note that, since the Raku interpreter never executes embedded Pod blocks, C blocks can also be used as an alternative form of -nestable block comments in Perl 6: +nestable block comments in Raku: =begin code =begin comment @@ -1883,7 +1883,7 @@ an C<=finish> block is in all other respects identical to a C<=pod> block. =head3 Data blocks -Named Pod blocks whose typename is C are the Perl 6 equivalent of +Named Pod blocks whose typename is C are the Raku equivalent of the Perl 5 C<__DATA__> section. The difference is that C<=data> blocks are just regular Pod blocks and may appear anywhere within a source file, and as many times as required. @@ -1940,7 +1940,7 @@ C<=data> blocks are never rendered by the standard Pod renderers. All uppercase block typenames are reserved for specifying standard documentation, publishing, source components, or meta-information of a compunit it needs to be able to be selected for loading. In particular, all the -standard components found in Perl and manpage documentation have +standard components found in Raku and manpage documentation have reserved uppercase typenames. Standard semantic blocks include: @@ -2031,9 +2031,9 @@ C<=SYNOPSIS> block of the preceding example might be rendered like so: B<3.EI> =begin code - use Perl6::Magic::Parser; + use Raku::Magic::Parser; - my $rep = Perl6::Magic::Parser.parse($fh, :all_pod); + my $rep = Raku::Magic::Parser.parse($fh, :all_pod); =end code =end nested @@ -2404,7 +2404,7 @@ L it: =begin code :allow =begin para B<=config C<> :allow> - Perl 6 makes extensive use of the C>> and C>> + Raku makes extensive use of the C>> and C>> characters, for example, in a hash look-up: C<%hashB>>keyB>>> =end para @@ -2712,7 +2712,6 @@ For example: His Ldefn:lexiphania>> tendencies were, alas, incurable. =end code - =head3 Placement links A second kind of linkEthe C> or BEworks @@ -2766,7 +2765,7 @@ B See: L =end nested -You can use any of the following URI forms (see L<#Links>) in a +You can use the following URI forms in a placement link: =item C and C @@ -2790,7 +2789,7 @@ For example: laid out by A, as specified at A. =end code -Any compile-time Perl 6 object that starts with a sigil is automatically +Any compile-time Raku object that starts with a sigil is automatically available within an alias placement as well. Unless the object is already a string type, it is converted to a string during document-generation by implicitly calling C<.perl> on it. @@ -2895,31 +2894,31 @@ Pod document, specify the required D using the C> code. If the C> contains a number, that number is treated as the decimal Unicode value for the desired code point. For example: - Perl 6 makes considerable use of E<171> and E<187>. + Raku makes considerable use of E<171> and E<187>. You can also use explicit binary, octal, decimal, or hexadecimal numbers -(using the Perl 6 notations for explicitly based numbers): +(using the Raku notations for explicitly based numbers): - Perl 6 makes considerable use of E<0b10101011> and E<0b10111011>. - Perl 6 makes considerable use of E<0o253> and E<0o273>. - Perl 6 makes considerable use of E<0d171> and E<0d187>. - Perl 6 makes considerable use of E<0xAB> and E<0xBB>. + Raku makes considerable use of E<0b10101011> and E<0b10111011>. + Raku makes considerable use of E<0o253> and E<0o273>. + Raku makes considerable use of E<0d171> and E<0d187>. + Raku makes considerable use of E<0xAB> and E<0xBB>. If the C> contains anything that is not a number, the contents are interpreted as a Unicode character name (which is always uppercase), or else as an HTML5 named character reference. For example: - Perl 6 makes considerable use of E + Raku makes considerable use of E and E. or, equivalently: - Perl 6 makes considerable use of E and E. + Raku makes considerable use of E and E. Multiple consecutive entities (in any format) can be specified in a single C> code, separated by semicolons: - Perl 6 makes considerable use of E. + Raku makes considerable use of E. =head3 Emoji @@ -2993,7 +2992,7 @@ Anything enclosed in an C> code is an inline B. For example: =begin code :allow - Use a C loop instead.B loop is far more + Use a C loop instead.B loop is far more powerful than its Perl 5 predecessor.>> Preferably with an explicit iterator variable. =end code @@ -3013,7 +3012,7 @@ and later: B =para -E The Perl 6 C loop is far more powerful than its Perl 5 +E The Raku C loop is far more powerful than its Perl 5 predecessor. =end nested @@ -3153,7 +3152,7 @@ identifier (which is usually specified in uppercase, though this is certainly not mandatory). The second argument consists of one or more lines of replacement text. -This creates a lexically scoped Perl 6 macro that can be invoked during +This creates a lexically scoped Raku macro that can be invoked during document generation by placing the identifier (i.e. the first argument of the alias) in an C> formatting code. This formatting code is then replaced by the text returned by new macro. @@ -3218,7 +3217,7 @@ and some portion of the following code is used as the value returned by the alias macro. Note that the code block following the C<=alias> line is still treated -as real code by the Perl 6 parser, but its contents are I used to +as real code by the Raku parser, but its contents are I used to create the replacement macro of the alias. This allows the developer to reproduce chunks of actual source code directly in the documentation, without having to copy it. @@ -3303,25 +3302,25 @@ attribute. By default, handles are opened to the file "C". =head1 How Pod is parsed and processed -Pod is just a collection of specialized forms of Perl 6 comment. Every -Perl 6 implementation must provide a special command-line flag that +Pod is just a collection of specialized forms of Raku comment. Every +Raku implementation must provide a special command-line flag that locates, parses, and processes Pod to produce documentation. That flag is K<--doc>. Hence, to read Pod documentation you would type things like: - perl --doc perlrun + raku --doc perlrun - perl --doc DBI::DBD::Metadata + raku --doc DBI::DBD::Metadata - perl --doc ./lib/My/Module.pm + raku --doc ./lib/My/Module.pm -When the Perl 6 interpreter is run in this mode, it sets the compiler +When the Raku interpreter is run in this mode, it sets the compiler hint C<$?DOC> to true. If the K<--doc> flag is given a value, that value (with a C added) is placed in C<$?DOC>. This can be used to specify, for example, the output format desired: - perl --doc=HTML perldelta > perldelta.html + raku --doc=HTML perldelta > perldelta.html Under K<--doc>, the interpreter runs in a special mode, parsing the source code (including the Pod, as it always does) during compilation @@ -3341,7 +3340,7 @@ the C<$=pod> tree, and any C blocks that have loaded Pod-related handler code. Because the conversion of documentation is just a variation on the -standard Perl 6 compilation process, the processing of any given file of +standard Raku compilation process, the processing of any given file of Pod can be modified from within that file itself by the appropriate insertion of C blocks. For example: @@ -3382,7 +3381,7 @@ long as you remember to exit before the default C can run: The idea is that developers will be able to add their own documentation mechanisms simply by loading a module (via a C) to augment or override the default documentation behaviour. Such mechanisms can then -be built using code written in standard Perl 6 that accesses C<$=pod>, +be built using code written in standard Raku that accesses C<$=pod>, as well as using the C<.WHY> and C<.WHEREFORE> introspection methods of any constructs that have attached Pod blocks. @@ -3390,7 +3389,7 @@ Note also that this mechanism means that, on many systems, you can create a self-converting documentation file like so: =begin code - #! /usr/bin/perl6 --doc + #! /usr/bin/raku --doc =begin pod @@ -3440,8 +3439,12 @@ create a self-converting documentation file like so: C<=para> Ordinary paragraph C<=pod> No "ambient" blocks inside C<=table> Simple rectangular table - C<=data> Perl 6 data section + C<=data> Raku data section C<=finish> No ambient blocks after this point + C<=toc> Autogenerated table of contents + C<=include> Include other blocks, documents + C<=picture> Inserting pictures + C<=formula> Mathematical formulas C<=>R Semantic blocks (C<=SYNOPSIS>, C<=BUGS>, etc.) C<=>R User-defined block @@ -3457,18 +3460,26 @@ create a self-converting documentation file like so: C> Basis/focus of sentence (typically rendered bold) C> Code (typically rendered fixed-width) C> Definition (C|R;R;...>>) - C> Entity names or numeric codepoints (C;R;...>>) + C> Entity names or numeric codepoints (C;R;...>>), emoji + C> Mathematical formula + C> reserved + C> Superscript C> Important (typically rendered in italics) + C> Subscript C> Keyboard input (typically rendered fixed-width) C> Link (C|R>>) C> Module-defined code (C:R>>) C> Note (not rendered inline) - C> Placement link + C> Strikethrough + C> Placement link, inline eqivalent for C<=picture> block + C> reserved C<...>> Replaceable component or metasyntax C> Space characters to be preserved C> Terminal output (typically rendered fixed-width) C> Unusual (typically rendered with underlining) C<...>> Verbatim (internal formatting codes ignored) + C> Backward link + C> reserved C> Index entry (C|R,R;...>>) C> Zero-width comment (contents never rendered) From 61ffc30b255f49ffa4028c810a5cabad1c820a12 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:12:05 +0200 Subject: [PATCH 19/47] add CHANAGES section --- S26-documentation.pod | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index 5ab33cd1..3f3c04af 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -12,6 +12,32 @@ Aliaksandr Zahatski |mailto:zag@cpan.org>> =VERSION pre-1.0.0 +=begin CHANGES + +=head2 pre-1.0.0 +=head3 New: + =item add C<:id>, C<:caption>, C<:lang> attributes, + =item task lists, C<=item :checked>, + =item intro Selectors, + =item advanced table format, C<=row>,C<=cell> blocks, + C<:header>, C<:rowspan>, C<:colspan> attributes, + =item table of contents, C<=toc>, + =item include block, C<=include>, + =item inserting pictures, C<=picture>, C>, + =item mathematical formulas, C<=formula>, C>, + =item mistake marking, C>, + =item text positioning, C>, C>, + =item Emoji, C>, + =item backward links, C> + +=head3 Deprecated/removed: + =item C<:margin> attribute, + =item C<=encoding> directive, + =item C> due to C<=toc> block, + =item C>, C> due to C<=include> block, + +=end CHANGES + =head1 Pod From 31e36a1a173a4395c756d255350b3dd8915a4afa Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:19:39 +0200 Subject: [PATCH 20/47] update emoji --- S26-documentation.pod | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 3f3c04af..54688bde 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2941,15 +2941,8 @@ or, equivalently: Raku makes considerable use of E and E. -Multiple consecutive entities (in any format) can be specified in a -single C> code, separated by semicolons: - - Raku makes considerable use of E. - -=head3 Emoji - -To include emoji codes in a Pod document, you can use the C> code along -with the colon-prefixed and postfix emoji code: +To include emoji codes, you can use the C> code along +with the colon-prefixed and postfix emoji shortname: Pod uses emoji codes to express emotions and actions, such as E<:thumbsup:> for approval and E<:smile:> for happiness. @@ -2961,6 +2954,12 @@ to include emojis in your Pod document. Note that the specific emoji codes and the emojis they represent may vary depending on the platform or system you are using. +Multiple consecutive entities (in any format) can be specified in a +single C> code, separated by semicolons: + + Raku makes considerable use of E. + + =head3 Indexing terms Anything enclosed in an C> code is an B. The contents From 195fb284bfe496208f3bd29850a113d1a16fde28 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:20:23 +0200 Subject: [PATCH 21/47] update P<> --- S26-documentation.pod | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 54688bde..41fd1091 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2797,7 +2797,8 @@ placement link: =item C and C =item C -For L C> works as inline equivalent of a C<=picture> block. +For L C> works as inline equivalent of a C<=picture> block +in the following form: C>. =head3 Alias placements From 4569fd66cea5adfdb912c7eebdbde36c144bb440 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 16 Oct 2023 20:22:24 +0200 Subject: [PATCH 22/47] update CHANGES --- S26-documentation.pod | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 41fd1091..d3c2675c 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -17,10 +17,8 @@ Aliaksandr Zahatski |mailto:zag@cpan.org>> =head2 pre-1.0.0 =head3 New: =item add C<:id>, C<:caption>, C<:lang> attributes, - =item task lists, C<=item :checked>, + =item task lists, C<=item> and C<:checked> attribute, =item intro Selectors, - =item advanced table format, C<=row>,C<=cell> blocks, - C<:header>, C<:rowspan>, C<:colspan> attributes, =item table of contents, C<=toc>, =item include block, C<=include>, =item inserting pictures, C<=picture>, C>, @@ -29,7 +27,9 @@ Aliaksandr Zahatski |mailto:zag@cpan.org>> =item text positioning, C>, C>, =item Emoji, C>, =item backward links, C> - + =item advanced table format, C<=row>,C<=cell> blocks, + C<:header>, C<:rowspan>, C<:colspan> attributes, + =head3 Deprecated/removed: =item C<:margin> attribute, =item C<=encoding> directive, From 81fc792f10a3d32fde744cb04503cdc937395abe Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 18 Oct 2023 07:37:47 +0200 Subject: [PATCH 23/47] add =markdown --- S26-documentation.pod | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/S26-documentation.pod b/S26-documentation.pod index d3c2675c..9f6d01ec 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -23,6 +23,7 @@ Aliaksandr Zahatski |mailto:zag@cpan.org>> =item include block, C<=include>, =item inserting pictures, C<=picture>, C>, =item mathematical formulas, C<=formula>, C>, + =item Markdown support, C<=markdown> =item mistake marking, C>, =item text positioning, C>, C>, =item Emoji, C>, @@ -2245,6 +2246,47 @@ I possible to define the formule caption using the C<:caption> attribute. x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} =end code +=head3 Markdown support + +Pod includes built-in support for Markdown, making it easy to include Markdown +content within Pod documents. This is achieved using the C<=markdown> block. + +=begin code :allow + =begin markdown + ## Markdown Example + + You can use all the standard Markdown syntax within this block. For example: + + - *Italic text* using asterisks or underscores: *italic* or _italic_. + - **Bold text** using double asterisks or underscores: **bold** or __bold__. + - [Links](https://example.com) with the `[text](url)` syntax. + - Unordered lists using `-`, `*`, or `+`: + + - Item 1 + - Item 2 + + - Ordered lists using numbers: + + 1. First item + 2. Second item + + - Code blocks with backticks: + + ```python + def hello_world(): + print("Hello, World!") + ``` + + - Blockquotes with the `>` symbol: + + > This is a blockquote. + + =end markdown +=end code + +This block allows to seamlessly combine Pod's structured blocks with +the flexibility of Markdown. + =head2 Formatting codes @@ -3471,6 +3513,7 @@ create a self-converting documentation file like so: C<=include> Include other blocks, documents C<=picture> Inserting pictures C<=formula> Mathematical formulas + C<=markdown> Markdown support C<=>R Semantic blocks (C<=SYNOPSIS>, C<=BUGS>, etc.) C<=>R User-defined block From bf273146f9e1f4551cdff90a931a08df163f321e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 18 Oct 2023 07:39:48 +0200 Subject: [PATCH 24/47] add contextual backlinks W<> --- S26-documentation.pod | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 9f6d01ec..2a1a8cd0 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -27,7 +27,7 @@ Aliaksandr Zahatski |mailto:zag@cpan.org>> =item mistake marking, C>, =item text positioning, C>, C>, =item Emoji, C>, - =item backward links, C> + =item contextual backlinks, C> =item advanced table format, C<=row>,C<=cell> blocks, C<:header>, C<:rowspan>, C<:colspan> attributes, @@ -2842,6 +2842,38 @@ placement link: For L C> works as inline equivalent of a C<=picture> block in the following form: C>. +=head3 Contextual backlinks + +Pod introduces the concept of contextual backward links C> (or contextual backlinks), +enhancing the traditional L mechanism by allowing to not +only reference another location but also provide specific +context around that reference. This context can take the form of opinions, +additional information, or any relevant commentary that enhances the understanding +of the referenced material. + +For example: + +=begin code :allow + This text can reveal the meaning of B> +=end code + +or: + +=begin code :allow + We discuss here about B>. +=end code + +Contextual backlinks on the destination page can be displayed in various ways. +They may appear with surrounding text chunks, providing context within +the flow of the content. Alternatively, they can be placed at the end +of the text, in the margin of the page, or highlighted in other visually +distinctive ways. + +Like traditional L, contextual backlinks allows the use of +all available link schemes, including C and C, to link to external content. + +Contextual backlinks might be visually distinguished from +standard links through color coding. =head3 Alias placements @@ -3547,7 +3579,7 @@ create a self-converting documentation file like so: C> Terminal output (typically rendered fixed-width) C> Unusual (typically rendered with underlining) C<...>> Verbatim (internal formatting codes ignored) - C> Backward link + C> Contextual backlinks C> reserved C> Index entry (C|R,R;...>>) C> Zero-width comment (contents never rendered) From 9dca9f0e16e1ce84facb483e2cad0a1b8106ef22 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 18 Oct 2023 08:05:46 +0200 Subject: [PATCH 25/47] clean up --- README.md | 14 +- S01-overview.pod | 232 -- S02-bits.pod | 4948 ---------------------- S03-operators.pod | 5446 ------------------------- S04-control.pod | 1888 --------- S05-regex.pod | 4829 ---------------------- S06-routines.pod | 3614 ---------------- S07-lists.pod | 352 -- S08-capture.pod | 219 - S09-data.pod | 1329 ------ S10-packages.pod | 251 -- S11-modules.pod | 744 ---- S12-objects.pod | 2745 ------------- S13-overloading.pod | 216 - S14-roles-and-parametric-types.pod | 611 --- S15-unicode.pod | 736 ---- S16-io-OLD.pod | 293 -- S16-io.pod | 469 --- S17-concurrency.pod | 959 ----- S19-commandline.pod | 607 --- S21-calling-foreign-code.pod | 322 -- S22-package-format.pod | 863 ---- S24-testing.pod | 236 -- S27-perl-culture-draft.pod6 | 134 - S28-special-names.pod | 406 -- S29-functions.pod | 1019 ----- S31-pragmatic-modules.pod | 70 - S32-setting-library/Basics.pod | 209 - S32-setting-library/Callable.pod | 135 - S32-setting-library/Containers.pod | 1547 ------- S32-setting-library/Exception.pod | 1367 ------- S32-setting-library/IO-OLD.pod | 1654 -------- S32-setting-library/IO.pod | 1784 -------- S32-setting-library/Numeric.pod | 672 --- S32-setting-library/Rules.pod | 111 - S32-setting-library/Str.pod | 621 --- S32-setting-library/Temporal.pod | 295 -- S99-glossary.pod | 2983 -------------- html/hilite-full.png | Bin 588 -> 0 bytes html/hilite-small.png | Bin 450 -> 0 bytes html/index.html | 410 -- html/perl-with-historical-message.css | 53 - html/perl.css | 291 -- html/style.css | 86 - pod6-files | 7 - v6d.pod | 5 - 46 files changed, 1 insertion(+), 45781 deletions(-) delete mode 100644 S01-overview.pod delete mode 100644 S02-bits.pod delete mode 100644 S03-operators.pod delete mode 100644 S04-control.pod delete mode 100644 S05-regex.pod delete mode 100644 S06-routines.pod delete mode 100644 S07-lists.pod delete mode 100644 S08-capture.pod delete mode 100644 S09-data.pod delete mode 100644 S10-packages.pod delete mode 100644 S11-modules.pod delete mode 100644 S12-objects.pod delete mode 100644 S13-overloading.pod delete mode 100644 S14-roles-and-parametric-types.pod delete mode 100644 S15-unicode.pod delete mode 100644 S16-io-OLD.pod delete mode 100644 S16-io.pod delete mode 100644 S17-concurrency.pod delete mode 100644 S19-commandline.pod delete mode 100644 S21-calling-foreign-code.pod delete mode 100644 S22-package-format.pod delete mode 100644 S24-testing.pod delete mode 100644 S27-perl-culture-draft.pod6 delete mode 100644 S28-special-names.pod delete mode 100644 S29-functions.pod delete mode 100644 S31-pragmatic-modules.pod delete mode 100644 S32-setting-library/Basics.pod delete mode 100644 S32-setting-library/Callable.pod delete mode 100644 S32-setting-library/Containers.pod delete mode 100644 S32-setting-library/Exception.pod delete mode 100644 S32-setting-library/IO-OLD.pod delete mode 100644 S32-setting-library/IO.pod delete mode 100644 S32-setting-library/Numeric.pod delete mode 100644 S32-setting-library/Rules.pod delete mode 100644 S32-setting-library/Str.pod delete mode 100644 S32-setting-library/Temporal.pod delete mode 100644 S99-glossary.pod delete mode 100644 html/hilite-full.png delete mode 100644 html/hilite-small.png delete mode 100644 html/index.html delete mode 100644 html/perl-with-historical-message.css delete mode 100644 html/perl.css delete mode 100644 html/style.css delete mode 100644 pod6-files delete mode 100644 v6d.pod diff --git a/README.md b/README.md index fc2fab34..92071a12 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,2 @@ -Perl 6 Design Documents +Design Documents ======================= - -This repository contains the Perl 6 design documents, also called "Synopses", -in Pod (5 and 6) format. A [regularly updated HTML -version](http://design.perl6.org/) is available. - -Historically, these documents have determined the direction of Perl 6. As -implementations matured, this role shifted (and still shifts) towards -documenting the experience from the implementations. - -Instead the [test suite](https://github.com/perl6/roast/) is becoming the -specification, and the "specs" in the repository name of the design documents -tends to mean "speculations" now. diff --git a/S01-overview.pod b/S01-overview.pod deleted file mode 100644 index d7cf5b18..00000000 --- a/S01-overview.pod +++ /dev/null @@ -1,232 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 1: Overview - -=head1 VERSION - - Created: 10 Aug 2004 - - Last Modified: 11 Feb 2015 - Version: 10 - -This document originally summarized Apocalypse 1, which covers the -initial design concept. That original summary may be found below -under "Random Thoughts". However, these Synopses also contain -updates to reflect the evolving design of Perl 6 over time, unlike -the Apocalypses, which are frozen in time as "historical documents". -These updates are not marked--if a Synopsis disagrees with its -Apocalypse, assume the Synopsis is correct. - -Another assumption has been that if we don't talk about something in these -Synopses, it's the same as it is in Perl 5. Soon we plan to fill in -the gaps with the Perl 5 details though. - -=head1 Project Plan - -Mostly, we're just a bunch of ants all cooperating (sort of) to haul -food toward the nest (on average). There are many groups of people -working on various bits and pieces as they see fit, since this is -primarily a volunteer effort. - -This document does not attempt to summarize all these subprojects--see -L for such information. What we can say here -is that, unlike how it was with Perl 5, none of these projects is -designed to be the Official Perl. Perl 6 is anything that passes the -official test suite. This test suite was initially developed under the -Pugs project because that project was at one point the furthest along -in exploring the high-level semantics of Perl 6. (Other projects -may be better at other things, such as speed or interoperability. -This is fine; it is not necessary that all implementations be equally -good at everything.) The official test suite is community property, -and is intended to be platform neutral, so that Perl 6 is defined -primarily by its desired semantics, not by accidents of history. - -Another aspect of this is the Perl 6 compiler will be self-hosting. -That is, the compiler will eventually compile itself, at least down -to the point where various code-generating backends can take over. -This largely removes platform dependencies from the frontend, so that -only the backends need to worry about platform-specific issues. - -But above all, our project plan is simply to help people find a -spot where they can feel like they're creating the future, both for -themselves and for others. Around here, that's what we call fun. - -=head1 Random Thoughts - -=over 4 - -=item * - -The word "apocalypse" historically meant merely "a revealing", -and we're using it in that unexciting sense. - -=item * - -If you ask for RFCs from the general public, you get a lot of -interesting but contradictory ideas, because people tend to stake -out polar positions, and none of the ideas can build on each other. - -=item * - -Larry's First Law of Language Redesign: Everyone wants the colon. - -=item * - -RFCs are rated on "PSA": whether they point out a real B

roblem, -whether they present a viable Bolution, and whether that solution is -likely to be Bccepted as part of Perl 6. - -=item * - -Languages should be redesigned in roughly the same order as you would -present the language to a new user. - -=item * - -Perl 6 should be malleable enough that it can evolve into the imaginary -perfect language, Perl 7. This darwinian imperative implies support -for multiple syntaxes above and multiple platforms below. - -=item * - -Many details may change, but the essence of Perl will remain unchanged. -Perl will continue to be a multiparadigmatic, context-sensitive -language. We are not turning Perl into any other existing language. - -=item * - -Migration is important. A Perl 6 interpreter, if invoked as "C", will assume that it -is being fed Perl 5 code unless the code starts with a "class" or -"module" keyword, or you specifically tell it you're running Perl 6 -code in some other way, such as by: - - #!/usr/bin/perl6 - use v6.0; - -Also, a file with a C<.p6> extension may be taken as indicative, -as may any other extension containing the digit C<6>, such as C -or C or C or C. (Though C<.pl> and C<.pm> are still -perfectly acceptable extensions as long as the Perl-6-ness is indicated -by one of the other indicators.) - -=item * - -Migration in the other direction is also important. In Perl 6 -mode, one can drop back to Perl 5 mode with C at the -beginning of a lexical block. Such blocks may be nested: - - use v6; - # ...some Perl 6 code... - { - use v5; - # ...some Perl 5 code... - { - use v6; - # ...more Perl 6 code... - } - } - -Some platforms may restrict this to a subset of Perl 5 when it is -not expedient to include a full Perl 5 interpreter. The standard -Perl 6 grammar will include the ability to parse a well-behaved -subset of Perl 5 on its own (much like PPI does); implementations -are required only to support this subset, though of course they may -also choose to implement bug-for-bug compatibility. - -=item * - -Scaling is one of those areas where Perl needs to be multiparadigmatic -and context sensitive. Perl 5 code is not strict by default, while -Perl 6 code is. But it should be easy to relax with C<-e> or the -'no strict' pragma: - - perl -e '$x = 1' - - #!/usr/bin/perl - no strict; - $x = 1; - -=item * - -It must be possible to write policy metamodules that invoke other -modules on the user's behalf. - -=item * - -If you want to treat everything as objects in Perl 6, Perl will help -you do that. If you don't want to treat everything as objects, Perl -will help you with that viewpoint as well. - -=item * - -Operators are just functions with funny names and syntax. - -=item * - -Language designers are still necessary to synthesize unrelated ideas -into a coherent whole. - -=item * - -The language designer is neither omniscient nor omnipotent, and never -will be, despite requests for those particular features. Therefore -the design process will be spiral, cooperative, and convergent. -The rate of convergence is an emergent property, and cannot be forced, -only encouraged. As long as anyone is hacking on any implementation -of Perl 6 to make it conform to the test suite, or hacking on the -test suite to make it reflect consensus of specification, the rate -of convergence will be deemed to be positive. If you are unhappy -with the current rate of convergence, please cooperate more with -someone else you think is interested in convergence. - -=item * - -The spec will not be frozen prematurely, but will continue to solidify -as various aspects of it are proven (or disproven) in various -implementations. Many parts of the spec are already effectively -frozen, or are in a slushy state. "The future is already here, -it's just unevenly distributed." - -=item * - -All specced features that have not been proven in an implementation -should be considered somewhat conjectural, even if not so marked. -As implementations start to agree on what is practical and what is not, -do not be surprised if some features that are currently specced may be -deferred to future versions; these should still be considered long-term -direction in the evolution of Perl 6 over time, and the short-term -design should be conservative in preserving that long-term evolution. -Note that we are not in a hurry to defer any sections of the spec, -even if that would give the illusion of progress. Convergence -of specs and implementations will happen naturally as we get -implementations that are closer to the spec. It is quite likely -that the first practical implementation will largely determine -which features are considered to be required in 6.0.0. - -=item * - -Everyone is allowed to panic I. However, continual panic will -be deemed poisonous. Nobody gets special treatment, even if they -think special treatment is necessary for success. This means you. - -=back - -=head1 About These Documents - -If you are reading the HTML version, it is generated from the POD sources -in the specs repository under L, so edit -it there in the git repository if you would like to make changes. - -=head2 Additions - -Please post errors and feedback to perl6-language. If you are making -a general laundry list, please separate messages by topic. - -=head1 AUTHORS - - Larry Wall - -=for vim:set expandtab sw=4: diff --git a/S02-bits.pod b/S02-bits.pod deleted file mode 100644 index a9a25070..00000000 --- a/S02-bits.pod +++ /dev/null @@ -1,4948 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 2: Bits and Pieces - -=head1 VERSION - - Created: 10 Aug 2004 - - Last Modified: 16 Oct 2015 - Version: 296 - -This document summarizes Apocalypse 2, which covers small-scale lexical -items and typological issues. (These Synopses also contain updates to -reflect the evolving design of Perl 6 over time, unlike the Apocalypses, -which are frozen in time as "historical documents". These updates are not -marked--if a Synopsis disagrees with its Apocalypse, assume the Synopsis is -correct.) - -=head1 One-pass parsing - -To the extent allowed by sublanguages' parsers, Perl is parsed using a -one-pass, predictive parser. That is, lookahead of more than one "longest -token" is discouraged. The currently known exceptions to this are where the -parser must: - -=over 4 - -=item * - -Locate the end of interpolated expressions that begin with a sigil and might -or might not end with brackets. - -=item * - -Recognize that a reduce operator is not really beginning a C<[...]> -composer. - -=back - -One-pass parsing is fundamental to knowing exactly which language you are -dealing with at any moment, which in turn is fundamental to allowing -unambiguous language mutation in any desired direction. (Generic languages -are allowed, but only if intended; accidentally generic languages lead to -loss of linguistic identity and integrity. This is the hard lesson of -Perl 5's source filters and other multi-pass parsing mistakes.) - -=head1 Lexical Conventions - -=head2 Unicode Semantics - -In the abstract, Perl is written in Unicode, and has consistent Unicode -semantics regardless of the underlying text representations. By default -Perl presents Unicode in "NFG" formation, where each grapheme counts as one -character. A grapheme is what the novice user would think of as a character -in their normal everyday life, including any diacritics. - -Perl can count Unicode line and paragraph separators as line markers, but -that behavior had better be configurable so that Perl's idea of line numbers -matches what your editor thinks about Unicode lines. - -Unicode horizontal whitespace is counted as whitespace, but it's better not -to use thin spaces where they will make adjoining tokens look like a single -token. On the other hand, Perl doesn't use indentation as syntax, so you -are free to use any amount of whitespace anywhere that whitespace makes -sense. Comments always count as whitespace. - -=head2 Bracketing Characters - -For some syntactic purposes, Perl distinguishes bracketing characters from -non-bracketing. Bracketing characters are defined as any Unicode characters -with either bidirectional mirrorings or Ps/Pe/Pi/Pf properties. - -In practice, though, you're safest using matching characters with -Ps/Pe/Pi/Pf properties, though ASCII angle brackets are a notable exception, -since they're bidirectional but not in the Ps/Pe/Pi/Pf sets. - -Characters with no corresponding closing character do not qualify as opening -brackets. This includes the second section of the Unicode BidiMirroring -data table. - -If a character is already used in Ps/Pe/Pi/Pf mappings, then any entry in -BidiMirroring is ignored (both forward and backward mappings). For any -given Ps character, the next Pe codepoint (in numerical order) is assumed to -be its matching character even if that is not what you might guess using -left-right symmetry. Therefore C (C<⦍>) maps to C (C<⦎>), not C (C<⦐>), -and C (C<⦏>) maps to C (C<⦐>), not C (C<⦎>). Neither C (C<⦎>) nor -C (C<⦐>) are valid bracket openers, despite having reverse mappings in the -BidiMirroring table. - -The C (C<〝>) codepoint has two closing alternatives, C (C<〞>) and -C (C<〟>); Perl 6 only recognizes the one with lower code point number, -C (C<〞>), as the closing brace. This policy also applies to new -one-to-many mappings introduced in the future. - -However, many-to-one mappings are fine; multiple opening characters may map -to the same closing character. For instance, C (C<‘>), C (C<‚>), and -C (C<‛>) may all be used as the opener for the C (C<’>) closer. -Constructs that count openers and closers assume that only the given opener -is special. That is, if you open with one of the alternatives, all other -alternatives are treated as non-bracketing characters within that construct. - -=head2 Multiline Comments - -Pod sections may be used reliably as multiline comments in Perl 6. Unlike -in Perl 5, Pod syntax now lets you use C<=begin comment> and C<=end comment> -to delimit a Pod block correctly without the need for C<=cut>. (In fact, -C<=cut> is now gone.) The format name does not have to be C -- any -unrecognized format name will do to make it a comment. (However, bare -C<=begin> and C<=end> probably aren't good enough, because all comments in -them will show up in the formatted output.) - -We have single paragraph comments with C<=for comment> as well. That lets -C<=for> keep its meaning as the equivalent of a C<=begin> and C<=end> -combined. As with C<=begin> and C<=end>, a comment started in code reverts -to code afterwards. - -Since there is a newline before the first C<=>, the Pod form of comment -counts as whitespace equivalent to a newline. See S26 for more on embedded -documentation. - -=head2 Single-line Comments - -Except within a quote literal, a C<#> character always introduces a comment -in Perl 6. There are two forms of comment based on C<#>. Embedded comments -require the C<#> to be followed by a backtick (C<`>) plus one or more -opening bracketing characters. - -All other uses of C<#> are interpreted as single-line comments that work -just as in Perl 5, starting with a C<#> character and ending at the -subsequent newline. They count as whitespace equivalent to newline for -purposes of separation. Unlike in Perl 5, C<#> may I be used as the -delimiter in quoting constructs. - -=head2 Embedded Comments - -Embedded comments are supported as a variant on quoting syntax, introduced -by C<#`> plus any user-selected bracket characters (as defined in -L above): - - say #`( embedded comment ) "hello, world!"; - - $object\#`{ embedded comments }.say; - - $object\ #`「 - embedded comments - 」.say; - -Brackets may be nested, following the same policy as ordinary quote -brackets. - -There must be no space between the C<#`> and the opening bracket character. -(There may be the I of space for some double-wide -characters, however, such as the corner quotes above.) - -For multiline comments it is recommended (but not required) to use two or -more brackets both for visual clarity and to avoid relying too much on -internal bracket counting heuristics when commenting code that may -accidentally miscount single brackets: - - #`{{ - say "here is an unmatched } character"; - }} - -However, it's sometimes better to use Pod comments because they are -implicitly line-oriented. - -=head2 User-selected Brackets - -For all quoting constructs that use user-selected brackets, you can open -with multiple identical bracket characters, which must be closed by the same -number of closing brackets. Counting of nested brackets applies only to -pairs of brackets of the same length as the opening brackets: - - say #`{{ - This comment contains unmatched } and { { { { (ignored) - Plus a nested {{ ... }} pair (counted) - }} q<< <> >> # says " <> " - -Note however that bare circumfix or postcircumfix C<<< <<...>> >>> is not a -user-selected bracket, but the ASCII variant of the C<< «...» >> -interpolating word list. Only C<#`> and the C-style quoters (including -C, C, C

, and C) enable subsequent user-selected brackets. - -=head2 Unspaces - -Some languages such as C allow you to escape newline characters to combine -lines. Other languages (such as regexes) allow you to backslash a space -character for various reasons. Perl 6 generalizes this notion to any kind -of whitespace. Any contiguous whitespace (including comments) may be hidden -from the parser by prefixing it with C<\>. This is known as the "unspace". -An unspace can suppress any of several whitespace dependencies in Perl. For -example, since Perl requires an absence of whitespace between a noun and a -postfix operator, using unspace lets you line up postfix operators: - - %hash\ {$key} - @array\ [$ix] - $subref\($arg) - -As a special case to support the use above, a backslash where a postfix is -expected is considered a degenerate form of unspace. Note that whitespace -is not allowed before that, hence - - $subref \($arg) - -is a syntax error (two terms in a row). And - - foo \($arg) - -will be parsed as a list operator with a C argument: - - foo(\($arg)) - -However, other forms of unspace may usefully be preceded by whitespace. -(Unary uses of backslash may therefore never be followed by whitespace or -they would be taken as an unspace.) - -Other postfix operators may also make use of unspace: - - $number\ ++; - $number\ --; - 1+3\ i; - $object\ .say(); - $object\#`{ your ad here }.say - -Another normal use of a you-don't-see-this-space is typically to put a -dotted postfix on the next line: - - $object\ # comment - .say - - $object\#`[ comment - ].say - - $object\ - .say - -But unspace is mainly about language extensibility: it lets you continue the -line in any situation where a newline might confuse the parser, regardless -of your currently installed parser. (Unless, of course, you override the -unspace rule itself...) - -Although we say that the unspace hides the whitespace from the parser, it -does not hide whitespace from the lexer. As a result, unspace is not -allowed within a token. Additionally, line numbers are still counted if the -unspace contains one or more newlines. Since Pod chunks count as whitespace -to the language, they are also swallowed up by unspace. Heredoc boundaries -are suppressed, however, so you can split excessively long lines introducing -heredocs like this: - - ok(q:to'CODE', q:to'OUTPUT', \ - "Here is a long description", \ # --more-- - todo(:parrøt<0.42>, :dötnet<1.2>)); - ... - CODE - ... - OUTPUT - -To the heredoc parser that just looks like: - - ok(q:to'CODE', q:to'OUTPUT', "Here is a long description", todo(:parrøt<0.42>, :dötnet<1.2>)); - ... - CODE - ... - OUTPUT - -Note that this is one of those cases in which it is fine to have whitespace -before the unspace, since we're only trying to suppress the newline -transition, not all whitespace as in the case of postfix parsing. (Note -also that the example above is not meant to spec how the test suite works. ) - -=head2 Comments in Unspaces and vice versa - -An unspace may contain a comment, but a comment may not contain an unspace. -In particular, end-of-line comments do not treat backslash as significant. -If you say: - - #`\ (... - -or - - #\ `(... - -it is an end-of-line comment, not an embedded comment. Write: - - \ #`( - ... - ) - -to mean the other thing. - -=head2 Unspace disallowed within regexes - -Within a regex, unspace is disallowed as too ambiguous with customary -backslashing conventions in surrounding cultures. Hence you must write an -explicit whitespace match some other way, such as with quotes or with a -C<\x20> or C<\c32> escape. On the other hand, while an unspace can start -with C<\#> in normal code, C<\#> within a regex is specifically allowed, and -is not taken as unspace, but matches a literal C (NUMBER SIGN). (Within -a character class, you may also escape whitespace with a backslash; the -restriction on unspace applies only at the normal pattern-matching level.) - -=head2 Optional Whitespace and Exclusions - -In general, whitespace is optional in Perl 6 except where it is needed to -separate constructs that would be misconstrued as a single token or other -syntactic unit. (In other words, Perl 6 follows the standard -I principle, or in the cases of large constructs, a I principle. See L below for -more on how a Perl program is analyzed into tokens.) - -This is an unchanging deep rule, but the surface ramifications of it change -as various operators and macros are added to or removed from the language, -which we expect to happen because Perl 6 is designed to be a mutable -language. In particular, there is a natural conflict between postfix -operators and infix operators, either of which may occur after a term. If a -given token may be interpreted as either a postfix operator or an infix -operator, the infix operator requires space before it. Postfix operators -may never have intervening space, though they may have an intervening dot. -If further separation is desired, an unspace or embedded comment may be used -as described above, as long as no whitespace occurs outside the unspace or -embedded comment. - -For instance, if you were to add your own C<< infix:<++> >> operator, then -it must have space before it. The normal autoincrementing C<< postfix:<++> ->> operator may never have space before it, but may be written in any of -these forms: - - $x++ - - $x\++ - - $x.++ - - $x\ ++ - - $x\ .++ - - $x\#`( comment ).++ - $x\#`((( comment ))).++ - - $x\ - .++ - - $x\ # comment - # inside unspace - .++ - - $x\ # comment - # inside unspace - ++ # (but without the optional postfix dot) - - $x\#`『 comment - more comment - 』.++ - - $x\#`[ comment 1 - comment 2 - =begin Podstuff - whatever (Pod comments ignore current parser state) - =end Podstuff - comment 3 - ].++ - -=head3 Implicit Topical Method Calls - -A consequence of the postfix rule is that (except when delimiting a quote or -terminating an unspace) a dot with whitespace in front of it is always -considered a method call on C<$_> where a term is expected. If a term is -not expected at this point, it is a syntax error. (Unless, of course, there -is an infix operator of that name beginning with dot. You could, for -instance, define a Fortranly C<< infix:<.EQ.> >> if the fit took you. But -you'll have to be sure to always put whitespace in front of it, or it would -be interpreted as a postfix method call instead.) - -For example, - - foo .method - -and - - foo - .method - -will always be interpreted as - - foo $_.method - -but never as - - foo.method - -Use some variant of - - foo\ - .method - -if you mean the postfix method call. - -One consequence of all this is that you may no longer write a Num as C<42.> -with just a trailing dot. You must instead say either C<42> or C<42.0>. In -other words, a dot following a number can only be a decimal point if the -following character is a digit. Otherwise the postfix dot will be taken to -be the start of some kind of method call syntax. (The C<.123> form with a -leading dot is still allowed however when a term is expected, and is -equivalent to C<0.123> rather than C<$_.123>.) - -=head2 Keywords and whitespace - -One other spot where whitespace makes a difference is after various -keywords, such as control flow or other statement-oriented keywords. Such -keywords require whitespace after them. (Again, this is in the interests of -extensibility). So for instance, if you define a symbol that happens to be -the same as the keyword C, you can still use it as a non-keyword, as -long as you don't put whitespace after it: - - my \if = 42; say (if) if if; # prints 42 - -Here only the middle if of the second statement is taken as a keyword -because it has whitespace after it. The other mentions of C do not, and -would be illegal were it not that the symbol is defined in this scope. If -you omit the definition, you'd get a message like this: - - Whitespace required after keyword 'if' - at myfile:1 - ------> say (if⏏) if if; - Undeclared routine: - if used at line 1 - -=head1 Built-In Data Types - -Perl 6 has an optional type system that helps you write safer code that -performs better. The compiler is free to infer what type information it can -from the types you supply, but it will not complain about missing type -information unless you ask it to. - -Perl 6 is an OO engine, but you're not generally required to think in OO -when that's inconvenient. However, some built-in concepts such as -filehandles are more object-oriented in a user-visible way than in Perl 5. - -=head2 The P6opaque Datatype - -In support of OO encapsulation, there is a new fundamental data -representation: B. External access to opaque objects is always -through method calls, even for attributes. - -=head2 Name Equivalence of Types - -Types are officially compared using name equivalence rather than structural -equivalence. However, we're rather liberal in what we consider a name. For -example, the name includes the version and authority associated with the -module defining the type (even if the type itself is "anonymous"). Beyond -that, when you instantiate a parametric type, the arguments are considered -part of the "long name" of the resulting type, so one C is -equivalent to another C. (Another way to look at it is that -the type instantiation "factory" is memoized.) Typename aliases are -considered equivalent to the original type. In particular, the C syntax is just sugar for C, which is the canonical form -of an instantiated generic type. - -This name equivalence of parametric types extends only to parameters that -can be considered immutable (or that at least can have an immutable snapshot -taken of them). Two distinct classes are never considered equivalent even -if they have the same attributes because classes are not considered -immutable. - -=head2 Properties on Objects - -Perl 6 supports the notion of B on various kinds of objects. -Properties are like object attributes, except that they're managed by the -individual object rather than by the object's class. - -According to S12, properties are actually implemented by a kind of mixin -mechanism, and such mixins are accomplished by the generation of an -individual anonymous class for the object (unless an identical anonymous -class already exists and can safely be shared). - -=head3 Traits - -Properties applied to objects constructed at compile-time, such as variables -and classes, are also called B. Traits cannot be changed at -run-time. Changes to run-time properties are done via mixin instead, so -that the compiler can optimize based on declared traits. - -=head2 Types as Constraints - -A variable's type is a constraint indicating what sorts of values the -variable may contain. More precisely, it's a promise that the object or -objects contained in the variable are capable of responding to the methods -of the indicated "role". See S12 for more about roles. - - # $x can contain only Int objects - my Int $x; - -=head2 Container Types - -A variable may itself be bound to a container type that specifies how the -container works, without specifying what kinds of things it contains. - - # $x is implemented by the MyScalar class - my $x is MyScalar; - -Constraints and container types can be used together: - - # $x can contain only Int objects, - # and is implemented by the MyScalar class - my Int $x is MyScalar; - -Note that C<$x> is also initialized to the C type object. See below -for more on this. - -=head2 Nil - -There is a special value named C. It means "there is no value here". -It is a little bit like the empty C<()> list, insofar as both represent an -absence of values, except that C<()> is defined and means "there are 0 -arguments here if you're counting that low". The C value represents -the absence of a value where there I be one, so it does not -disappear in list context, but relies on something downstream to catch it or -blow up. C also indicates a failed match. - -Since method calls are performed directly on any object, C can respond -to certain method calls. C returns C (whereas -C<().defined> returns C). C also returns C. -C always returns C. C and C return -C<'Nil'>. C and C throw a resumable warning that -returns a value of C<''> on resumption. C likewise throws a -resumable warning that returns 0 on resumption. Any undefined method call -on C returns C, so that C propagates down method call chains. -Likewise any subscripting operation on C returns C. - -Any attempt to change the C value should cause an exception to be -thrown. - -Assigning C to any scalar container causes the container to throw out -any contents and restore itself to an uninitialized state (after which it -will appear to contain an object appropriate to the declared default of the -container, where C is the default default; the element may be simply -deleted if that's how the default can be represented in the structure). -Binding of C with C<:=> simply puts Nil in the container. However, -binding C to a parameter (C<::=> semantics) works more like assignment; -passing C to a parameter with a default causes that parameter to be set -to its default value rather than an undefined value, as if the argument had -not been supplied. - -Assigning C to any entire composite container (such as an C or -C) empties the container, resetting it back to an uninitialized state. -The container object itself then becomes undefined. (Assignment of C<()> -leaves it defined.) - -=head2 Type Objects - -C by itself does not automatically call a C constructor. -It merely assigns an undefined C prototype object to C<$spot>: - - my Dog $spot; # $spot is initialized with ::Dog - my Dog $spot = Dog; # same thing - - $spot.defined; # False - say $spot; # "Dog()" - -Any type name used as a value is the undefined prototype object of that -type, or I for short. See S12 for more on that. - -Any type name in rvalue context is parsed as a single type value and expects -no arguments following it. However, a type object responds to the function -call interface, so you may use the name of a type with parentheses as if it -were a function, and any argument supplied to the call is coerced to the -type indicated by the type object. If there is no argument in the -parentheses, the type object returns itself: - - my $type = Num; # type object as a value - $num = $type($string) # coerce to Num - -To get a real C object, call a constructor method such as C: - - my Dog $spot .= new; - my Dog $spot = $spot.new; # .= is rewritten into this - -You can pass in arguments to the constructor as well: - - my Dog $cerberus .= new(heads => 3); - my Dog $cerberus = $cerberus.new(heads => 3); # same thing - -Just like L, type objects do not disappear in list context, but rely -on something downstream to catch it or blow up. This allows type objects to -be assigned to scalars, but to disappear in non-scalar contexts. - -=head2 Coercive type declarations - -The parenthesized form of type coercion may be used in declarations where it -makes sense to accept a wider set of types but coerce them to a narrow type. -(This only works for one-way coercion, so you may not declare any C -parameter with a coercive type.) The type outside the parens indicates the -desired end result, and subsequent code may depend on it being that type. -The type inside the parens indicates the acceptable set of types that are -allowed to be bound or assigned to this location via coercion. If the wide -type is omitted, C is assumed. In any case, the wide type is only -indicative of permission to coerce; there must still be an available -coercion routine from the wide type to the narrow type to actually perform -the coercion. - - sub foo (Str(Any) $y) {...} - sub foo (Str() $y) {...} # same thing - - my Num(Cool) $x = prompt "Gimme a number"; - -Coercions may also be specified on the return type: - - sub bar ($x, $y --> Int()) { return 3.5 } # returns 3 - -=head2 Containers of Native Types - -If you say - - my int @array is MyArray; - -you are declaring that the elements of C<@array> are native integers, but -that the array itself is implemented by the C class. Untyped -arrays and hashes are still perfectly acceptable, but have the same -performance issues they have in Perl 5. - -=head2 Methods on Arrays - -To get the number of elements in an array, use the C<.elems> method. You -can also ask for the total string length of an array's elements, in -codepoints or graphemes, using these methods, C<.codes> or C<.chars> -respectively on the array. The same methods apply to strings as well. -(Note that C<.codes> is not well-defined unless you know which -canonicalization is in effect. Hence, it allows an optional argument to -specify the meaning exactly if it cannot be known from context.) - -There is no C<.length> method for either arrays or strings, because -C does not specify a unit. - -=head2 Built-in Type Conventions - -Built-in object types start with an uppercase letter. This includes -immutable types (e.g. C, C, C, C, C, C, -C, C, C, C), as well as mutable (container) -types, such as C, C, C, C, C, C, -and non-instantiable Roles such as C and C. - -Non-object (native) types are lowercase: C, C, C, C, -C, C. Native types are primarily intended for declaring compact -array storage, that is, a sequence of storage locations of the specified -type laid out in memory contiguously without pointer indirection. However, -Perl will try to make those look like their corresponding uppercase types if -you treat them that way. (In other words, it does autoboxing and -autounboxing as necessary. Note, however, that repeated autoboxing and -unboxing can make your program much slower, compared to a program that makes -consistent use of either native types or object types.) - -=head3 The C<.WHICH> Method for Value Types - -Some object types can behave as value types. Every object can produce a -"WHICH" value that uniquely identifies the object for hashing and other -value-based comparisons. Normal objects use some kind of unique ID as their -identity, but if a class wishes to behave as a value type, it can define a -C<.WHICH> method that makes different objects look like the same object if -they happen to have the same contents. - -=head3 The C Type - -When we say that a normal object uses its location as its identity, we do -I mean that it returns its address as a number. In the first place, -not all objects are in the same memory space (see the literature on NUMA, -for instance), and two objects should not accidentally have the same -identity merely because they were stored at the same offset in two different -memory spaces. We also do not want to allow accidental identity collisions -with values that really are numbers (or strings, or any other mundane value -type). Nor should we be encouraging people to think of object locations -that way in any case. So C still returns a value rather than another -object, but that value must be of a special C type that prevents -accidental confusion with normal value types, and at least discourages -trivial pointer arithmetic. - -Certainly, it is difficult to give a unique name to every possible address -space, let alone every possible address within every such a space. In the -absence of a universal naming scheme, it can only be made improbable that -two addresses from two different spaces will collide. A sufficiently large -random number may represent the current address space on output of an -C to a different address space, or if serialized to YAML or XML. -(This extra identity component need not be output for debugging messages -that assume the current address space, since it will be the same big number -consistently, unless your process really is running under a NUMA.) - -Alternately, if an object is being serialized to a form that does not -preserve object identity, there is no requirement to preserve uniqueness, -since in this case the object is really being translated to a value type -representation, and reconstituted on the other end as a different unique -object. - -=head2 Variables Containing Undefined Values - -A variable with a non-native type constraint may contain an I -value such as a type object, provided the undefined value meets the type -constraint. - - my Int $x = Int; # works - my Buf $x = Buf8; # works - -Variables with native types do not support undefinedness: it is an error to -assign an undefined value to them: - - my int $y = Int; # dies - -Since C can support the value C but not the general concept of -undefinedness, you can coerce an undefined value like this: - - my num $n = computation() // NaN; - -Variables of non-native types start out containing a type object of the -appropriate type unless explicitly initialized to a defined value. - -Any container's default may be overridden by the C trait. -If the container's contents are deleted, the value is notionally set to the -provided default value; this value may or may not be physically represented -in memory, depending on the implementation of the container. You should -officially not care about that (much). - -=head2 The C Method - -Every object supports a C function/method that returns the metaclass -instance managing it, regardless of whether the object is defined: - - 'x'.HOW.methods('x'); # get available methods for strings - Str.HOW.methods(Str); # same thing with the prototype object Str - HOW(Str).methods(Str); # same thing as function call - - 'x'.methods; # this is likely an error - not a meta object - Str.methods; # same thing - -(For a prototype system (a non-class-based object system), all objects are -merely managed by the same meta object.) - -=head2 Roles - -Perl supports generic types through what are called "roles" which represent -capabilities or interfaces. These roles are generally not used directly as -object types. For instance all the numeric types perform the C -role, and all string types perform the C role, but there's no such -thing as a "Numeric" object, since these are generic types that must be -instantiated with extra arguments to produce normal object types. Common -roles include: - - Stringy - Numeric - Real - Integral - Rational - Callable - Positional - Associative - Buf - Blob - -=head2 C Types - -Perl 6 intrinsically supports big integers and rationals through its system -of type declarations. C automatically supports promotion to arbitrary -precision, as well as holding C and C values. Note that C -assumes 2's complement arithmetic, so C<+^1 == -2> is guaranteed. (Native -C operations need not support this on machines that are not natively -2's complement. You must convert to and from C to do portable bitops -on such ancient hardware.) - -C must support the largest native floating point format that runs at -full speed. It may be bound to an arbitrary precision type, but by default -it is the same type as a native C. See below. - -C supports extended precision rational arithmetic. Dividing two -C objects using C<< infix: >> produces a C, which is -generally usable anywhere a C is usable, but may also be explicitly -cast to C. (Also, if either side is C already, C<< infix: >> -gives you a C instead of a C.) - -C and C both do the C role. - -Lowercase types like C and C imply the native machine -representation for integers and floating-point numbers, respectively, and do -not promote to arbitrary precision, though larger representations are always -allowed for temporary values. Unless qualified with a number of bits, -C and C types represent the largest native integer and -floating-point types that run at full speed. - -Because temporary values are biased in favor of correct semantics over -compact storage, native numeric operators that might overflow must come in -two variants, one which returns a guaranteed correct boxed value, and one of -which returns a guaranteed fast native value. By default the boxing variant -is selected (probably by virtue of hiding the native variants), but within a -given lexical scope, the C pragma will allow use of the -dangerous but fast variants instead. Arguments to the pragma can be more -specific about what types of return values are allowed, e.g. C and such. (The optimizer is also allowed to substitute such -variants when it can determine that the final destination would store -natively in any case, or that the variant could not possibly malfunction -given the arguments.) [Conjecture: we could allow an 'N' metaoperator to -select the native variant on a case by case basis.] - -Numeric values in untyped variables use C and C semantics rather -than C and C. Literals, on the other hand, may default to native -storage formats if they reasonably can. We rely on the semantics of boxing -temporary values by default (see above) to maintain correct semantics; the -optimizer is of course allowed to box or unbox a literal at compile time (or -cache a boxed/unboxed version of the value) whenever it seems appropriate. -In any case, native literals should be preferred under C -semantics. - -For pragmatic reasons, C values are guaranteed to be exact only up to a -certain point. By default, this is the precision that would be represented -by the C type, which is an alias for C, which -has a numerator of C but is limited to a denominator of C -(which may or may not be implemented as a native C, since small -representations may be desirable for small denominators). A C that -would require more than 64 bits of storage in the denominator is -automatically converted either to a C or to a lesser-precision C, -at the discretion of the implementation. (Native types such as C -limit the size of both numerator and denominator, though not to the same -size. The numerator should in general be twice the size of the denominator -to support user expectations. For instance, a C actually supports -C, allowing numbers like C<100.01> to be represented, -and a C, defined as C, can hold the number -of seconds since the Big Bang with attosecond precision. Though perhaps not -with attosecond accuracy...) - -The limitation on C values is intended to be enforced only on -user-visible types. Intermediate values used in the internal calculations -of C operators may exceed this precision, or represent negative -denominators. That is, the temporaries used in calculating the new -numerator and denominator are (at least in the abstract) of C type. -After a new numerator and denominator are determined, any sign is forced to -be represented only by the numerator. Then if the denominator exceeds the -storage size of the unsigned integer used, the fraction is reduced via GCD. -If the resulting denominator is still larger than the storage size, then and -I then may the precision be reduced to fit into a C or C. - -C addition and subtraction should attempt to preserve the denominator -of the more precise argument if that denominator is an integral multiple of -the less precise denominator. That is, in practical terms, adding a column -of dollars and cents should generally end up with a result that has a -denominator of 100, even if values like 42 and 3.5 were added in. With -other operators, this guarantee cannot be made; in such cases, the user -should probably be explicitly rounding to a particular denominator anyway. - -For applications that really need arbitrary precision denominators as well -as numerators at the cost of performance, C may be used, which is -defined as C, that is, as arbitrary precision in both -parts. There is no literal form for a C, so it must be constructed -using C. In general, only math operators with at least -one C argument will return another C, to prevent accidental -promotion of reasonably fast C values into arbitrarily slow C -values. - -Although most rational implementations normalize or "reduce" fractions to -their smallest representation immediately through a GCD algorithm, Perl -allows a rational datatype to do so lazily at need, such as whenever the -denominator would run out of precision, but avoid the overhead otherwise. -Hence, if you are adding a bunch of Cs that represent, say, dollars and -cents, the denominator may stay 100 the entire way through. The C<.nu> and -C<.de> methods will return these unreduced values. You can use -C<$rat.=norm> to normalize the fraction. (This also forces the sign on the -denominator to be positive.) The C<.perl> method will produce a decimal -number if the denominator is a power of 10, or normalizable to a power of 10 -(that is, having factors of only 2 and 5 (and -1)). Otherwise it will -normalize and return a rational literal of the form C<< <-47/3> >>. -Stringifying a rational via C<.gist> or C<.Str> returns an exact decimal -number if possible, and otherwise rounds off the repeated decimal based on -the size of the denominator. For full details see the documentation of -C in S32. - -C and C both produce valid C literals, so they must -include the C for the exponential. - - say 1/5; # 0.2 exactly - say 1/3; # 0.333333 - - say <2/6>.perl - # <1/3> - - say 3.14159_26535_89793 - # 3.141592653589793 including last digit - - say 111111111111111111111111111111111111111111111.123 - # 111111111111111111111111111111111111111111111.123 - - say 555555555555555555555555555555555555555555555/5 - # 111111111111111111111111111111111111111111111 - - say <555555555555555555555555555555555555555555555/5>.perl - # 111111111111111111111111111111111111111111111.0 - say 2e2; # 200e0 or 2e2 or 200.0e0 or 2.0e2 - -=head2 Infinity and C - -Perl 6 by default makes standard IEEE floating point concepts visible, such -as C (infinity) and C (not a number). Within a lexical scope, -pragmas may specify the nature of temporary values, and how floating point -is to behave under various circumstances. All IEEE modes must be lexically -available via pragma except in cases where that would entail heroic efforts -to bypass a braindead platform. - -The default floating-point modes do not throw exceptions but rather -propagate C and C. The boxed object types may carry more detailed -information on where overflow or underflow occurred. Numerics in Perl are -not designed to give the identical answer everywhere. They are designed to -give the typical programmer the tools to achieve a good enough answer most -of the time. (Really good programmers may occasionally do even better.) -Mostly this just involves using enough bits that the stupidities of the -algorithm don't matter much. - -=head2 Strings, the C Type - -A C type is a Unicode string object. It boxes a native C (the -difference being in representation; a C is a P6opaque and as such you -may mix in to it, but this is not possible with a C). A C functions -at grapheme level. This means that `.chars` should give the number of -graphemes, `.substr` should never cut a combining character in two, and so -forth. Both C and C are immutable. Their exact representation in -memory is implementation defined, so implementations are free to use ropes -or other data structures internally in order to make concatenation, substring, -and so forth cheaper. - -Implementation note: since Perl 6 mandates that C must view graphemes -as the fundamental unit rather than codepoints, this has some implications -regarding efficient implementation. It is suggested that all graphemes be -translated on input to unique grapheme numbers and represented as integers -within some kind of uniform array for fast substr access. For those -graphemes that have a precomposed form, use of that codepoint is suggested. -(Note that this means Latin-1 can still be represented internally with 8-bit -integers.) - -For graphemes that have no precomposed form, a temporary private id should -be assigned that uniquely identifies the grapheme. If such ids are assigned -consistently throughout the process, comparison of two graphemes is no more -difficult than the comparison of two integers, and comparison of base -characters no more difficult than a direct lookup into the id-to-NFD table. - -Obviously, any temporary grapheme ids must be translated back to some -universal form (such as NFD) on output, and normal precomposed graphemes may -turn into either NFC or NFD forms depending on the desired output. -Maintaining a particular grapheme/id mapping over the life of the process -may have some GC implications for long-running processes, but most processes -will likely see a limited number of non-precomposed graphemes. - -Code wishing to work at a codepoint level instead of a grapheme level -should use the C type, which has subclasses representing the various -Unicode normalization forms (namely, C, C, C, and C). -Note that C is defined as a codepoint level operation. Even though the -C may contain synthetics internally, these should never be exposed by -C; instead, the behaviour should be as if the C had been converted -to an C and then the first element accessed (obviously, implementations -are free to do something far more efficient). - -=head2 The C Type - -A C is a stringish view of an array of integers, and has no Unicode or -character properties without explicit conversion to some kind of C. -(The C, C, C, and C types are the native -counterparts; native buf types are required to occupy contiguous memory for -the entire buffer.) Typically a C is an array of bytes serving as a -buffer. Bitwise operations on a C treat the entire buffer as a single -large integer. Bitwise operations on a C generally fail unless the -C in question can provide an abstract C interface somehow. -Coercion to C should generally invalidate the C interface. As a -generic role C may be instantiated as any of C, C, or -C (or as any type that provides the appropriate C interface), -but when used to create a buffer C is punned to a class implementing -C (actually C). - -Unlike C types, C types prefer to deal with integer string -positions, and map these directly to the underlying compact array as -indices. That is, these are not necessarily byte positions--an integer -position just counts over the number of underlying positions, where one -position means one cell of the underlying integer type. Builtin string -operations on C types return integers and expect integers when dealing -with positions. As a limiting case, C is just an old-school byte -string, and the positions are byte positions. Note, though, that if you -remap a section of C memory to be C, you'll have to multiply -all your positions by 4. - -=head3 Native C Types - -These native types are defined based on the C role, parameterized by -the native integer type it is composed of: - - Name Is really - ==== ========= - buf1 Buf[bit] - buf8 Buf[uint8] - buf16 Buf[uint16] - buf32 Buf[uint32] - buf64 Buf[uint64] - -There are no signed buf types provided as built-ins, but you may say - - Buf[int8] - Buf[int16] - Buf[int32] - Buf[int64] - -to get buffers of signed integers. It is also possible to define a C -based on non-integers or on non-native types: - - Buf[complex64] - Buf[FatRat] - Buf[Int] - -However, no guarantee of memory contiguity can be made for non-native types. - -=head2 The C Object - -The C<*> character as a standalone term captures the notion of "Whatever", -the meaning of which can be decided lazily by whatever it is an argument to. -Alternately, for those unary and binary operators that don't care to handle -C<*> themselves, it is automatically primed at compile time into a closure -that takes one or two arguments. (See below.) - -Generally, when an operator handles C<*> itself, it can often be thought of -as a "glob" that gives you everything it can in that argument position. For -instance, here are some operators that choose to handle C<*> and give it -special meaning: - - if $x ~~ 1..* {...} # if 1 <= $x <= +Inf - my ($a,$b,$c) = "foo" xx *; # an arbitrary long list of "foo" - if /foo/ ff * {...} # a latching flipflop - @slice = @x[*;0;*]; # all indexes for 1st and 3rd dimensions - @slice = %x{*;'foo'}; # all keys in domain of 1st dimension - @array[*] # list of all values, unlike @array[] - (*, *, $x) = (1, 2, 3); # skip first two elements - # (same as lvalue "undef" in Perl 5) - -C is an undefined prototype object derived from C. As a type -it is abstract, and may not be instantiated as a defined object. When used -for a particular MMD dispatch, and nothing in the MMD system claims it, it -dispatches to as an C with an undefined value, and (we hope) blows up -constructively. - -Since the C object is effectively immutable, the optimizer is free -to recognize C<*> and optimize in the context of what operator it is being -passed to. An operator can declare that it wants to handle C<*> either by -declaring one or more of its arguments for at least one of its candidates -with an argument of type C, or by marking the proto sub with the -trait, C. [Conjecture: actually, this is -negotiable--we might shorten it to C or some such. -C<:-)>] - -=head3 Autopriming of Unary and Binary Operators with Whatever - -Perl 6 has several ways of performing partial function application. Since -this is an unwieldy term, we've settled on calling it I. (Many -folks call this "currying", but that's not really a correct technical usage -of the term.) Most generally, priming is performed on a C object -by calling its C<.assuming> method, described elsewhere. This section is -about a convenient syntactic sugar for that. - -For any unary or binary operator (specifically, any prefix, postfix, and -infix operator), if the operator has not specifically requested (via -signature matching) to handle C<*> itself, the compiler is required to -translate directly to an appropriately primed closure at compile time. We -call this I. Most of the built-in numeric operators fall into -this category. So: - - * - 1 - '.' x * - * + * - -are autoprimed into closures of one or two arguments: - - { $^x - 1 } - { '.' x $^y } - { $^x + $^y } - -This rewrite happens after variables are looked up in their lexical scope, -and after declarator install any variables into the lexical scope, with the -result that - - * + (state $s = 0) - -is effectively primed into: - - -> $x { $x + (state $OUTER::s = 0) } - -rather than: - - -> $x { $x + (state $s = 0) } - -In other words, C<*> priming does not create a useful lexical scope. -(Though it does have a dynamic scope when it runs.) This prevents the -semantics from changing drastically if the operator in question suddenly -decides to handle C itself. - -As a postfix operator, a method call is one of those operators that is -automatically primed. Something like: - - *.meth(1,2,3) - -is rewritten as: - - { $^x.meth(1,2,3) } - -In addition to priming a method call without an invocant, such primed -methods are handy anywhere a smartmatcher is expected: - - @primes = grep *.is-prime, 2..*; - subset Duck where *.^can('quack'); - when !*.defined {...} - -Metaoperators are treated as normal operators; the autopriming does not -automatically distribute to the inner operator. For example, - - @array X* * - -does not make a list of closures, but is equivalent to - - -> $arg { @array X* $arg } - -Postcircumfixes (with or without the dot) are also autoprimed, so we have - - *[$x] -> @a { @a[$x] } - *{$x} -> %h { %h{$x} } - * -> %h { %h } - *($x) -> &c { &c($x) } - -=head3 The C Types - -These returned closures are of type C or -C rather than type C, so constructs that do -want to handle C<*> or its derivative closures can distinguish them by type: - - @array[*] # subscript is type Whatever, returns all elements - @array[*-1] # subscript is type WhateverCode:($), returns last element - - 0, 1, *+1 ... * # counting - 0, 1, *+* ... * # fibonacci - -For any prefix, infix, postfix, or postcircumfix operator that would be -primed by a C, a C also autoprimes it, such that any -noun phrase based on C<*> as a head noun autoprimes transitively outward as -far as it makes sense, including outward through metaoperators. Hence: - - * + 2 + 3 # { $^x + 2 + 3 } - * + 2 + * # { $^x + 2 + $^y } - * + * + * # { $^x + $^y + $^z } - (-*.abs)i # { (-$^x.abs)i } - @a «+» * # { @a «+» $^x } - -Note in particular that parentheses will autoprime on a C, so - - *[0](1,2,3,4,5) - -means - - -> @a { @a[0](1,2,3,4,5) } - -rather than - - (-> @a { @a.[0] })(1,2,3,4,5) - -If you want the latter semantics for some reason, use a temporary: - - my $c = *[0]; $c(1,2,3,4,5); - -or just put the autoprime in parens: - - (*[0])(1,2,3,4,5) - -Note that only C<*> autoprimes, because it's an instantiated object. -A C type object never autoprimes. - -=head3 Operators with idiosyncratic Whatever - -The above is only for operators that are not C-aware. There is no -requirement that a C-aware operator return a C when -C is used as an argument; that's just the I behavior for -functions that have no intrinsic "globbish" meaning for C<*>. If you want -to prime one of these globbish operators, you'll need to write an explicit -closure or do an explicit priming on the operator with C<.assuming()>. -Operators in this class, such as C<< infix:<..> >> and C<< infix: >>, -typically I autoprime arguments of type C even though they -do not autoprime C, so we have: - - "foo" xx * # infinite supply of "foo" - "foo" xx *-1 # { "foo" xx $^a - 1 } - 0 .. * # half the real number line - 0 .. * - 1 # { 0 .. $^a - 1 } - * - 3 .. * - 1 # { $^a - 3 .. $^b - 1 } - -(If the last is used as a subscript, the subscripter notices there are two -arguments and passes that dimension's size twice.) - -The smartmatch operator will autoprime C<*> but not a C. - - * ~~ Int # same as { $_ ~~ Int } - $x ~~ * # same as { $x ~~ $_ } - - $x ~~ * == 42 # same as $x ~~ { $_ == 42 } - * == 42 ~~ Any # same as { $_ == 42 } ~~ Any - -=head3 Non-closure-returning Operators with C<*> - -Operators that are known to return non-closure values with C<*> include: - - 0 .. * # means 0 .. Inf - 0 ... * # means 0 ... Inf - 'a' xx * # means 'a' xx Inf - 1,* # means 1,* :) - - $a = * # just assigns Whatever - $a = * + 1 # just assigns WhateverCode - -The sequence operators C<< &infix:<...> >> and C<< &infix:<...^> >> -do not autoprime C, because we want to allow C -closures as the stopper: - - 0 ...^ *>5 # means 0, 1, 2, 3, 4, 5 - -[Conjecture: it is possible that, for most of the above operators that take -C<*> to mean C, we could still actually return a closure that defaults -that particular argument to C. However, this would work only if we -provide a "value list context" that forbids closures, in the sense that it -always calls any closure it finds in its list and replaces the closure in -the list with its return value or values, and then rescans from that point -(kinda like a text macro does), in case the closure returned a list -containing a closure. So for example, the closure returned by C<0..*> would -interpolate a C object into the list when called. Alternately, it -could return the C<0>, followed by another closure that does C<1..*>. Even -the C<...> operator could likely be redefined in terms of a closure that -regenerates itself, as long as we figure out some way of remembering the -last N values each time.] - -In any case, array indexes must behave as such a 'value list context', since -you can't directly index an array with anything other than a number. The -final element of an array is subscripted as C<@a[*-1]>, which means that -when the subscripting operation discovers a C object for a -subscript, it calls it and supplies an argument indicating the number of -elements in (that dimension of) the array. See S09. - -=head3 The C Type - -A variant of C<*> is the C<**> term, which is of type C. It -is generally understood to be a multidimension form of C<*> when that makes -sense. When modified by an operator that would turn C<*> into a function of -one argument, C, C<**> instead turns into a function with -one slurpy argument, C, such that multiple arguments are -distributed to some number of internal whatevers. That is: - - * - 1 means -> $x { $x - 1 } - ** - 1 means -> *@x { map -> $x { $x - 1 }, @x } - -Therefore C<@array[^**]> represents C<< @array[{ map { ^* }, @_ }] >>, that -is to say, every element of the array, no matter how many dimensions. -(However, C<@array[**]> means the same thing because (as with C<...> above), -the subscript operator will interpret bare C<**> as meaning all the -subscripts, not the list of dimension sizes. The meaning of C is -always controlled by the first context it is bound into.) - -Other uses for C<*> and C<**> will doubtless suggest themselves over time. -These can be given meaning via the MMD system, if not the compiler. In -general a C should be interpreted as maximizing the degrees of -freedom in a dwimmy way, not as a nihilistic "don't care anymore--just shoot -me". - -=head2 Native types - -Values with these types autobox to their uppercase counterparts when you -treat them as objects: - - bit single native bit - int native signed integer - uint native unsigned integer (autoboxes to Int) - buf native buffer (finite seq of native ints or uints, no Unicode) - rat native rational - num native floating point - complex native complex number - bool native boolean - -Since native types cannot represent Perl's concept of undefined values, in -the absence of explicit initialization, native floating-point types default -to C, while integer types (including C) default to 0. The complex -type defaults to C. A buf type of known size defaults to a -sequence of 0 values. - -You can set a different default on any container type by use of a trait such -as C. Deleting or undefining such a container sets the -contents back to the default value (or optionally removes it in cases where -the default value can be autovivified on demand). - -If you wish for a native declaration to attempt no initialization, but leave -whatever garbage was in memory, you may use the C trait. -There are several use cases for this, if you know you're going to initialize -the memory otherwise, or you're doing some form of memory mapping. - -If a buf type is initialized with a Unicode string value, the string is -decomposed into Unicode codepoints, and each codepoint shoved into an -integer element. If the size of the buf type is not specified, it takes its -length from the initializing string. If the size is specified, the -initializing string is truncated or 0-padded as necessary. If a codepoint -doesn't fit into a buf's integer type, a parse error is issued if this can -be detected at compile time; otherwise a warning is issued at run time and -the overflowed buffer element is filled with an appropriate replacement -character, either C (REPLACEMENT CHARACTER) if the element's integer -type is at least 16 bits, or C (DELETE) if the larger value would -not fit. If any other conversion is desired, it must be specified -explicitly. In particular, no conversion to UTF-8 or UTF-16 is attempted; -that must be specified explicitly. (As it happens, conversion to a buf type -based on 32-bit integers produces valid UTF-32 in the native endianness.) - -=head2 The C type - -Among other things, C is named after the eastern concept of "Mu" or 無 -(see L, especially the "Mu (negative)" -entry), so in Perl 6 it stands in for Perl 5's concept of "undef" when that -is used as a noun. However, C is also the "nothing" from which -everything else is derived via the undefined type objects, so it stands in -for the concept of "Object" as used in languages like Java. Or think of it -as a "micro" or µ-object that is the basis for all other objects, something -atomic like a Muon. Or if acronyms make you happy, there are a variety to -pick from: - - Most Universal - More Undefined - Modern Undef - Master Union - Meta Ur - Mega Up - ... - -Or just think of it as a sound a cow makes, which simultaneously means -everything and nothing. - -=head2 Undefined types - -Perl 6 does not have a single value representing undefinedness. Instead, -objects of various types can carry type information while nevertheless -remaining undefined themselves. Whether an object is defined is determined -by whether C<.defined> returns true or not. These typed objects typically -represent uninitialized values. Failure objects are also officially -undefined despite carrying exception information; these may be created using -the C function, or by direct construction of a C object of -some sort. (See S04 for how failures are handled.) - - Mu Most Undefined - Failure Failure (lazy exceptions, thrown if not handled properly) - -Whenever you declare any kind of type, class, module, or package, you're -automatically declaring an undefined prototype value with the same name, -known as the I. The name itself returns that type object: - - Mu Perl 6 object (default block parameter type, Any, Junction, or Each) - Any Perl 6 object (default routine parameter type, excludes Junction, Nil, Failure) - Cool Perl 6 Convenient OO Loopbacks - Whatever Wildcard (like Any, but subject to do-what-I-mean via MMD) - Int Any Int object - Widget Any Widget object - -All user-defined classes derive from the C class by default. - -Type objects sometimes stringify to their name in parens, to indicate -undefinedness. Note that type objects are not classes, but may be used to -name classes when the type's associated meta-object allows it: - - Widget.new() # create a new Widget - -The C type encompasses all normal value and object types. It is the -unit type, but includes units that are containers of multiple values. It is -not the most general type, however. C derives from C, which is the -top type in Perl 6, and encompasses certain conceptual types that fall -outside the realm of ordinary C values. These conceptual types -include: - - Junction unordered superposition of data with and/or/one/none - Each ordered superposition (conjectural) - Failure a lazy exception - -Conceptual types rely on the failure to match an C type in order to -trigger various extraordinary behaviors. The C and C types -trigger an inside-out linguistic distribution of various list behaviors from -inside a scalar expression that pretends a bunch of values are really a -single value. (These are modeled on similar linguistic behaviors in -English.) The distributional behavior triggered for these types is known as -I. - -The C type is considered conceptual so that dynamic context can -determine the treatment of failures that in other languages would always -throw exceptions. This gives Perl 6 programs the flexibility to handle -exceptions either in-band or out-of-band. It is particularly important to -be able to handle exceptions in-band when you are trying to perform parallel -operations, so that the failure of one computation does not result in -fratricide of all its fellow computations. (You can think of this as -analogous to the way C propagates through floating-point calculations.) - -Single dispatch of a C invocant to any method not in C -returns the same C, so that cascaded method calls can be checked -with a single check: - - $object.fee.fie.[$foe].{$foo}.sic // die "Oops: $!"; - -Failures may only be passed into functions via parameters that allow C -or C, and a failure may only be returned from a function whose -return type permits it. - -After the failure is returned, any subsequent attempt to use the failure in -an C context will be subject to further failure analysis, and will -likely throw an exception immediately. Likewise, discarding the failure in -sink context produces an immediate exception. - -Note that a C object is undefined, but may contain one or more -defined C objects, which are considered normal objects that just -happen to be used in exception throwing and handling. - -=head2 Immutable types - -Objects with these types behave like values, i.e. C<$x === $y> is true if -and only if their types and contents are identical (that is, if C<$x.WHICH> -eqv C<$y.WHICH>). - - Str Perl string (finite sequence of Unicode characters) - Bit Perl single bit (allows traits, aliasing, undefinedness, etc.) - Int Perl integer (allows Inf/NaN, arbitrary precision, etc.) - Num Perl number (approximate Real, generally via floating point) - Rat Perl rational (exact Real, limited denominator) - FatRat Perl rational (unlimited precision in both parts) - Complex Perl complex number - Bool Perl boolean - Exception Perl exception - Block Executable objects that have lexical scopes - Range A pair of Ordered endpoints - Set Unordered collection of values that allows no duplicates - Bag Unordered collection of values that allows duplicates - Mix Unordered collection of values with weights - Enum An immutable Pair - EnumMap A mapping of Enums with no duplicate keys - Signature Function parameters (left-hand side of a binding) - LoL Arguments in a semicolon list - Capture Function call arguments (right-hand side of a binding) - Blob An undifferentiated mass of ints, an immutable Buf - Instant A point on the continuous atomic timeline - Duration The difference between two Instants - HardRoutine A routine that is committed to not changing - -C values may be composed with the C listop or method. -C values may be composed with the C listop or method. -C values may be composed with the C listop or method. - -Cs and Cs are measured in atomic seconds with fractions. -Notionally they are real numbers which may be implemented in any C -type of sufficient precision, preferably a C or C. -(Implementations that make fixed-point assumptions about the available -subsecond precision are discouraged; the user interface must act like real -numbers in any case.) Interfaces that take C arguments, such as -sleep(), may also take C arguments, but C arguments must be -explicitly created via any of various culturally aware time specification -APIs. A small number of C values that represent common epoch -instant values are also available. - -In numeric context a C happily returns a C or C -representing the number of seconds. C values, on the other hand, -are largely opaque, numerically speaking, and in particular are epoch -agnostic. (Any epoch is just a particular C, and all times related -to that epoch are really C ± C, which returns a new -C.) In order to facilitate the writing of culturally aware time -modules, the C type provides C values corresponding to -various commonly used epochs, such as the 1958 TAI epoch, the POSIX epoch, -the Mac epoch, and perhaps the year 2000 epoch as UTC thinks of it. -There's no reason to exclude any useful epoch that is well characterized in -atomic seconds. All normal times can be calculated from those epoch -instants using addition and subtraction of C values. Note that -the C values are still just atomic time without any cultural -deformations; in particular, the C formed of by subtracting -C from the current instant will contain more seconds -than the current POSIX C due to POSIX's abysmal ignorance of leap -seconds. This is not the fault of the universe, which is not fooled -(neglecting relativistic considerations). Cs and Cs are -always linear atomic seconds. Systems which cannot officially provide a -steady time base, such as POSIX systems, will simply have to make their best -guess as to the correct atomic time when asked to interconvert between -cultural time and atomic time. Alternately, they may use some other -less-official time mechanism to achieve steady clock behavior. Most Unix -systems can count clock ticks, even if POSIX time types get confused. - -Although the conceptual type of an C resembles C, with -arbitrarily large size in either numerator or denominator, the internal form -may of course be optimized internally for "nearby" times, so that, if we -know the year as an integer, the instant within the year can just be a -C representing the offset from the beginning of the year. Calculations -that fall within the same year can then be done in C rather than -C, or a table of yearly offsets can find the difference in integer -seconds between two years, since (so far) nobody has had the nerve to -propose fractional leap seconds. Or whatever. C is opaque, so we -can swap implementations in and out without user-visible consequences. - -The term C returns the current time as an C. As with the -C and C terms, it is not a function, so don't put parens after -it. It also never looks for arguments, so the next token should be an -operator or terminator. - - now + 300 # the instant five minutes from now - -Basic math operations are defined for instants and durations such that the -sum of an instant and a duration is always an instant, while the difference -of two instants is always a duration. Math on instants may only be done -with durations (or numbers that will be taken as durations, as above); you -may not add two instants. - - $instant + $instant # WRONG - $instant - $instant # ok, returns a duration - $instant + $duration # ok, returns an instant - -Numeric operations on durations return C where that makes sense -(addition, subtraction, modulus). The type returned for other numeric -operations is unspecified; they may return normal numeric types or they may -return other dimensional types that attempt to assist in dimensional -analysis. (The latter approach should likely require explicit declaration -for now, until we can demonstrate that it does not adversely impact the -average programmer, and that it plays well with the concept of gradual -typing.) - -The C type is like an immutable buffer, and therefore responds both to -array and (some) stringy operations. Note that, like a C, its size is -measured in whatever the base unit is, which is not always bytes. If you -have a C, then C<$blob.elems> returns the number of bits -in it. As with buffers, various native types are automatically derived from -native unsigned int types: - - blob1 Blob[bit], a bit string - blob2 Blob[uint2], a DNA sequence? - blob3 Blob[uint[3]], an octal string - blob4 Blob[uint4], a hex string - blob8 Blob[uint8], a byte string - blob16 Blob[uint16] - blob32 Blob[uint32] - blob64 Blob[uint64] - -The C type is derived from C, with the additional constraint -that it may only contain validly encoded UTF-8. Likewise, C is -derived from C, and C from C. - -Note that since these are type names, parentheses must always be used to -call them as coercers, since the listop form is not allowed for coercions. -That is: - - utf8 op $x - -is always parsed as - - (utf8) op $x - -and never as - - utf8(op $x) - -These types do (at least) the following roles: - - Class Roles - ===== ===== - Str Stringy - Bit Numeric Boolean Integral - Int Numeric Real Integral - Num Numeric Real - Rat Numeric Real Rational - FatRat Numeric Real Rational - Complex Numeric - Bool Boolean - Block Callable - Range Iterable - Set Setty Iterable - Bag Baggy Iterable - Mix Mixy Iterable - Enum Associative - EnumMap Associative Positional Iterable - Signature - List Positional Iterable - Capture Positional Associative - Blob Stringy Positional - Instant Numeric Real - Duration Numeric Real - HardRoutine Routine - -[Conjecture: C may best be split into 2 roles where both C -and C compose the more general one and just C composes a less -general one. The more general of those would apply to what is common to any -dense sequence ("string") that C and C both are (either of -characters or bits or integers etc), and the string operators like -concatenation (C<~>) and replication (C, C) would be part of the more -general role. The more specific role would apply to C but not C -and includes any specific operators that are specific to I and -don't apply to bits or integers etc. The other alternative is to more -clearly distance character strings from bit strings, keeping C<~>/etc for -character strings only and adding an analogy for bit strings.] - -The C role indicates not that you can iterate the type directly, -but that you can request the type to return an iterator. Iterable types may -have multiple iterators (lists) running across them simultaneously, but an -iterator/list itself has only one thread of consumption. Every time you do -C on an iterator, a value disappears from its list. - -Note that C iterators return only the keys, not the boolean values. -You must explicitly use C<.pairs> to get key/value pairs. The C and -C types, on the other hand, default to returning pairs, as a C -does. - -=head2 Mutable types - -Objects with these types have distinct C<.WHICH> values that do not change -even if the object's contents change. (Routines are considered mutable -because they can be wrapped in place.) - - Iterator Perl list - RangeIter Iterator over a Range - Scalar Perl scalar - Array Perl array - Hash Perl hash - SetHash Setty QuantHash[Bool,False] - BagHash Baggy QuantHash[UInt,0] - MixHash Mixy QuantHash[Real,0.0] - Pair A single key-to-value association - Buf Perl buffer (array of integers with some stringy features) - IO Perl filehandle - Routine Base class for all wrappable executable objects - Sub Perl subroutine - Method Perl method - Submethod Perl subroutine acting like a method - Macro Perl compile-time subroutine - Regex Perl pattern - Match Perl match, usually produced by applying a pattern - Stash A symbol table hash (package, module, class, lexpad, etc) - SoftRoutine A routine that is committed to staying mutable - -The C role differs from a normal C hash in how it -handles default values. If the value of a C element is set to -the default value for the C, the element is deleted. If -undeclared, the default default for a C is 0 for numeric types, -C for boolean types, and the null string for string and buffer types. -A C of an object type defaults to the undefined prototype for -that type. More generally, the default default is whatever defined value a -C would convert to for that value type. A C of C -deletes elements that go to either 0 or the null string. A C -also autodeletes keys for normal undefined values (that is, those undefined -values that do not contain an unthrown exception). - -A C is a C of booleans with a default of C. If -you use the C interface and increment an element of a C its -value becomes true (creating the element if it doesn't exist already). If -you decrement the element it becomes false and is automatically deleted. -Decrementing a non-existing value results in a C value. Incrementing -an existing value results in C. When not used as a C (that is, -when used as an C or list or C object) a C behaves as a -C of its keys. (Since the only possible value of a C is the -C value, it need not be represented in the actual implementation with -any bits at all.) - -A C is a C of C with a default of 0. If you use -the C interface and increment an element of a C its value is -increased by one (creating the element if it doesn't exist already). If you -decrement the element the value is decreased by one; if the value goes to 0 -the element is automatically deleted. An attempt to decrement a -non-existing value returns an undefined value. When not used as a C -(that is, when used as an C or list or C object) a C -behaves as a C of its pairs. - -A C is a C of C with a default of 0.0. If the -value goes to 0 the element is automatically deleted. When not used as a -C (that is, when used as an C or list or C object) a -C behaves as a C of its pairs. - -As with C types, C and C are mutable in their values -but not in their keys. (A key can be a reference to a mutable object, but -cannot change its C<.WHICH> identity. In contrast, the value may be rebound -to a different object, just as a hash element may.) - -The following roles are supported: - - Iterator List - Scalar - Array Positional Iterable - Hash Associative - SetHash Setty QuantHash[Bool] - BagHash Baggy QuantHash[UInt] - MixHash Mixy QuantHash[Real] - Pair Associative - PairSeq Associative Positional Iterable - Buf Stringy - IO - Routine Callable - Sub Callable - Method Callable - Submethod Callable - Macro Callable - Regex Callable - Match Positional Associative - Stash Associative - SoftRoutine Routine - -Types that do the C role are generally hidden from casual view, since -iteration is typically triggered by context rather than by explicit call to -the iterator's C<.get> method. Filehandles are a notable exception. - -See L for a discussion of soft vs. hard routines. - -=head2 Of types - -Explicit types are optional. Perl variables have two associated types: their -"of type" and their "container type". (More generally, any container has a -container type, including subroutines and modules.) The C type is stored -as its C property, while the container type of the container is just the -object type of the container itself. The word C is allowed as an -alias for C. - -The C type specifies what kinds of values may be stored in the variable. -An C type is given as a prefix or with the C keyword: - - my Dog $spot; - my $spot of Dog; - -In either case this sets the C property of the container to C. You -may not mix these notations; if you do, a compiler error will result. - -An C type on an array or hash specifies the type stored by each element: - - my Dog @pound; # each element of the array stores a Dog - - my Rat %ship; # the value of each entry stores a Rat - -The key type of a hash may be specified as a shape trait--see S09. - -Containers enforce type safety on setting, whereas subroutines enforce type -safety on return. The C declarations is an alias for the C -type of a subroutine. - - sub get_pet() of Animal {...} # of type, obviously - sub get_pet() returns Animal {...} # of type - our Animal sub get_pet() {...} # of type - -To coerce your return value, use a coercion type: - - sub get_pet() returns Pet(Animal) {...} # coerce any Animal to Pet - -For a container, however, use of a coercion type as the C coerces upon -setting rather than returning the value. - -=head2 Container types - -The container type specifies how the variable itself is implemented. It is -given as a trait of the variable: - - my $spot is Scalar; # this is the default - my $spot is PersistentScalar; - my $spot is DataBase; - -Defining a container type is the Perl 6 equivalent to tying a variable in -Perl 5. But Perl 6 variables are tied directly at declaration time, and for -performance reasons may not be tied with a run-time C statement unless -the variable is explicitly declared with a container type that does the -C role. - -However, package variables are always considered C by default. As -a consequence, all named packages are also C by default. Classes -and modules may be viewed as differently tied packages. Looking at it from -the other direction, classes and modules that wish to be bound to a global -package name must be able to do the C role. - -=head2 Hierarchical types - -A non-scalar type may be qualified, in order to specify what type of value -each of its elements stores: - - my Egg $cup; # the value is an Egg - my Egg @carton; # each elem is an Egg - my Array of Egg @box; # each elem is an array of Eggs - my Array of Array of Egg @crate; # each elem is an array of arrays of Eggs - my Hash of Array of Recipe %book; # each value is a hash of arrays of Recipes - -Each successive C makes the type on its right a parameter of the type on -its left. Parametric types are named using square brackets, so: - - my Hash[Array[Recipe]] %book; - -actually means: - - my Hash of Array of Recipe %book; - -which is: - - my Hash:of(Array:of(Recipe)) %book; - -Because the actual variable can be hard to find when complex types are -specified, there is a postfix form as well: - - my Hash of Array of Recipe %book; # HoHoAoRecipe - my %book of Hash of Array of Recipe; # same thing - -Alternately, the return type may be specified within the signature: - - my sub get_book ($key --> Hash of Array of Recipe) {...} - -You may also specify the type as the C trait (with C -allowed as a synonym): - - my Hash of Array of Recipe sub get_book ($key) {...} - my sub get_book ($key) of Hash of Array of Recipe {...} - my sub get_book ($key) returns Hash of Array of Recipe {...} - -=head2 Parameter types - -Parameters may be given types, just like any other variable: - - sub max (int @array is rw) {...} - sub max (@array of int is rw) {...} - -=head2 Generic types - -Within a declaration, a class variable (either by itself or following an -existing type name) declares a new type name and takes its parametric value -from the actual type of the parameter it is associated with. It declares -the new type name in the same scope as that of the associated declaration. - - sub max (Num ::X @array) { - push @array, X.new(); - } - -The new type name is introduced immediately, so two such types in the same -signature must unify compatibly if they have the same name: - - sub compare (Any ::T $x, T $y) { - return $x eqv $y; - } - -=head2 The Cool class (and package) - -The C type is derived from C, and contains all the methods that -are "cool" (as in, "I'm cool with an argument of that type."). - -More specifically, these are the methods that are culturally universal, -insofar as the typical user will expect the name of the method to imply -conversion to a particular built-in type that understands the method in -question. For instance, C<$x.abs> implies conversion to an appropriate -numeric type if C<$x> is "cool" but doesn't already support a method of that -name. Conversely, C<$x.substr> implies conversion to a string or buffer -type. - -The C module also contains all multisubs of last resort; these are -automatically searched if normal multiple dispatch does not find a viable -candidate. Note that the C package is mutable, and both single and -multiple dispatch must take into account changes there for the purposes of -run-time monkey patching. However, since the multiple dispatcher uses the -C package only as a failover, compile-time analysis of such dispatches -is largely unaffected for any arguments with an exact or close match. -Likewise any single dispatch a method that is more specific than the C -class is not affected by the mutability of C. User-defined classes -don't derive from C by default, so such classes are also unaffected by -changes to C. - -=head1 Names and Variables - -=head2 Apostrophe separator - -The C<$Package'var> syntax is gone. Use C<$Package::var> instead. (Note, -however, that identifiers may now contain an apostrophe or hyphen if -followed by a character matching C<< <.alpha> >>) - -=head2 Sigils - -Perl 6 includes a system of B to mark the fundamental structural -type of a variable: - - $ scalar (object) - @ ordered array - % unordered hash (associative array) - & code/rule/token/regex - :: package/module/class/role/subset/enum/type/grammar - -Within a declaration, the C<&> sigil also declares the visibility of the -subroutine name without the sigil within the scope of the declaration: - - my &func := sub { say "Hi" }; - func; # calls &func - -Within a signature or other declaration, the C<::> pseudo-sigil followed by -an identifier marks a type variable that also declares the visibility of a -package/type name without the sigil within the scope of the declaration. -The first such declaration within a scope is assumed to be an unbound type, -and takes the actual type of its associated argument. With subsequent -declarations in the same scope the use of the pseudo-sigil is optional, -since the bare type name is also declared. - -A declaration nested within must not use the sigil if it wishes to refer to -the same type, since the inner declaration would rebind the type. (Note -that the signature of a pointy block counts as part of the inner block, not -the outer block.) - -=head3 Sigils indicate interface - -Sigils indicate overall interface, not the exact type of the bound object. -Different sigils imply different minimal abilities. - -C<$x> may be bound to any object, including any object that can be bound to -any other sigil. Such a scalar variable is always treated as a singular -item in any kind of list context, regardless of whether the object is -essentially composite or unitary. It will not automatically dereference to -its contents unless placed explicitly in some kind of dereferencing context. -In particular, when interpolating into list context, C<$x> never expands its -object to anything other than the object itself as a single item, even if -the object is a container object containing multiple items. - -C<@x> may be bound to an object of the C class, but it may also be -bound to any object that does the C role, such as a C, -C, C, or C. The C role implies the -ability to support C<< postcircumfix:<[ ]> >>. - -Likewise, C<%x> may be bound to any object that does the C -role, such as C, C, C, C, or C. The -C role implies the ability to support C<< postcircumfix:<{ }> ->>. - -C<&x> may be bound to any object that does the C role, such as any -C or C. The C role implies the ability to support -C<< postcircumfix:<( )> >>. - -In any case, the minimal container role implied by the sigil is checked at -binding time at the latest, and may fail earlier (such as at compile time) -if a semantic error can be detected sooner. If you wish to bind an object -that doesn't yet do the appropriate role, you must either stick with the -generic C<$> sigil, or mix in the appropriate role before binding to a more -specific sigil. - -An object is allowed to support both C and C. An -object that does not support C may not be bound directly to -C<@x>. However, any construct such as C<%x> that can interpolate the -contents of such an object into list context can automatically construct a -list value that may then be bound to an array variable. Subscripting such a -list does not imply subscripting back into the original object. - -=head3 No intervening whitespace - -Unlike in Perl 5, you may no longer put whitespace between a sigil and its -following name or construct. - -=head2 Twigils - -Ordinary sigils indicate normally scoped variables, either lexical or -package scoped. Oddly scoped variables include a secondary sigil (a -B) that indicates what kind of strange scoping the variable is -subject to: - - $foo ordinary scoping - $.foo object attribute public accessor - $^foo self-declared formal positional parameter - $:foo self-declared formal named parameter - $*foo dynamically overridable global variable - $?foo compiler hint variable - $=foo Pod variable - $ match variable, short for $/{'foo'} - $!foo object attribute private storage - $~foo the foo sublanguage seen by the parser at this lexical spot - -Most variables with twigils are implicitly declared or assumed to be -declared in some other scope, and don't need a "my" or "our". Attribute -variables are declared with C, though. - -=head2 Scope declarators - -Normal names and variables are declared using a I: - - my # introduces lexically scoped names - our # introduces package-scoped names - has # introduces attribute names - anon # introduces names that are private to the construct - state # introduces lexically scoped but persistent names - augment # adds definitions to an existing name - supersede # replaces definitions of an existing name - unit # like our, but introduces a compilation-unit scoped name - -Names may also be declared in the signature of a function. These are -equivalent to a C declaration inside the block of the function, except -that such parameters default to readonly. - -The C declarator allows a declaration to provide a name that can be -used in error messages, but that isn't put into any external symbol table: - - my $secret = anon sub marine () {...} - $secret(42); # too many arguments to sub marine - -However, the name is introduced into the scope of the declaration itself, so -it may be used to call itself recursively: - - my $secret = anon sub tract($n) { say $n; tract($n-1) if $n }; - $secret(5); # 5 4 3 2 1 0 - -=head2 Invariant sigils - -Sigils are now invariant. C<$> always means a scalar variable, C<@> an -array variable, and C<%> a hash variable, even when subscripting. In item -context, variables such as C<@array> and C<%hash> simply return themselves -as C and C objects. (Item context was formerly known as scalar -context, but we now reserve the "scalar" notion for talking about variables -rather than contexts, much as arrays are disassociated from list context.) - -=head2 List stringification - -In string contexts, lists and list-like objects automatically stringify to -appropriate (white-space separated) string values. In numeric contexts, the -number of elements in the container is returned. In boolean contexts, a -true value is returned if and only if there are any elements in the -container. - -=head2 The C<.perl> method - -To get a Perlish representation of any object, use the C<.perl> method. -Like the C module in Perl 5, the C<.perl> method will put -quotes around strings, square brackets around list values, curlies around -hash values, constructors around objects, properly handle circular -references etc., so that Perl can evaluate the result back to the same -object. The C<.perl> method will return a representation of the object on -the assumption that, if the code is reparsed at some point, it will be used -to regenerate the object as a scalar in item context. If you wish to -interpolate the regenerated object in a list context, it may be necessary to -use C<< prefix:<|> >> to force interpolation. - -Note that C<.perl> has a very specific definition, and it is expected that -some modules will rely on the ability to roundtrip values with C. As -such, overriding C<.perl> with a different format (globally using -C, or for specific classes unless special care is taken to -maintain parsability) is unwise. Code which does not depend on C<.perl>'s -definition should use C<.gist> instead to allow more control. - -=head2 The C<.gist> method - -C<.gist>, by contrast with C<.perl>, returns a flexible form of an object -intended for human interpretation. For example, when presented with a very -long list or array, only the first 100 entries will be printed, followed by -C<...> to indicate there are more entries. If that's not what you want, -stringify the list instead. This method is only supposed to give you the -gist of the value, not the whole value. - -Specific user classes are encouraged to override C<.gist> to do something -appropriate, and it is completely acceptable to monkey patch C<.gist> -methods while doing debugging, without risk of breaking any used module. -C<.gist>, like any method, will accept and ignore unrecognized named -arguments; implementations of C<.gist> are encouraged to standardize on a -set of flags. - -[Some conjectural suggestions: - - :oneline Do not indent or linebreak output - :width($d) Wrap output at $d chars - :charset($obj) Represent unrecognized characters as escapes - :ascii Short for some instantiation of :charset - -Conjecturally, C<.gist> on system-defined classes could redispatch to -C<&*PRETTYPRINTER> or some similar system, allowing for a more disciplined -way to change pretty formats. - -It may also be desirable to use a richer format for intermediate strings -than simple C, for instance using an object format that can handle -intelligent line breaking. However, that's probably overkill.] - -=head2 The C<.fmt> method - -To get a formatted representation of any scalar value, use the -C<.fmt('%03d')> method to do an implicit C on the value. - -To format an array value separated by commas, supply a second argument: -C<.fmt('%03d', ', ')>. To format a hash value or list of pairs, include -formats for both key and value in the first string: C<< .fmt('%s: %s', "\n") ->>. - -=head2 Subscripts - -Subscripts now consistently dereference the container produced by whatever -was to their left. Whitespace is not allowed between a variable name and -its subscript. However, there are two ways to stretch the construct out -visually. Since a subscript is a kind of postfix operator, there is a -corresponding B form of each subscript (C<@foo.[1]> and C<%bar.{'a'}>) -that makes the dereference a little more explicit. Constant string -subscripts may be placed in angles, so C<%bar.{'a'}> may also be written as -C<< %bar >> or C<< %bar. >>. Additionally, you may insert extra -whitespace using the unspace. - -Slicing is specified by the nature of the subscript, not by the sigil. - -=head3 Subscripts have list context - -The context in which a subscript is evaluated is no longer controlled by the -sigil either. Subscripts are always evaluated in list context. (More -specifically, they are evaluated in a variant of list context known as -I context (List of List), which preserves dimensional information so -that you can do multi-dimensional slices using semicolons. However, each -slice dimension evaluates its sublist in normal list context, so functions -called as part of a subscript don't see a lol context. See S09 for more on -slicing.) - -If you need to force inner context to item (scalar), we now have convenient -single-character context specifiers such as + for numbers and ~ for strings: - - $x = g(); # item context for g() - @x[f()] = g(); # list context for f() and g() - @x[f()] = +g(); # list context for f(), numeric item context for g() - @x[+f()] = g(); # numeric item context for f(), list context for g() - - @x[f()] = @y[g()]; # list context for f() and g() - @x[f()] = +@y[g()]; # list context for f() and g() - @x[+f()] = @y[g()]; # numeric item context for f(), list context for g() - @x[f()] = @y[+g()]; # list context for f(), numeric item context for g() - - %x{~f()} = %y{g()}; # string item context for f(), list context for g() - %x{f()} = %y{~g()}; # list context for f(), string item context for g() - -Sigils used as functions with parenthesis also force context, so these also -work: - - @x[$(g())] # item context for g() - %x{$(g())} # item context for g() - -But note that these don't do the same thing: - - @x[$g()] # call function in $g - %x{$g()} # call function in $g - -Array and Hash variables can be evaluated in item context by prefixing them -with a single dollar sign: - - $@a # same as item @a - $%h # same as item %h - -=head2 List assignment and binding - -There is a need to distinguish list assignment from list binding. List -assignment works much like it does in Perl 5, copying the values. There's a -new C<:=> binding operator that lets you bind names to C and C -objects without copying, in the same way as subroutine arguments are bound -to formal parameters. See S06 for more about binding. - -=head2 List - -Comma-separated values (as well as word-quoting constructs such as -C<< >>) form a C: - - (1,2,3,:mice) - -The result is a C object containing three C objects and a -C object, that is, four positional objects. When, however, you say -something like: - - rhyme(1,2,3,:mice) - -the syntactic list is translated (at compile time, in this case) into a -C object with three positionals and one named argument in -preparation for binding. More generally, a list is transmuted to a -capture any time it is bound to a complete signature. - -You may force immediate conversion to a C object by prefixing the -list with a backslash: - - $args = \(1,2,3,:mice) - -Individual arguments in an argument list (or capture composer) are parsed as ordinary -expressions, and any functions mentioned are called immediately, with each -function's results placed as an argument within the outer argument list. Whether any -given argument is flattened will depend on its eventual binding, and in -general cannot be known at composition time. - -We use "argument" here to mean anything that would be taken as a single -argument if bound to a positional or named parameter: - - rhyme(1,2,3,:mice) # rhyme has 4 arguments - rhyme((1,2),3,:mice) # rhyme has 3 arguments - rhyme((1,2,3),:mice) # rhyme has 2 arguments - rhyme((1,2),(3,:mice)) # rhyme has 2 arguments - rhyme((1,2,3,:mice)) # rhyme has 1 argument - -In these examples, the first argument to the function is a list in all but -the first case, where it is simply the literal integer 1. An argument is -either of: - -=over - -=item * - -A parenthesized list that groups together a sublist, or - -=item * - -Any other object that can function as a single argument. - -=back - -Looking at it the other way, all arguments that don't actually need to be -wrapped up in a list are considered degenerate lists in their own right -when it comes to binding. Note that a capture is not considered a kind of -list, so does not flatten in flat context. - -=head2 Lists, parameters, and Captures - -When an argument is bound to a parameter, the behavior depends on whether -the parameter is "flattening" or "argumentative". Positional parameters and -slice parameters are argumentative -and just return the next syntactic argument -without flattening. (A slice differs from an ordinary positional -parameter in being "slurpy", that is, it is intended to fetch multiple -values from the variadic region of the surrounding capture. Slurpy contexts -come in flattening (C<*> parameters), slicing (C<**> parameters), and one-arg (C<+> parameters) -forms.) - -The fact that a parameter is being bound implies that there is an outer -capture being bound to a signature. The capture's iterator provides a -C<.get> and a C<.getarg> method to tell the iterator what context to bind -in. For positional/slice parameters, the C<.getarg> method returns the -entire next argument from the iterator. It returns other objects unchanged. -In contrast, flat parameters call C<.get> on the capture's iterator, which -flattens any sublists before pulling out the next item. In either case, -no bare list object is seen as a normal bound argument. (There is a way -to bind the underlying list using backslash, however. This is how -internal routines can deal with lists as real objects.) - -In contrast to parameter binding, if a C is bound to an entire -signature (typically as part of a function or method call), it will be -transformed first into a capture object, which is much like a list but has -its arguments divvied up into positional and named subsets for faster -binding. (Usually this transformation happens at compile time.) If the -first positional is followed by a colon instead of a comma, it is marked as -the invocant in case it finds itself in a context that cares. It's illegal -to use the colon in place of the comma anywhere except after the first -argument. - -Explicit binding to an individual variable is considered a form of signature -binding, which is to say a declarator puts implicit signature parens around -the unparenthesized form: - - my (*@x) := foo(); # signature binding - my *@x := foo(); # same thing - -The parens are, of course, required if there is more than one parameter. - -C objects are immutable in the abstract, but evaluate their -arguments lazily. Before everything inside a C is fully evaluated -(which happens at compile time when all the arguments are constants), the -eventual value may well be unknown. All we know is that we have the promise -to make the bits of it immutable as they become known. - -C objects may contain multiple unresolved iterators such as feeds -or lazy lists. How these are resolved depends on what they -are eventually bound to. Some bindings are sensitive to multiple dimensions -while others are not. Binding to a list of lists is often known as -"slicing", because it's commonly used to index "slices" of a potentially -multi-dimensional array. - -You may retrieve parts from a C object with a prefix sigil operator: - - $args = \3; # same as "$args = \(3)" - @$args; # same as "Array($args)" - %$args; # same as "Hash($args)" - -When cast into an array, you can access all the positional arguments; into a -hash, all named arguments. - -All prefix sigil operators accept one positional argument, evaluated in item -context as a rvalue. They can interpolate in strings if called with -parentheses. The special syntax form C<$()> translates into C<$( $/.made // -Str($/) )> to operate on the current match object; similarly C<@()> and -C<%()> can extract positional and named submatches. - -C objects fill the ecological niche of references in -Perl 6. You can think of them as "fat" references, that is, references that -can capture not only the current identity of a single object, but also the -relative identities of several related objects. Conversely, you can think -of Perl 5 references as a degenerate form of C when you want to -refer only to a single item. - -The C statement prefix will eagerly evaluate any block or statement, -throw away the results, and instead return the empty C value, C<()>. -This can be useful to peg some behavior to an empty list while still -returning an empty list: - - # Check that incoming argument list isn't null - @inclist = map { $_ + 1 }, @list || sink warn 'Nil input!'; - - @inclist = do for @list || sink { warn 'Nil input!'; $warnings++; } { - $_ + 1; - } - - # Check that outgoing result list isn't null - @inclist = do map { $_ + 1 }, @list or sink warn 'Nil result!'; - - @inclist = do for @list { - $_ + 1; - } or sink { warn 'Nil result'; $warnings++; } - -Given C, there's no need for an "else" clause on Perl 6's loops, and -the C construct works in any list, not just C loops. - -=head2 CaptureCursors - -A C object is a view into another capture with an associated -start position. Such a cursor is essentially a pattern-matching state. -Capture cursors are used for operations like C and C and C -loops that need to apply a short signature multiple times to a longer list -of values supplied by the base capture. When we say "capture" we sometimes -mean either C or C. C are also -immutable. When pattern matching a signature against a cursor, you get a -new cursor back which tells you the new position in the base capture. - -=head2 Signature objects - -A signature object (C) may be created with colon-prefixed parens: - - my ::MySig ::= :(Int, Num, Complex, Status) - -Expressions inside the signature are parsed as parameter declarations rather -than ordinary expressions. See S06 for more details on the syntax for -parameters. - -Declarators generally make the colon optional: - - my ($a,$b,$c); # parsed as signature - -Signature objects bound to type variables (as in the example above) may be -used within other signatures to apply additional type constraints. When -applied to a capture argument, the signature allows you to take the types of -the capture's arguments from C, but declare the (untyped) variable -names yourself via an additional signature in parentheses: - - sub foo (Num $num, MySig $a ($i,$j,$k,$mousestatus)) {...} - foo($mynum, \(1, 2.7182818, 1.0i, statmouse()); - -=head2 Ampersand and invocation - -Unlike in Perl 5, the notation C<&foo> merely stands for the C function -as a C object without calling it. You may call any Code object by -dereferencing it with parens (which may, of course, contain arguments): - - &foo($arg1, $arg2); - -Whitespace is not allowed before the parens because it is parsed as a -postfix. As with any postfix, there is also a corresponding C<.()> -operator, and you may use the "unspace" form to insert optional whitespace -and comments between the backslash and either of the postfix forms: - - &foo\ ($arg1, $arg2); - &foo\ .($arg1, $arg2); - &foo\#`[ - embedded comment - ].($arg1, $arg2); - -Note however that the parentheses around arguments in the "normal" named -forms of function and method calls are not postfix operators, so do not -allow the C<.()> form, because the dot is indicative of an actual -dereferencing operation, which the named forms aren't doing. You may, -however, use "unspace" to install extra space before the parens in the -forms: - - foo() # okay - foo\ () # okay - foo.() # means foo().() - - .foo() # okay - .foo\ () # okay - .foo.() # means .foo().() - - $.foo() # okay - $.foo\ () # okay - $.foo.() # means $.foo().() - -If you I use the dotty form on these special forms, it will assume you -wanted to call the named form without arguments, and then dereference the -result of that. - -=head2 Specifying a dispatch candidate - -With multiple dispatch, C<&foo> is actually the name of a C -routine (instantiated from a C) controlling a set of candidate -functions (which you can use as if it were an ordinary function, because a -C is really an C function with pretensions to management of -a dispatcher). However, in that case C<&foo> by itself is not sufficient to -uniquely name a specific function. To do that, the type may be refined by -using a signature literal as a postfix operator: - - &foo:(Int,Num) - -Use of a signature that does not unambiguously select a single multi results -in failure. - -It still just returns a C object. A call may also be partially -applied (primed) by using the C<.assuming> method: - - &foo.assuming(1,2,3,:mice) - -=head2 Multidimensional slices and lists - -Slicing syntax is covered in S09. A multidimensional slice will be done -with semicolons between individual slice sublists. The semicolons imply one -extra level of tree-ness. So when you say - - @matrix[1..*; 0] - -really means - - @matrix[List.new( (1..*), 0 )] - -Each such slice sub-list is evaluated lazily. - -Just as parens and brackets can be used to compose lists and arrays, if -you put any semicolons into either form, it becomes a multi-dimensional -composer: - - (1..*; 0) # same as (lol (1..*), 0), that is LoL.new($(1..*), 0) - [1..*; 0] # same as [lol (1..*), 0], that is Array.new($(1..*), 0) - -A consequence of this is that you may not put more than one statement inside -parens or brackets expecting sequence semantics, that is, the way a normal -block evaluates all but the final statement for declarations or side -effects, then returns the value of the final statement. In order to do that -in Perl 6, you need to use one of these constructs: - - do { my $x = 42; $x } - $( my $x = 42; $x ) - @( my @x = 42,43; @x ) - %( my %x = a => 42; %x ) - -Note that the first one limits the scope of the declaration to the block, -while the parenthesized forms are parasitic on the outer lexical scope. - -=head2 Subscript adverbs - -To make a slice subscript return something other than values, append an -appropriate adverb to the subscript. - - @array = ; - @array[0,1,2]; # returns 'A', 'B', (Any) - @array[0,1,2] :p; # returns 0 => 'A', 1 => 'B' - @array[0,1,2] :kv; # returns 0, 'A', 1, 'B' - @array[0,1,2] :k; # returns 0, 1 - @array[0,1,2] :v; # returns 'A', 'B' - - %hash = (:a, :b); - %hash; # returns 'A', 'B', (Any) - %hash :p; # returns a => 'A', b => 'B' - %hash :kv; # returns 'a', 'A', 'b', 'B' - %hash :k; # returns 'a', 'b' - %hash :v; # returns 'A', 'B' - -These adverbial forms all weed out non-existing entries if the adverb is -true; if not, they leave them in, just as an ordinary slice would. So: - - @array[0,1,2] :!p; # returns 0 => 'A', 1 => 'B', 2 => (Any) - %hash :!kv; # returns 'a', 'A', 'b', 'B', 'c', (Any) - -Likewise, - - my ($a,$b,$c) = %hash :delete; - -deletes the entries I while returning them. (Of course, any of -these forms also work in the degenerate case of a slice containing a single -index.) Note that these forms work by virtue of the fact that the subscript -is the topmost previous operator. You may have to parenthesize or force -list context if some other operator that is tighter than comma would appear -to be topmost: - - 1 + (%hash{$x} :delete); - $x = (%hash{$x} :delete); - ($x) = %hash{$x} :delete; - -(The situation does not often arise for the slice modifiers above because -they are usually used in list context, which operates at comma precedence.) - -The element is deleted only if the adverb is true. While C<:!delete> is -essentially a no-op; you could conditionally delete entries I -based on passing a flag such as in C<:delete($kill'em)>. In either case, -the values are returned. - -You may also perform an existence test, either on a single item or a -junction of items: - - if %hash :exists {...} - if %hash{any } :exists {...} - if %hash{all } :exists {...} - if %hash{one } :exists {...} - if %hash{none } :exists {...} - -Using the C<:exists> adverb together with a list slice results in in a -C of C, which you could also put in a junction with similar -semantics: - - if any %hash :exists {...} - if all %hash :exists {...} - if one %hash :exists {...} - if none %hash :exists {...} - -although with different optimization options for the compiler. - -You may use C<:!exists> to test for non-existence. This is specifically -handy because of precedence rules making C<< !%hash :exists >> apply the -C<:exists> to the prefix C. C<< %hash :!exists >> does not have that -problem. - -=head2 Combining subscript adverbs - -Like named parameters in a call, there is no order in handling multiple -adverbs with subscripts. Some combinations make sense, such as: - - %a = %b{@keys-to-extract} :delete :p; # same as :p :delete - -would slice out pairs for the given keys out of one hash into another. -Whereas - - @actually-deleted = %h{@keys-to-extract} :delete :k; # same as :k :delete - -would return the I that were actually deleted from the hash. - -The adverbs that specify a return type only, can B be combined, because -combinations such as C<:kv :p> or C<:v :k> simply do not make sense. - -These combinations are considered legal and mean the following: - - :delete :kv delete, return key/values of actually deleted keys - :delete :!kv delete, return key/values of all keys attempted - :delete :p delete, return pairs of actually deleted keys - :delete :!p delete, return pairs of all keys attempted - :delete :k delete, return actually deleted keys - :delete :!k delete, return all keys attempted to delete - :delete :v delete, return values of actually deleted keys - :delete :!v delete, return values of all keys attempted - :delete :exists delete, return Bools indicating keys existed - :delete :!exists delete, return Bools indicating keys did not exist - :delete :exists :kv delete, return list with key,True for key existed - :delete :!exists :kv delete, return list with key,False for key existed - :delete :exists :!kv delete, return list with key,Bool whether key existed - :delete :!exists :!kv delete, return list with key,!Bool whether key existed - :delete :exists :p delete, return pairs with key/True for key existed - :delete :!exists :p delete, return pairs with key/False for key existed - :delete :exists :!p delete, return pairs with key/Bool whether key existed - :delete :!exists :!p delete, return pairs with key/!Bool whether key existed - :exists :kv return pairs with key,True for key exists - :!exists :kv return pairs with key,False for key exists - :exists :!kv return pairs with key,Bool for key exists - :!exists :!kv return pairs with key,!Bool for key exists - :exists :p return pairs with key/True for key exists - :!exists :p return pairs with key/False for key exists - :exists :!p return pairs with key/Bool for key exists - :!exists :!p return pairs with key/!Bool for key exists - -An implementation is free to silently ignore any other combinations or -silently prefer one of the adverbs given above any other. - -=head2 Numeric and boolean context of hashes - -In numeric context (i.e. when cast into C or C), a C object -becomes the number of pairs contained in the hash. In a boolean context, a -Hash object is true if there are any pairs in the hash. - -=head2 List sorting - -Sorting a list of pairs should sort on their keys by default, then on their -values. Sorting a list of lists should sort on the first elements, then the -second elements, etc. For more on C see S29. - -=head2 Special variables - -Many of the special variables of Perl 5 are going away. Those that apply to -some object such as a filehandle will instead be attributes of the -appropriate object. Those that are truly global will have global alphabetic -names, such as C<$*PID> or C<@*ARGS>. - -Any remaining special variables will be lexically scoped. This includes -C<$_> and C<@_>, as well as the new C<$/>, which is the return value of the -last regex match. C<$0>, C<$1>, C<$2>, etc., are aliases into the C<$/> -object. - -=head2 Array end index - -The C<$#foo> notation is dead. Use C<@foo.end> or C<@foo[*-1]> instead. -(Or C<@foo.shape[$dimension]> for multidimensional arrays.) - -=head1 Names - -An I is composed of an alphabetic character followed by any -sequence of alphanumeric characters. The definitions of alphabetic and -numeric include appropriate Unicode characters. Underscore is always -considered alphabetic. An identifier may also contain isolated apostrophes -or hyphens provided the next character is alphabetic. - -A I is anything that is a legal part of a variable name (not counting -the sigil). This includes - - $foo # simple identifiers - $Foo::Bar::baz # compound identifiers separated by :: - $Foo::($bar)::baz # compound identifiers that perform interpolations - $42 # numeric names - $! # certain punctuational variables - -When not used as a sigil, the semantic function of C<::> within a name is to -force the preceding portion of the name to be considered a package through -which the subsequent portion of the name is to be located. If the preceding -portion is null, it means the package is unspecified and must be searched -for according to the nature of what follows. Generally this means that an -initial C<::> following the main sigil is a no-op on names that are known at -compile time, though C<::()> can also be used to introduce an interpolation -(see below). Also, in the absence of another sigil, C<::> can serve as its -own sigil indicating intentional use of a not-yet-declared package name. - -Unlike in Perl 5, if a sigil is followed by comma, semicolon, a colon not -followed by an identifier, or any kind of bracket or whitespace (including -Unicode brackets and whitespace), it will be taken to be a sigil without a -name rather than a punctuational variable. This allows you to use sigils as -coercion operators: - - print $( foo() ) # foo called in item context - print %( foo() ) # foo called in hash context - -Bare sigils may be used as placeholders for anonymous variables: - - my ($a, $, $c) = 1..3; - print unless (state $)++; - -Outside of declarative constructs you may also use C<*> for a placeholder: - - ($a, *, $c) = 1..3; - -Which would be the same as: - - ($a, $, $c) = 1..3; - -=head2 Package-qualified names - -Ordinary package-qualified names look like they do in Perl 5: - - $Foo::Bar::baz # the $baz variable in package Foo::Bar - -Sometimes it's clearer to keep the sigil with the variable name, so an -alternate way to write this is: - - Foo::Bar::<$baz> - -This is resolved at compile time because the variable name is a constant. - -=head2 Pseudo-packages - -The following pseudo-package names are reserved at the front of a name: - - MY # Symbols in the current lexical scope (aka $?SCOPE) - OUR # Symbols in the current package (aka $?PACKAGE) - CORE # Outermost lexical scope, definition of standard Perl - GLOBAL # Interpreter-wide package symbols, really UNIT::GLOBAL - PROCESS # Process-related globals (superglobals) - COMPILING # Lexical symbols in the scope being compiled - -The following relative names are also reserved but may be used -anywhere in a name: - - CALLER # Contextual symbols in the immediate caller's lexical scope - CALLERS # Contextual symbols in any caller's lexical scope - DYNAMIC # Contextual symbols in my or any caller's lexical scope - OUTER # Symbols in the next outer lexical scope - OUTERS # Symbols in any outer lexical scope - LEXICAL # Contextual symbols in my or any outer's lexical scope - UNIT # Symbols in the outermost lexical scope of compilation unit - SETTING # Lexical symbols in the unit's DSL (usually CORE) - PARENT # Symbols in this package's parent package (or lexical scope) - CLIENT # The nearest CALLER that comes from a different package - -Other all-caps names are semi-reserved. We may add more of them in the -future, so you can protect yourself from future collisions by using mixed -case on your top-level packages. (We promise not to break any existing -top-level CPAN package, of course. Except maybe C, and then only for -coyotes.) - -The file's scope is known as C, but there are one or more lexical -scopes outside of that corresponding to the linguistic setting (often known -as the prelude in other cultures). Hence, the C scope is -equivalent to C. For a standard Perl program C is the -same as C, but various startup options (such as C<-n> or C<-p>) can -put you into a domain specific language, in which case C remains the -scope of the standard language, while C represents the scope -defining the DSL that functions as the setting of the current file. When used -as a search term in the middle of a name, C includes all its outer scopes -up to C. To get I the setting's outermost scope, use C instead. -See -also the C<-L>/C<--language> switch described in L. If a setting -wishes to gain control of the main execution, it merely needs to declare a -C
routine as documented in S06. In this case the ordinary execution -of the user's code is suppressed; instead, execution of the user's code is -entirely delegated to the setting's C
routine, which calls back to the -user's lexically embedded code with C<{YOU_ARE_HERE}>. - -The C<{YOU_ARE_HERE}> functions within the setting as a proxy for the user's -C block, so C<-n> and C<-p> may be implemented in a setting with: - - for $*ARGFILES.lines {YOU_ARE_HERE} # -n - map *.say, do for $*ARGFILES.lines {YOU_ARE_HERE} # -p - -or - - map {YOU_ARE_HERE}, $*ARGFILES.lines; # -n - map *.say, map {YOU_ARE_HERE}, $*ARGFILES.lines; # -p - -and the user may use loop control phasers as if they were directly in the -loop block. Any C in the user's code refers to the block outside of -C<{YOU_ARE_HERE}>. If used as a standalone statement, C<{YOU_ARE_HERE}> -runs as if it were a bare block. - -Note that, since the C of an C is the evaluated string itself, -the C of an C is the language in effect at the point of the -C, not the language in effect at the top of the file. (You may, -however, use C to get the setting of the code that is -executing the C.) In more traditional terms, the normal program is -functioning as the "prelude" of the C. - -So the outermost lexical scopes nest like this, traversed via C: - - CORE <= SETTING < UNIT < (your_block_here) - -The outermost package scopes nest like this, traversed via C: - - GLOBAL < (your_package_here) - -Your main program starts up in the C package and the C lexical -scope. Whenever anything is declared with "our" semantics, it inserts a -name into both the current package and the current lexical scope. (And "my" -semantics only insert into the current lexical scope.) Note that the -standard setting, C, is a lexical scope, not a package; the various -items that are defined within (or imported into) C are *not* in -C, which is pretty much empty when your program starts compiling, -and mostly only contains things you either put there yourself, or some other -module put there because you used that module. In general things defined -within (or imported into) C should only be declared or imported with -"my" semantics. All Perl code can see C anyway as the outermost -lexical scope, so there's no need to also put such things into C. - -The C package itself is accessible via C. The -C package is accessible via C. The C -package is not the parent of C. However, searching up the dynamic -stack for dynamic variables will look in all nested dynamic scopes (mapped -automatically to each call's lexical scope, not package scope) out to the -main dynamic scope; once all the dynamic scopes are exhausted, it also looks -in the C package and then in the C package, so C<$*OUT> -typically finds the process's standard output handle. Hence, C and -C serve as extra outer dynamic scopes, much like C and -C function as extra outer lexical scopes. - -Extra C scopes keep their identity and their nesting within -C, so you may have to go to C several times from C before -you get to C. Normally, however, there is only the core setting, in -which case C ends up meaning the same as C which is -the same as C. - -Extra C scopes are treated differently. Every compilation unit has -its own associated C package. As the currently compiling -compilation unit expresses the need for various other compilation units, the -global names known to those other units must be merged into the new unit's -C. (This includes the names in all the packages within the -global package.) If two different units use the same global name, they must -generally be taken to refer to the same item, but only if the type -signatures can be meshed (and augmentation rules followed, in the case of -package names). If two units provide package names with incompatible type -signatures, the compilation of the unit fails. In other words, you may not -use incompatible global types to provide a union type. However, if one or -the other unit underspecifies the type in a compatible way, the -underspecified type just takes on the extra type information as it learns -it. (Presumably some combination of Liskov substitution, duck-typing, and -run-time checking will prevent tragedy in the unit that was compiled with -the underspecified type. Alternately, the compiler is allowed to recompile -or re-examine the unit with the new type constraints to see if any issues -are certain to arise at run time, in which case the compiler is free to -complain.) - -Any dynamic variable declared with C in the user's main program -(specifically, the part compiled with C as the current package) is -accessible (by virtue of being in C) as a dynamic variable even if -not directly in the dynamic call chain. Note that dynamic vars do *not* -look in C for anything. (They I look in C if you're -running under a setting distinct from C, if that setting defines a -dynamic scope outside your main program, such as for the C<-n> or C<-p> -switch.) Context variables declared with C in the C or -C packages do not need to use the C<*> twigil, since the twigil is -stripped before searching those packages. Hence, your environment variables -are effectively declared without the sigil: - - augment package GLOBAL { our %ENV; } - -=head2 Interpolating into names - -You may interpolate a string into a package or variable name using -C<::($expr)> where you'd ordinarily put a package or variable name. The -string is allowed to contain additional instances of C<::>, which will be -interpreted as package nesting. You may only interpolate entire names, -since the construct starts with C<::>, and either ends immediately or is -continued with another C<::> outside the parens. Most symbolic references -are done with this notation: - - $foo = "Bar"; - $foobar = "Foo::Bar"; - $::($foo) # lexically-scoped $Bar - $::("MY::$foo") # lexically-scoped $Bar - $::("OUR::$foo") # package-scoped $Bar - $::("GLOBAL::$foo") # global $Bar - $::("PROCESS::$foo")# process $Bar - $::("PARENT::$foo") # current package's parent's $Bar - $::($foobar) # $Foo::Bar - $::($foobar)::baz # $Foo::Bar::baz - $::($foo)::Bar::baz # $Bar::Bar::baz - $::($foobar)baz # ILLEGAL at compile time (no operator baz) - -Note that unlike in Perl 5, initial C<::> doesn't imply global. Here as -part of the interpolation syntax it doesn't even imply package. After the -interpolation of the C<::()> component, the indirect name is looked up -exactly as if it had been there in the original source code, with priority -given first to leading pseudo-package names, then to names in the lexical -scope (searching scopes outwards, ending at C). The current package is -searched last. - -Use the C pseudopackage to limit the lookup to the current lexical -scope, and C to limit the scopes to the current package scope. - -=head2 Strict lookup - -When "strict" is in effect (which is the default except for one-liners), -non-qualified variables (such as C<$x> and C<@y>) are only looked up from -lexical scopes, but never from package scopes. - -To bind package variables into a lexical scope, simply say C. -To bind global variables into a lexical scope, predeclare them with C: - - use PROCESS <$IN $OUT>; - -Or just refer to them as C<$*IN> and C<$*OUT>. - -=head2 Direct lookup - -To do direct lookup in a package's symbol table without scanning, treat the -package name as a hash: - - Foo::Bar::{'&baz'} # same as &Foo::Bar::baz - PROCESS::<$IN> # Same as $*IN - Foo::<::Bar><::Baz> # same as Foo::Bar::Baz - -The C<::> before the subscript is required here, because the -C syntax is reserved for attaching a "WHENCE" initialization -closure to an autovivifiable type object. (see S12). - -Unlike C<::()> symbolic references, this does not parse the argument for -C<::>, nor does it initiate a namespace scan from that initial point. In -addition, for constant subscripts, it is guaranteed to resolve the symbol at -compile time. - -The null pseudo-package is reserved to mean the same search list as an -ordinary name search. That is, the following are all identical in meaning: - - $foo - $::{'foo'} - ::{'$foo'} - $:: - ::<$foo> - -That is, each of them scans lexical scopes outward, and then the current -package scope (though the package scope is then disallowed when "strict" is -in effect). - -As a result of these rules, you can write any arbitrary variable name as -either of: - - $::{'!@#$#@'} - ::{'$!@#$#@'} - -You can also use the C<< ::<> >> form as long as there are no spaces in the -name. - -=head2 Symbol tables - -The current lexical symbol table is now accessible through the -pseudo-package C. The current package symbol table is visible as -pseudo-package C. The C name refers to the C symbol table -immediately surrounding the current C, and C is the one -surrounding that one. - - our $foo = 41; - say $::foo; # prints 41, :: is no-op - { - my $foo = 42; - say MY::<$foo>; # prints "42" - say $MY::foo; # same thing - say $::foo; # same thing, :: is no-op here - - say OUR::<$foo>; # prints "41" - say $OUR::foo; # same thing - - say OUTER::<$foo>; # prints "41" (our $foo is also lexical) - say $OUTER::foo; # same thing - } - -You may not use any lexically scoped symbol table, either by name or by -reference, to add symbols to a lexical scope that is done compiling. (We -reserve the right to relax this if it turns out to be useful though.) - -=head2 Dynamic lookup - -The C package refers to the lexical scope of the (dynamically -scoped) caller. The caller's lexical scope is allowed to hide any -user-defined variable from you. In fact, that's the default, and a lexical -variable must have the trait "C" to be visible via C. -(C<$_>, C<$!> and C<$/> are always dynamic, as are any variables whose -declared names contain a C<*> twigil.) If the variable is not visible in the -caller, it returns C. Variables whose names are visible at the -point of the call but that come from outside that lexical scope are -controlled by the scope in which they were originally declared as dynamic. -Hence the visibility of C<< CALLER::<$*foo> >> is determined where C<$*foo> -is actually declared, not by the caller's scope (unless that's where it -happens to be declared). Likewise C<< CALLER::CALLER::<$x> >> depends only -on the declaration of C<$x> visible in your caller's caller. - -User-defined dynamic variables should generally be initialized with C<::=> -unless it is necessary for variable to be modified. (Marking dynamic -variables as readonly is very helpful in terms of sharing the same value -among competing threads, since a readonly variable need not be locked.) - -Empty C definitions defined with C<{*}> are considered invisible to -C, so a C may refer directly to the caller of the C -using a single C lookup. Autogenerated C entries follow the -same rule. - -=head2 C - -The C pseudo-package is just like C except that it starts -in the current dynamic scope and from there scans outward through all -dynamic scopes (frames) until it finds a dynamic variable of that name in -that dynamic frame's associated lexical pad. (This search is implied for -variables with the C<*> twigil; hence C<$*FOO> is equivalent to C<< -DYNAMIC::<$*FOO> >>.) If, after scanning outward through all those dynamic -scopes, there is no variable of that name in any immediately associated -lexical pad, it strips the C<*> twigil out of the name and looks in the -C package followed by the C package. If the value is not -found, it returns C. - -Unlike C, C will see a dynamic variable that is declared in -the current scope, since it starts searching 0 scopes up the stack rather -than 1. You may, however, use C<< CALLER::<$*foo> >> to bypass a dynamic -definition of C<$*foo> in your current scope, such as to initialize it with -the outer dynamic value: - - my $*foo ::= CALLER::<$*foo>; - -The C declarator may be used (without an initializer) on a dynamic -variable to perform a similar operation: - - temp $*foo; - -The main difference is that by default it initializes the new C<$*foo> with -its current value, rather than the caller's value. Also, it is allowed only -on read/write dynamic variables, since the only reason to make a copy of the -outer value would be because you'd want to override it later and then forget -the changes at the end of the current dynamic scope. - -You may also use C<< OUTER::<$*foo> >> to mean you want to start the search -in your outer lexical scope, but this will succeed only if that outer -lexical scope also happens to be one of your current I scopes. -That is, the same search is done as with the bare C<$*foo>, but any "hits" -are ignored until we've got to the C scope in our traversal. - -=head2 Package lookup - -There is no longer any special package hash such as C<%Foo::>. Just -subscript the package object itself as a hash object, the key of which is -the variable name, including any sigil. The package object can be derived -from a type name by use of the C<::> postfix: - - MyType::<$foo> - -(Directly subscripting the type with either square brackets or curlies is -reserved for various generic type-theoretic operations. In most other -matters type names and package names are interchangeable.) - -Typeglobs are gone. Use binding (C<:=> or C<::=>) to do aliasing. -Individual variable objects are still accessible through the hash -representing each symbol table, but you have to include the sigil in the -variable name now: C or the equivalent C<< -MyPackage::<$foo> >>. - -=head2 Globals - -Interpreter globals live in the C package. The user's program -starts in the C package, so "our" declarations in the mainline code -go into that package by default. Process-wide variables live in the -C package. Most predefined globals such as C<$*UID> and C<$*PID> -are actually process globals. - -=head2 The C package - -There is only ever a single C package. For an ordinary Perl -program running by itself, there is only one C package as well. -However, in certain situations (such as shared hosting under a webserver), -the actual process may contain multiple virtual processes or interpreters, -each running its own "main" code. In this case, the C namespace -holds variables that properly belong to the individual virtual process, -while the C namespace holds variables that properly belong to the -actual process as a whole. From the viewpoint of the program there is -little difference as long as all global variables are accessed as if they -were dynamic variables (by using the C<*> twigil). The process as a whole -may place restrictions on the mutability of process variables as seen by the -individual subprocesses. Also, individual subprocesses may not create new -process variables. If the process wishes to grant subprocesses the ability -to communicate via the C namespace, it must supply a writeable -dynamic variable to all the subprocesses granted that privilege. - -=head2 Dynamic variable creation - -It is illegal to assign or bind a dynamic variable that does not already -exist. It will not be created in C (or C) automatically, -nor is it created in any lexical scope. Instead, you must assign directly -using the package name to get that to work: - - GLOBAL::<$mynewvar> = $val; - -=head2 The magic input handle - -The magic command-line input handle is C<$*ARGFILES>. The arguments -themselves come in C<@*ARGS>. See also "Declaring a MAIN subroutine" in -S06. - -=head2 Magical access to documentation - -The Pod documentation in a file is accessible from code in the same file via -variables with a C<=> secondary sigil. C<$=data> is the accessor for your -C<=data> section(s), for instance. All Pod structures are available as a -hierarchical data structure, through C<$=pod>. As with C<*>, the C<=> may -also be used as a package name: C<$=::data>. - -=head2 Magical lexically scoped values - -Magical lexically scoped values live in variables with a C secondary -sigil. These are all values that are known to the compiler, and may in fact -be dynamically scoped within the compiler itself, and only appear to be -lexically scoped because dynamic scopes of the compiler resolve to lexical -scopes of the program. All C<$?> variables are considered constants, and -may not be modified after being compiled in. The user is also allowed to -define or (redefine) such constants: - - constant $?TABSTOP = 4; # assume heredoc tabs mean 4 spaces - -(Note that the constant declarator always evaluates its initialization -expression at compile time.) - -C<$?FILE> and C<$?LINE> are your current file and line number, for instance. -Instead of C<$?OUTER::FOO> you probably want to write C<< OUTER::<$?FOO> >>. -Within code that is being run during the compile, such as C blocks, -or macro bodies, or constant initializers, the compiler variables must be -referred to as (for instance) C<< COMPILING::<$?LINE> >> if the bare -C<$?LINE> would be taken to be the value during the compilation of the -currently running code rather than the eventual code of the user's -compilation unit. For instance, within a macro body C<$?LINE> is the line -within the macro body, but C<< COMPILING::<$?LINE> >> is the line where the -macro was invoked. See below for more about the C pseudo -package. - -Here are some possibilities: - - $?FILE Which file am I in? - $?LINE Which line am I at? - &?ROUTINE Which routine am I in? - &?BLOCK Which block am I in? - %?LANG What is the current set of interwoven languages? - -The following return objects that contain all pertinent info: - - $?KERNEL Which kernel am I compiled for? - $?DISTRO Which OS distribution am I compiling under - $?VM Which virtual machine am I compiling under - $?XVM Which virtual machine am I cross-compiling for - $?PERL Which Perl am I compiled for? - $?SCOPE Which lexical scope am I in? - $?PACKAGE Which package am I in? - $?MODULE Which module am I in? - $?CLASS Which class am I in? (as variable) - $?ROLE Which role am I in? (as variable) - $?GRAMMAR Which grammar am I in? - %?META The META6.json data associated with the module - %?RESOURCE Associated resource files, shortcut for %?META - -It is relatively easy to smartmatch these constant objects against pairs to -check various attributes such as name, version, or authority: - - given $?VM { - when :name :ver(v2) { ... } - when :name { ... } - when :name { ... } - when :name :ver(v6.*) { ... } - } - -Matches of constant pairs on constant objects may all be resolved at compile -time, so dead code can be eliminated by the optimizer. - -Note that some of these things have parallels in the C<*> space at run time: - - $*KERNEL Which kernel I'm running under - $*DISTRO Which OS distribution I'm running under - $*VM Which VM I'm running under - $*PERL Which Perl I'm running under - -You should not assume that these will have the same value as their -compile-time cousins. - -=head2 The C pseudopackage - -While C<$?> variables are constant to the run time, the compiler has to have -a way of changing these values at compile time without getting confused -about its own C<$?> variables (which were frozen in when the compile-time -code was itself compiled). The compiler can talk about these -compiler-dynamic values using the C pseudopackage. - -References to C variables are automatically hoisted into the -lexical scope currently being compiled. Setting or temporizing a -C variable sets or temporizes the incipient C<$?> variable in the -surrounding lexical scope that is being compiled. If nothing in the context -is being compiled, an exception is thrown. - - BEGIN { COMPILING::<$?FOO> = 42 } - say $?FOO; # prints 42 - { - say $?FOO; # prints 42 - } - { - BEGIN { temp COMPILING::<$?FOO> = 43 } # temporizes to *compiling* block - say $?FOO; # prints 43 - } - { - BEGIN { - COMPILING::<$?FOO> = 44; - say COMPILING::<$?FOO>; # prints 44, but $?FOO probably undefined - } - say $?FOO; # prints 44 - } - say $?FOO; # prints 42 (left scope of temp above) - $?FOO = 45; # always an error - COMPILING::<$?FOO> = 45; # an error unless we are compiling something - -Note that C<< CALLER::<$?FOO> >> might discover the same variable as -C>, but only if the compiling scope is the immediate -caller. Likewise C<< OUTER::<$?FOO> >> might or might not get you to the -right place. In the abstract, C> goes outwards -dynamically until it finds a compiling scope, and so is guaranteed to find -the "right" C<$?FOO>. (In practice, the compiler hopefully keeps track of -its current compiling scope anyway, so no scan is needed.) - -Perceptive readers will note that this subsumes various "compiler hints" -proposals. Crazy readers will wonder whether this means you could set an -initial value for other lexicals in the compiling scope. The answer is yes. -In fact, this mechanism is probably used by the exporter to bind names into -the importer's namespace. - -=head2 Switching parsers - -The currently compiling Perl parser is switched by modifying one of the -braided languages in C<< COMPILING::<%?LANG> >>. Lexically scoped parser -changes should temporize the modification. Changes from here to -end-of-compilation unit can just assign or bind it. In general, most parser -changes involve deriving a new grammar and then pointing one of the C<< -COMPILING::<%?LANG> >> entries at that new grammar. Alternately, the tables -driving the current parser can be modified without derivation, but at least -one level of anonymous derivation must intervene from the preceding Perl -grammar, or you might be messing up someone else's grammar. Basically, the -current set of grammars in C<%?LANG> has to belong only to the current -compiling scope. It may not be shared, at least not without explicit -consent of all parties. No magical syntax at a distance. Consent of the -governed, and all that. - -=head2 Slangs - -Individual sublanguages ("slangs") may be referred to using the C<~> twigil. -The following are useful: - - $~MAIN the current main language (e.g. Perl statements) - $~Quote the current root of quoting language - $~Quasi the current root of quasiquoting language - $~Regex the current root of regex language - $~Trans the current root of transliteration language - $~P5Regex the current root of the Perl 5 regex language - -Hence, when you are defining a normal Perl macro, you're replacing C<$~MAIN> -with a derived language, but when you define a new regex backslash sequence, -you're replacing C<$~Regex> with a derived language. (There may or may not -be a syntax in the main language to do this.) Note that such changes are -automatically scoped to the lexical scope; as with real slang, the -definitions are temporary and embedded in a larger language inherited from -the surrounding culture. - -Instead of defining macros directly you may also mix in one or more grammar -rules by lexically scoped declaration of a new sublanguage: - - augment slang Regex { # derive from $~Regex and then modify $~Regex - token backslash:std<\Y> { YY }; - } - -This tends to be more efficient since it only has to do one mixin at the end -of the block. Note that the slang declaration has nothing to do with -package C, but only with C<$~Regex>. Sublanguages are in their own -namespace (inside the current value of C<%?LANG>, in fact). Hence -C is modifying one of the local strands of a braided language, not -a package somewhere else. - -You may also supersede a sublang entirely if, for example, you just want to -disable that sublanguage in the current lexical scope: - - supersede slang P5Regex {} - m:P5/./; # kaboom - -If you supersede C
then you're replacing the Perl parser entirely. -This might be done by, say, the "use COBOL" declaration. C<:-)> - -=head2 Extended identifiers - -It is often convenient to have names that contain arbitrary characters or -other data structures. Typically these uses involve situations where a set -of entities shares a common "short" name, but still needs for each of its -elements to be identifiable individually. For example, you might use a -module whose short name is C, but the complete long name of a -module includes its version, naming authority, and perhaps even its source -language. Similarly, sets of operators work together in various syntactic -categories with names like C, C, C, etc. The long -names of these operators, however, often contain characters that are -excluded from ordinary identifiers. - -For all such uses, an identifier followed by a subscript-like adverbial form -(see below) is considered an I: - - infix:<+> # the official name of the operator in $a + $b - infix:<*> # the official name of the operator in $a * $b - infix:«<=» # the official name of the operator in $a <= $b - prefix:<+> # the official name of the operator in +$a - postfix:<--> # the official name of the operator in $a-- - -This name is to be thought of semantically, not syntactically. That is, the -bracketing characters used do not count as part of the name; only the quoted -data matters. These are all the same name: - - infix:<+> - infix:<<+>> - infix:«+» - infix:['+'] - -Despite the appearance as a subscripting form, these names are resolved not -at run time but at compile time. The pseudo-subscripts need not be simple -scalars. These are extended with the same two-element list: - - circumfix:«<< >>» - circumfix:['<<','>>'] - -An identifier may be extended with multiple named identifier extensions, in -which case the names matter but their order does not. These name the same -module: - - use ThatModule:auth:ver<2.7.18.28.18> - use ThatModule:ver<2.7.18.28.18>:auth - -Adverbial syntax is described in L. - -=head1 Literals - -Perl 6 has a rich set of literal forms, many of which can be used for -textual input as well. For those forms simple enough to be allowed, the -C function treats such a string value as if it were a literal in the -program. In some cases the C function will be applied on your -behalf, and in other cases you must do so explicitly. The rationale for -this function is that there are many cases where the programmer or user is -forced to use a string type to represent a value that is intended to become -a numeric type internally. Committing pre-emptively to either a string type -or a numeric type is likely to be wrongish, so Perl 6 instead provides the -concept of I literals. How these work is described below in -L. - -When used as literals in a program, most of these forms produce an exact -type, and are not subject to C processing. The exceptions will be -noted as we go. - -=head2 Underscores - -A single underscore is allowed only between any two digits in a literal -number, where the definition of digit depends on the radix. (A single -underscore is also allowed between a radix prefix and a following digit, as -explained in the next section.) Underscores are not allowed anywhere else in -any numeric literal, including next to the radix point or exponentiator, or -at the beginning or end. - -=head2 Radix markers - -Initial C<0> no longer indicates octal numbers by itself. You must use an -explicit radix marker for that. Pre-defined radix prefixes include: - - 0b base 2, digits 0..1 - 0o base 8, digits 0..7 - 0d base 10, digits 0..9 - 0x base 16, digits 0..9,a..f (case insensitive) - -Each of these allows an optional underscore after the radix prefix but -before the first digit. These all mean the same thing: - - 0xbadcafe - 0xbad_cafe - 0x_bad_cafe - -=head2 General radices - -The general radix form of a number involves prefixing with the radix in -adverbial form: - - :10<42> same as 0d42 or 42 - :16 same as 0xDEADBEEF - :8<177777> same as 0o177777 (65535) - :2<1.1> same as 0b1.1 (0d1.5) - -Extra digits are assumed to be represented by C..C and C..C, so -you can go up to base 36. (Use C and C for base twelve, not C and -C.) Alternatively you can use a list of values, which is convenient for -decimals: - - :60[12,34,56] # 12 * 3600 + 34 * 60 + 56 - :100[3,'.',14,16] # pi - -All numbers representing digits must be less than the radix, or an error -will result (at compile time if constant-folding can catch it, or at run -time otherwise). - -Any radix may include a fractional part. A dot is never ambiguous because -you have to tell it where the number ends: - - :16 # fraction - :16.face # method call - -=head2 Exponentials - -Only base 10 (in any form) allows an additional exponentiator starting with -'e' or 'E'. All other radixes must either rely on the constant folding -properties of ordinary multiplication and exponentiation, or supply the -equivalent two numbers as part of the string, which will be interpreted as -they would outside the string, that is, as decimal numbers by default: - - :16 * 16**8 - :16 - -It's true that only radixes that define C as a digit are ambiguous that -way, but with any radix it's not clear whether the exponentiator should be -10 or the radix, and this makes it explicit: - - 0b1.1e10 ILLEGAL, could be read as any of: - - :2<1.1> * 2 ** 10 1536 - :2<1.1> * 10 ** 10 15,000,000,000 - :2<1.1> * :2<10> ** :2<10> 6 - -So we write those as - - :2<1.1*2**10> 1536 - :2<1.1*10**10> 15,000,000,000 - :2«1.1*:2<10>**:2<10>» 6 - -The generic string-to-number converter will recognize all of these forms -(including the * form, since constant folding is not available to the run -time). Also allowed in strings are leading plus or minus, and maybe a -trailing Units type for an implied scaling. Leading and trailing whitespace -is ignored. Note also that leading C<0> by itself I implies octal in -Perl 6. - -In all these cases, the type produced will be the narrowest of C, -C, or C that can accurately represent the number. If no type can -represent it exactly, it should be returned as either a C or a C, -whichever is more accurate. (C will tend to be more accurate for -numbers of normal or large magnitude, while C may be more accurate -for numbers of very small magnitude, since the C's size mismatch of -numerator and denominator will eventually cost more accuracy than the Num's -exponent overhead. As a limiting case, a C cannot represent any -number smaller than C<< :10<1*2**-64> >>.) - -A consequence of the preceding is that you cannot make a C using -colon notation. You must rely on constructors and constant folding: - - FatRat.new(1,2) ** 128 - FatRat.new(1, 2 ** 128) # same thing - -=head2 Conversion functions - -Any of the adverbial forms may be used as a function: - - :2($x) # "bin2num" - :8($x) # "oct2num" - :10($x) # "dec2num" - :16($x) # "hex2num" - -Think of these as setting the default radix, not forcing it. Like Perl 5's -old C function, any of these will recognize a number starting with a -different radix marker and switch to the other radix. However, note that -the C<:16()> converter function will interpret leading C<0b> or C<0d> as hex -digits, not radix switchers. - -Use of the functional form on anything that is not a string will throw an -exception explaining that the user has confused a number with the textual -representation of a number. This is to catch errors such as a C<:8(777)> -that should have been C<< :8<777> >>, or the attempt to use the function in -reverse to produce a textual representation from a number. - -=head2 Rational literals - -Rational literals are indicated by separating two integer literals (in any -radix) with a slash, and enclosing the whole in angles: - - <1/2> # one half literal Rat - -Whitespace is not allowed on either side of the slash or it will be split -under normal quote-words semantics: - - < 1 / 2 > # (IntStr('1'), '/', IntStr('2')) - < 1/2 > # okay, returns RatStr('1/2') rather than Rat - -Because of constant folding, you may often get away with leaving out the -angles: - - 1/2 # 1 divided by 2 - -However, in that case you have to pay attention to precedence and -associativity. The following does I cube C<2/3>: - - 2/3**3 # 2/(3**3), not (2/3)**3 - -Decimal fractions not using "e" notation are also treated as literal C -values: - - 6.02e23.WHAT # Num - 1.23456.WHAT # Rat - 0.11 == 11/100 # True - -Literals specified without spaces in angle brackets are exempt from C -processing, so C<< <1/2> >> produces a value that is C, while C<< < 1/2 -> >> produces a value that is both a C and a C. See L below. - -=head2 Complex literals - -Complex literals are similarly indicated by writing an addition or -subtraction of two real numbers (again, without spaces around the operators) -inside angles: - - <5.2+1e42i> - <-3-1i> - -As with rational literals, constant folding would produce the same complex -number, but this form parses as a single term, ignoring surrounding -precedence. - -(Note that these are not actually special syntactic forms: both rational and -complex literal forms fall out naturally from the semantic rules of qw -quotes described below.) - -Literals specified without spaces in angle brackets are exempt from C -processing, so C<< <1+2i> >> produces a value that is a C while C<< -< 1+2i > >> produces a value that is both a C and a C. See -L below. - -=head2 C literals - -C literals look similar to integer literals with radix markers, but -use curlies instead of angles: - - :2{0010_1110_1000_10} a blob1, base 2, 1 bit per column - :4{} a blob2, 2 bits per column - :8{5235 0437 6} a blob3, 3 bits per column - :16{A705E} a blob4, 4 bits per column - -Whitespace and underscores are allowed but ignored. - -=head2 Radix interpolation - -Characters indexed by hex numbers can be interpolated into strings by -introducing with C<"\x">, followed by either a bare hex number (C<"\x263a">) -or a hex number in square brackets (C<"\x[263a]">). Similarly, C<"\o12"> -and C<"\o[12]"> interpolate octals--but generally you should be using hex in -the world of Unicode. Multiple characters may be specified within any of -the bracketed forms by separating the numbers with comma: C<"\x[41,42,43]">. -You must use the bracketed form to disambiguate if the unbracketed form -would "eat" too many characters, because all of the unbracketed forms eat as -many characters as they think look like digits in the radix specified. None -of these notations work in normal Perl code. They work only in -interpolations and regexes and the like. - -Note that the inside of the brackets is not an expression, and you may not -interpolate there, since that would be a double interpolation. Use curlies -to interpolate the values of expressions. - -The old C<\123> form is now illegal, as is the C<\0123> form. Only C<\0> -remains, and then only if the next character is not in the range -C<'0'..'7'>. Octal characters must use C<\o> notation. Note also that -backreferences are no longer represented by C<\1> and the like--see S05. - -=head2 Angle quotes (quote words) - -The C quote operator now has a bracketed form: C<< ->>. When used as a subscript it performs a slice equivalent to -C<{'foo','bar'}>. Elsewhere it is equivalent to a parenthesized list of -strings: C<< ('foo','bar') >>. Since parentheses are generally reserved -just for precedence grouping, they merely autointerpolate in flat list -context. Therefore - - @a = 1, < x y >, 2; - -is equivalent to: - - @a = 1, ('x', 'y'), 2; - -which is the same as: - - @a = 1, 'x', 'y', 2; - -In item context, the implied grouping parentheses are still there, so - - $a = < a b >; - -is equivalent to: - - $a = ('a', 'b'); - -which assigns a C to the variable. On the other hand, if you -backslash the list: - - $a = \; - -it is like: - - $a = \('a', 'b'); - -and ends up storing a C object (which weeds out any named arguments -into a separate structure, in contrast to a C, which keeps -everything in its original list). - -Binding is different from assignment. If bound to a signature, the C<< >> list will be promoted to a C object, but if bound to a -parameter, it will make the flattening/slicing decision based on the nature -of the individual parameter. That is, if you pass C<< >> as an -argument, it will bind as a single item to a positional or slice parameter, -and as two items to a slurpy parameter. - -But note that under the parenthesis-rewrite rule, a single value will still -act like a single value. These are all the same: - - $a = < a >; - $a = ('a'); - $a = 'a'; - -Strings within angle brackets are subject to C processing, and any -component that parses successfully as a numeric literal will become both a -string and a number. See L below. - -=head3 Explicit List construction - -As the previous section shows, a list is not automatically constructed by -parens; the list is actually constructed by the comma, not by the parens. -To force a single value to become a composite object in item context, either -add a comma inside parens, or use an appropriate constructor or composer for -clarity as well as correctness: - - $a = (< a >,); - $a = ('a',); - $a = List.new('a'); - $a = ['a']; - -=head3 Empty List - -Even though there is no comma in it, the empty list is represented by -C<()>. Normally, one could itemize this by prefixing a C<$> (as in C<$()>), -but that translates to the special syntax form C<$( $/.made // Str($/) )>. -Instead, one can C<().item>, or less legibly, introduce a space as in C<$( -)>. - -=head3 Disallowed forms - -The degenerate case C<< <> >> is disallowed as a probable attempt to do IO -in the style of Perl 5; that is now written C. (C<< >> is -also disallowed.) Empty lists are better written with C<()> in any case -because C<< <> >> will often be misread as meaning C<('')>. (Likewise the -subscript form C<< %foo<> >> should be written C<%foo{}> to avoid misreading -as C<@foo{''}>.) If you really want the angle form for stylistic reasons, -you can suppress the error by putting a space inside: C<< < > >>. - -=head3 Relationship between <> and «» - -Much like the relationship between single quotes and double quotes, single -angles do not interpolate while double angles do. The double angles may be -written either with French quotes, C<«$foo @bar[]»>, or with ASCII quotes, -C<<< <<$foo @bar[]>> >>>, as the ASCII workaround. The implicit split is -done after interpolation, but respects quotes in a shell-like fashion, so -that C<«'$foo' "@bar[]"»> is guaranteed to produce a list of two "words" -equivalent to C<< ('$foo', "@bar[]") >>. C notation is also -recognized inside C<«...»> and such "words" are returned as C objects. - -Colon pairs (but not arrow pairs) are recognized within double angles. In -addition, the double angles allow for comments beginning with C<#>. These -comments work exactly like ordinary comments in Perl code. Unlike in the -shells, any literal C<#> must be quoted, even ones without whitespace in -front of them, but note that this comes more or less for free with a colon -pair like C<< :char<#x263a> >>, since comments only work in double angles, -not single. - -=head2 Adverbial Pair forms - -There is now a generalized adverbial form of Pair notation, also known -as a "colon pair" form. The following table shows the correspondence -to the "fatarrow" notation: - - Fat arrow Adverbial pair Paren form - ========= ============== ========== - a => True :a - a => False :!a - a => 0 :a(0) - a => $x :a($x) - a => 'foo' :a :a() - a => :a :a() - a => «$foo @bar» :a«$foo @bar» :a(«$foo @bar») - a => {...} :a{...} :a({...}) - a => [...] :a[...] :a([...]) - a => $a :$a - a => @a :@a - a => %a :%a - a => &a :&a - a => %foo %foo:p - -The fatarrow construct may be used only where a term is expected because -it's considered an expression in its own right, since the fatarrow itself is -parsed as a normal infix operator (even when autoquoting an identifier on -its left). Because the left side is a general expression, the fatarrow form -may be used to create a Pair with I value as the key. On the other -hand, when used as above to generate C objects, the adverbial forms -are restricted to the use of identifiers as keys. You must use the fatarrow -form to generate a C where the key is not an identifier. - -Despite that restriction, it's possible for other things to come between a -colon and its brackets; however, all of the possible non-identifier -adverbial keys are reserved for special syntactical forms. Perl 6 currently -recognizes decimal numbers and the null key. In the following table the -first and second columns do I mean the same thing: - - Simple pair DIFFERS from which means - =========== ============ =========== - 2 => <101010> :2<101010> radix literal 0b101010 - 8 => <123> :8<123> radix literal 0o123 - 16 => :16 radix literal 0xdeadbeef - 16 => $somevalue :16($somevalue) radix conversion function - '' => $x :($x) signature literal - '' => ($x,$y) :($x,$y) signature literal - '' => : name extension - '' => «x» :«x» name extension - '' => [$x,$y] :[$x,$y] name extension - '' => { .say } :{ .say } adverbial block (not allowed on names) - -All of the adverbial forms (including the normal ones with identifier keys) -are considered special tokens and are recognized in various positions in -addition to term position. In particular, when used where an infix would be -expected they modify the previous topmost operator that is tighter in -precedence than "loose unary" (see S03): - - 1 == 100 :fuzz(3) # calls: infix:<==>(1, 100, fuzz => 3) - -Within declarations the adverbial form is used to rename parameter -declarations: - - sub foo ( :externalname($myname) ) {...} - -Adverbs modify the meaning of various quoting forms: - - q:x 'cat /etc/passwd' - -When appended to an identifier (that is, in postfix position), the adverbial -syntax is used to generate unique variants of that identifier; this syntax -is used for naming operators such as C<< infix:<+> >> and -multiply-dispatched grammatical rules such as C. When -so used, the adverb is considered an integral part of the name, so C<< -infix:<+> >> and C<< infix:<-> >> are two different operators. Likewise C<< -prefix:<+> >> is different from C<< infix:<+> >>. (The notation also has -the benefit of grouping distinct identifiers into easily accessible sets; -this is how the standard Perl 6 grammar knows the current set of infix -operators, for instance.) - -Only identifiers that produce a list of one or more values (preferably -strings) are allowed as name extensions; in particular, closures do not -qualify as values, so the C<:{...}> form is not allowed as a name extender. -In particular, this frees up the block form after a method name, so it -allows us to parse a block as a method argument: - - @stuff.sort:{ +$_ } - -These might look like it is using pairs, but it is really equivalent to - - @stuff.sort: { +$_ } - -So the colons here are not really introducing pairs, but rather introducing -the argument list of the method. In any other location, C<:{...}> would be -taken in one of two ways, depending on whether the brackets define a closure -or a hash. If taken as a closure, C<:{...}> creates a pair mapping the null -key to the closure. If taken as a hash composer, the null key is ignored, -and C<:{...}> creates an object-keyed hash rather than the string-keyed hash -that C<{...}> would without the colon.) - -Either fatarrow or adverbial pair notation may be used to pass named -arguments as terms to a function or method. After a call with parenthesized -arguments, only the adverbial syntax may be used to pass additional -arguments. This is typically used to pass an extra block: - - find($directory) :{ when not /^\./ } - -This just naturally falls out from the preceding rules because the adverbial -block is in operator position, so it modifies the "find operator". (Parens -aren't considered an operator.) - -Note that (as usual) the C<{...}> form (either identifier-based or special) -can indicate either a closure or a hash depending on the contents. It does -I indicate a subscript, since C<:key{}> is really equivalent to C<< key -=> {} >>, and the braces are not behaving as a postfix at all. (The -function to which it is passed can I the value as a subscript if it -chooses, however.) - -Note also that the C<< >> form is not a subscript and is therefore -equivalent not to C<.{'a','b'}> but rather to C<('a','b')>. Bare C<< >> -turns into C<('a')> rather than C<('a',)>. (However, as with the other -bracketed forms, the value may end up being used as a subscript depending on -context.) - -Two or more adverbs can always be strung together without intervening -punctuation anywhere a single adverb is acceptable. When used as named -arguments in an argument list, you I put comma between, because they're -just ordinary named arguments to the function, and a fatarrow pair would -work the same. However, this comma is allowed only when the first pair -occurs where a term is expected. Where an infix operator is expected, the -adverb is always taken as modifying the nearest preceding operator that is -not hidden within parentheses, and if you string together multiple such -pairs, you may not put commas between, since that would cause subsequent -pairs to look like terms. (The fatarrow form is not allowed at all in -operator position.) See S06 for the use of adverbs as named arguments. - -The negated form (C<:!a>) and the sigiled forms (C<:$a>, C<:@a>, C<:%a>) -never take an argument and don't care what the next character is. They are -considered complete. These forms require an identifier to serve as the key. -A sigiled form that includes a twigil will not include the twigil in the -key. - -For identifiers that take a non-negative integer argument, it is allowed to -abbreviate, for example, C<:sweet(16)> to C<:16sweet>. (This is -distinguishable from the C<< :16 >> form, which never has an -alphabetic character following the number.) Only literal non-negative -integers numbers may be swapped this way. Please note that this abbreviation -allows: - - s:2nd/foo/bar/ # or 3rd, 4th, 5th etc. - -The other forms of adverb (including the bare C<:a> form) I look for -an immediate bracketed argument, and will slurp it up. If that's not -intended, you must use whitespace between the adverb and the opening -bracket. The syntax of individual adverbs is the same everywhere in Perl 6. -There are no exceptions based on whether an argument is wanted or not. -(There is a minor exception for quote and regex adverbs, which accept -I parentheses as their bracketing operator, and ignore other brackets, -which must be placed in parens if desired. See "Paren form" in the table -above.) - -Except as noted above, the parser always looks for the brackets. Despite -not indicating a true subscript, the brackets are similarly parsed as -postfix operators. As postfixes the brackets may be separated from their -initial C<:foo> with either unspace or dot (or both), but nothing else. - -Regardless of syntax, adverbs used as named arguments (in either term or -infix position) generally show up as optional named parameters to the -function in question--even if the function is an operator or macro. The -function in question neither knows nor cares how weird the original syntax -was. - -=head2 C forms - -In addition to C and C, there is now the base form C which does -I interpolation unless explicitly modified to do so. So C is really -short for C and C is short for C. In fact, all quote-like -forms derive from C with adverbs: - - q// Q :q // - qq// Q :qq // - rx// Q :regex // - s/// Q :subst /// - tr/// Q :trans /// - -Adverbs such as C<:regex> change the language to be parsed by switching to a -different parser. This can completely change the interpretation of any -subsequent adverbs as well as the quoted material itself. - - q:s// Q :q :scalar // - rx:s// Q :regex :scalar // - -Just as C has the short form C<'...'>, and C has the short -form C<"...">, the completely quoted C has a short form that uses -halfwidth corner brackets: C<｢...｣>. - -=head2 Adverbs on quotes - -Generalized quotes may now take adverbs: - - Short Long Meaning - ===== ==== ======= - :x :exec Execute as command and return results - :w :words Split result on words (no quote protection) - :ww :quotewords Split result on words (with quote protection) - :v :val Evaluate word or words for value literals - :q :single Interpolate \\, \q and \' (or whatever) - :qq :double Interpolate with :s, :a, :h, :f, :c, :b - :s :scalar Interpolate $ vars - :a :array Interpolate @ vars - :h :hash Interpolate % vars - :f :function Interpolate & calls - :c :closure Interpolate {...} expressions - :b :backslash Interpolate \n, \t, etc. (implies :q at least) - :to :heredoc Parse result as heredoc terminator - :regex Parse as regex - :subst Parse as substitution - :trans Parse as transliteration - :code Quasiquoting - :p :path Return a Path object (see S16 for more options) - -You may omit the first colon by joining an initial C, C, or C with -a single short form adverb, which produces forms like: - - qw /a b c/; # P5-esque qw// meaning q:w - Qc '...{$x}...'; # Q:c//, interpolate only closures - qqx/$cmd @args[]/ # equivalent to P5's qx// - -(Note that C doesn't interpolate.) - -If you want to abbreviate further, just define a macro: - - macro qx { 'qq:x ' } # equivalent to P5's qx// - macro qTO { 'qq:x:w:to ' } # qq:x:w:to// - macro quote:<❰ ❱> ($text) { quasi { {{{$text}}}.quoteharder } } - -All the uppercase adverbs are reserved for user-defined quotes. All Unicode -delimiters above Latin-1 are reserved for user-defined quotes. - -A consequence of the above is that we can now say: - - %hash = qw:c/a b c d {@array} {%hash}/; - -or - - %hash = qq:w/a b c d {@array} {%hash}/; - -to interpolate items into a C. Conveniently, arrays and hashes -interpolate with only whitespace separators by default, so the subsequent -split on whitespace still works out. (But the built-in C<«...»> quoter -automatically does interpolation equivalent to C. The -built-in C<< <...> >> is equivalent to C.) - -=head2 The C<:val> modifier - -The C<:v>/C<:val> modifier runs each word through the C function, -which will attempt to recognize literals as defined by the current slang. -(See L below.) Only pure literals such as -numbers, versions, and enums are so recognized; all other words are left as -strings. In any case, use of such an intuited value as a string will -reproduce the original string including any leading or trailing whitespace: - - say +val(' +2/4 ') # '0.5' - say ~val(' +2/4 ') # ' +2/4 ' - -Of course, words derived from C<:w> and C<:ww> will not have any whitespace, -since that is what the words are split apart on. - -=head2 Whitespace before adverbs - -Whitespace is allowed between the "q" and its adverb: C. - -=head2 Overriding the definitions of quoting keywords - -If you define an identifier (either as a term or a subroutine) that happens -to shadow one of the quoting or matching keywords, that keyword is no longer -available for quoting purposes: - - my \q = 42; say q / 2; # prints 21 - sub m { 42 }; say m / 2; # prints 21 - -Unlike with keyword overrides, it doesn't matter whether there's whitespace -after it; the name will always just be parsed as a term or function call, -unless followed explicitly by a colon. Generally you can work around such a -definition by using a related form of the same quote, or by adding a useless -modifier (either with or without the colon): - - my \q = 42; say Q:q /2/; # prints 2 - my \q = 42; say qs /2/; # prints 2 - my \q = 42; say q:s /2/; # prints 2 - - sub m { 42 }; say / 2 /; # matches 2 - sub m { 42 }; say m:1st/ 2 /; # matches 2 - -=head2 Delimiters of quoting forms - -For these "q" forms the choice of delimiters has no influence on the -semantics. That is, C<''>, C<"">, C<< <> >>, C<«»>, C<``>, C<()>, C<[]>, -and C<{}> have no special significance when used in place of C as -delimiters. There may be whitespace before the opening delimiter. (Which is -mandatory for parens because C is a subroutine call and C is an -adverb with arguments). A colon may never be used as the delimiter since it -will always be taken to mean another adverb regardless of what's in front of -it. Nor may a C<#> character be used as the delimiter since it is always -taken as whitespace (specifically, as a comment). You may not use -whitespace or alphanumerics for delimiters. - -=head2 Quotes from Macros - -New quoting constructs may be declared as macros: - - macro quote: (*%adverbs) {...} - -Note: macro adverbs are automatically evaluated at macro call time if the -adverbs are included in the parse. If an adverb needs to affect the parsing -of the quoted text of the macro, then an explicit named parameter may be -passed on as a parameter to the C subrule, or used to select -which subrule to invoke. - -=head2 Interpolating into a single-quoted string - -You may interpolate double-quotish text into a single-quoted string using -the C<\qq[...]> construct. Other "q" forms also work, including -user-defined ones, as long as they start with "q". Otherwise you'll just -have to embed your construct inside a C<\qq[...]>. - -=head2 Interpolation rules - -Bare scalar variables always interpolate in double-quotish strings. Bare -array, hash, and subroutine variables may I be interpolated. -However, any scalar, array, hash or subroutine variable may start an -interpolation if it is followed by a sequence of one or more bracketed -dereferencers: that is, any of: - -=over 4 - -=item 1. An array subscript - -=item 2. A hash subscript - -=item 3. A set of parentheses indicating a function call - -=item 4. Any of 1 through 3 in their B form - -=item 5. A method call that includes argument parentheses - -=item 6. A sequence of one or more unparenthesized method call, followed by any of 1 through 5 - -=back - -In other words, this is legal: - - "Val = $a.ord.fmt('%x')\n" - -and is equivalent to - - "Val = { $a.ord.fmt('%x') }\n" - -However, no interpolated postfix may start with a backslash, so any -backslash or unspace is not recognized, but instead will be assumed to be -part of the string outside of the interpolation, and subject to the normal -backslashing rules of that quote context: - - my $a = 42; - "Val = $a\[junk\]"; # Val = 42[junk] - "Val = $a\[junk]"; # Val = 42[junk] - "Val = $a\ [junk]"; # Val = 42 [junk] - "Val = $a\.[junk]"; # Val = 42.[junk] - - -=head3 Arrays - -In order to interpolate an entire array, it's necessary now to subscript -with empty brackets: - - print "The answers are @foo[]\n" - -Note that this fixes the spurious "C<@>" problem in double-quoted email -addresses. - -As with Perl 5 array interpolation, the elements are separated by a space. -(Except that a space is not added if the element already ends in some kind -of whitespace. In particular, a list of pairs will interpolate with a tab -between the key and value, and a newline after the pair.) - -=head3 Hashes - -In order to interpolate an entire hash, it's necessary to subscript with -empty braces or angles: - - print "The associations are:\n%bar{}" - print "The associations are:\n%bar<>" - -Note that this avoids the spurious "C<%>" problem in double-quoted printf -formats. - -By default, keys and values are separated by tab characters, and pairs are -separated by newlines. (This is almost never what you want, but if you -want something polished, you can be more specific.) - -=head3 Sub calls - -In order to interpolate the result of a sub call, it's necessary to include -both the sigil and parentheses: - - print "The results are &baz().\n" - -=head3 Method calls - -In order to interpolate the result of a method call without arguments, it's -necessary to include parentheses or extend the call with something ending in -brackets: - - print "The attribute is $obj.attr().\n" - print "The attribute is $obj.attr.\n" - -The method is called in item context. (If it returns a list, that list is -interpolated as if it were an array.) - -It is allowed to have a cascade of argumentless methods as long as the last -one ends with parens: - - print "The attribute is %obj.keys.sort.reverse().\n" - -(The cascade is basically counted as a single method call for the -end-bracket rule.) - -=head3 Multiple dereferencers - -Multiple dereferencers may be stacked as long as each one ends in some kind -of bracket or is a bare method: - - print "The attribute is @baz[3](1, 2, 3).gethash.{$xyz}.attr().\n" - -Note that the final period above is not taken as part of the expression -since it doesn't introduce a bracketed dereferencer. The parens are not -required on the C<.gethash>, but they are required on the C<.attr()>, since -that terminates the entire interpolation. - -In no case may any of the top-level components be separated by whitespace or -unspace. (These are allowed, though, inside any bracketing constructs, such -as in the C<(1, 2, 3)> above.) - -=head3 Closures - -A bare closure also interpolates in double-quotish context. It may not be -followed by any dereferencers, since you can always put them inside the -closure. The expression inside is evaluated in string item context. You -can force list context on the expression using the C operator if -necessary. A closure in a string establishes its own lexical scope. -(Expressions that sneak in without curlies, such as C<$(...)>, do not -establish their own lexical scope, but use the outer scope, and may even -declare variables in the outer scope, since all the code inside (that isn't -in an C) is seen at compile time.) - -The following means the same as the previous example. - - print "The attribute is { @baz[3](1,2,3).gethash.{$xyz}.attr }.\n" - -The final parens are unnecessary since we're providing "real" code in the -curlies. If you need to have double quotes that don't interpolate curlies, -you can explicitly remove the capability: - - qq:c(0) "Here are { $two uninterpolated } curlies"; - -or equivalently: - - qq:!c "Here are { $two uninterpolated } curlies"; - -Alternately, you can build up capabilities from single quote to tell it -exactly what you I want to interpolate: - - q:s 'Here are { $two uninterpolated } curlies'; - -=head3 Twigils - -Secondary sigils (twigils) have no influence over whether the primary sigil -interpolates. That is, if C<$a> interpolates, so do C<$^a>, C<$*a>, C<$=a>, -C<$?a>, C<$.a>, etc. It only depends on the C<$>. - -=head3 Other expressions - -No other expressions interpolate. Use curlies. - -=head3 Class methods - -A class method may not be directly interpolated. Use curlies: - - print "The dog bark is {Dog.bark}.\n" - -=head3 Old disambiguation - -The old disambiguation syntax: - - ${foo[$bar]} - ${foo}[$bar] - -is dead. Use closure curlies instead: - - {$foo[$bar]} - {$foo}[$bar] - -(You may be detecting a trend here...) - -=head3 Topical methods - -To interpolate a topical method, use curlies: C<"{.bark}">. - -=head3 Function calls - -To interpolate a function call without a sigil, use curlies: C<"{abs $var}">. - -=head3 Backslash sequences - -Backslash sequences still interpolate, but there's no longer any C<\v> to -mean I, whatever that is... (C<\v> now matches vertical -whitespace in a regex.) Literal character representations are: - - \a BELL - \b BACKSPACE - \t TAB - \n LINE FEED - \f FORM FEED - \r CARRIAGE RETURN - \e ESCAPE - -=head3 Other functions - -There's also no longer any C<\L>, C<\U>, C<\l>, C<\u>, or C<\Q>. Use -curlies with the appropriate function instead: C<"{tclc $word}">. - -=head3 Unicode codepoints - -You may interpolate any Unicode codepoint by name using C<\c> and square -brackets: - - "\c[NEGATED DOUBLE VERTICAL BAR DOUBLE RIGHT TURNSTILE]" - -Multiple codepoints constituting a single character may be interpolated with -a single C<\c> by separating the names with comma: - - "\c[LATIN CAPITAL LETTER A, COMBINING RING ABOVE]" - -Whether that is regarded as one character or two depends on the Unicode -support level of the current lexical scope. It is also possible to -interpolate multiple codepoints that do not resolve to a single character: - - "\c[LATIN CAPITAL LETTER A, LATIN CAPITAL LETTER B]" - -[Note: none of the official Unicode character names contains comma.] - -You may also put one or more decimal numbers inside the square brackets: - - "\c[13,10]" # CRLF - -Any single decimal number may omit the brackets: - - "\c8" # backspace - -(Within a regex you may also use C<\C> to match a character that is not the -specified character.) - -If the character following C<\c> or C<\C> is neither a left square bracket -nor a decimal digit, the single following character is turned into a control -character by the usual trick of XORing the 64 bit. This allows C<\c@> for -NULL and C<\c?> for DELETE, but note that the ESCAPE character may not be -represented that way; it must be represented something like: - - \e - \c[ESCAPE] - \c27 - \x1B - \o33 - -Obviously C<\e> is preferred when brevity is needed. - -=head3 Backslashing - -Any character that I start an interpolation in the current quote -context may be protected from such interpolation by prefixing with -backslash. The backslash is always removed in this case. - -The treatment of backslashed characters that would I have introduced an -interpolation varies depending on the type of quote: - -=over 4 - -=item 1. - -Any quoting form that includes C or C<:qq> in its semantic derivation -(including the normal double quote form) assumes that all backslashes are to -be considered meaningful. The meaning depends on whether the following -character is alphanumeric; if it is, the non-interpolating sequence produces -a compile-time error. If the character is non-alphanumeric, the backslash -is silently removed, on the assumption that the string was erroneously -backslashed by an overenthusiastic algorithm or programmer. - -=item 2. - -All other quoting forms (including standard single quotes) assume that -non-interpolating sequences are to be left unaltered because they are -probably intended to pass through to the result. Backslashes are removed -I for the terminating quote or for characters that would interpolate -if unbackslashed. (In either case, a special exception is made for -brackets; if the left bracket would interpolate, the right bracket may -optionally also be backslashed, and if so, the backslash will be removed. -If brackets are used as the delimiters, both left and right I be -backslashed the same, since they would otherwise be counted wrong in the -bracket count.) - -=back - -As a consequence, these all produce the same literal string: - - " \{ this is not a closure } " - " \{ this is not a closure \} " - q:c / \{ this is not a closure } / - q:c / \{ this is not a closure \} / - q:c { \{ this is not a closure \} } - q { { this is not a closure } } - q { \{ this is not a closure \} } - -(Of course, matching backslashes is likely to make your syntax highlighter a -bit happier, along with any other naïve bracket counting algorithms...) - -=head2 Bare identifiers - -There are no barewords in Perl 6. An undeclared bare identifier will always -be taken to mean a subroutine name, and be parsed as a list operator. -(Class names (and other type names) are predeclared, or prefixed with the -C<::> type sigil when you're declaring a new one.) A consequence of this is -that there's no longer any "C". Since the syntax for -method calls is distinguished from sub calls, it is only unrecognized sub -calls that must be treated specially. - -You still must declare your subroutines, but a bareword with an unrecognized -name is provisionally compiled as a subroutine call, on the assumption that -such a declaration will occur by the end of the current compilation unit: - - foo; # provisional call if neither &foo nor ::foo is defined so far - foo(); # provisional call if &foo is not defined so far - foo($x); # provisional call if &foo is not defined so far - foo($x, $y); # provisional call if &foo is not defined so far - - $x.foo; # not a provisional call; it's a method call on $x - foo $x:; # not a provisional call; it's a method call on $x - foo $x: $y; # not a provisional call; it's a method call on $x - -If a postdeclaration is not seen, the compile fails at C time, that -is, at the end of compilation for this compilation unit. (You are still -free to predeclare subroutines explicitly, of course.) The postdeclaration -may be in any lexical or package scope that could have made the declaration -visible to the provisional call had the declaration occurred before rather -than after the provisional call. - -This fixup is done only for provisional calls. If there is I real -predeclaration visible, it always takes precedence. - -If the unrecognized subroutine name is followed by C<< postcircumfix:<( )> ->>, it is compiled as a provisional function call of the parenthesized form. -If it is not, it is compiled as a provisional function call of the list -operator form, which may or may not have an argument list. When in doubt, -the attempt is made to parse an argument list. As with any list operator, -an immediate postfix operator is illegal unless it is a form of parentheses, -whereas anything following whitespace will be interpreted as an argument -list if possible. - -Some examples of how listops, methods and labels interact syntactically: - - foo.bar # foo().bar - foo .bar # foo($_.bar) -- no postfix starts with whitespace - foo\ .bar # foo().bar - foo++ # foo()++ - foo 1,2,3 # foo(1,2,3) -- args always expected after listop - foo + 1 # foo(+1) -- term always expected after listop - foo; # foo(); -- no postfix, but no args either - foo: # label -- must be label at statement boundary. - -- ILLEGAL otherwise - foo: bar: # two labels in a row, okay - .foo: 1 # $_.foo: 1 -- must be "dot" method with : args - .foo(1) # $_.foo(1) -- must be "dot" method with () args - .foo # $_.foo() -- must be "dot" method with no args - .$foo: 1 # $_.$foo: 1 -- indirect "dot" method with : args - foo bar: 1 # bar.foo(1) -- bar must be predecl as class - -- sub bar allowed here only if 0-ary - -- otherwise you must say (bar): - foo bar 1 # foo(bar(1)) -- both subject to postdeclaration - -- never taken as indirect object - foo $bar: 1 # $bar.foo(1) -- indirect object even if declared sub - -- $bar considered one token - foo (bar()): 1 # bar().foo(1) -- even if foo declared sub - foo bar(): # ILLEGAL -- bar() is two tokens. - foo .bar: # foo(.bar:) -- colon chooses .bar to listopify - foo bar baz: 1 # foo(baz.bar(1)) -- colon controls "bar", not foo. - foo (bar baz): 1 # bar(baz()).foo(1) -- colon controls "foo" - $foo $bar # ILLEGAL -- two terms in a row - $foo $bar: # ILLEGAL -- use $bar."$foo"() for indirection - (foo bar) baz: 1 # ILLEGAL -- use $baz.$(foo bar) for indirection - -The indirect object colon only ever dominates a simple term, where "simple" -includes classes and variables and parenthesized expressions, but explicitly -not method calls, because the colon will bind to a trailing method call in -preference. An indirect object that parses as more than one token must be -placed in parentheses, followed by the colon. - -In short, only an identifier followed by a simple term followed by a postfix -colon is I parsed as an indirect object, but that form will I -be parsed as an indirect object regardless of whether the identifier is -otherwise declared. - -=head2 Dereferences - -There's also no "C" because symbolic dereferences are now -syntactically distinguished from hard dereferences. C<@($array)> must now -provide an actual array object, while C<@::($string)> is explicitly a -symbolic reference. (Yes, this may give fits to the P5-to-P6 translator, -but I think it's worth it to separate the concepts. Perhaps the symbolic -ref form will admit real objects in a pinch.) - -=head2 Hash subscripts and bare keys - -There is no hash subscript autoquoting in Perl 6. Use C<< %x >> for -constant hash subscripts, or the old standby C<< %x{'foo'} >>. (It also -works to say C<%x«foo»> as long as you realized it's subject to -interpolation.) - -But C<< => >> still autoquotes any bare identifier to its immediate left -(horizontal whitespace allowed but not comments). The identifier is not -subject to keyword or even macro interpretation. If you say - - $x = do { - call_something(); - if => 1; - } - -then C<$x> ends up containing the pair C<< ("if" => 1) >>. Always. (Unlike -in Perl 5, where version numbers didn't autoquote.) - -You can also use the C<:key($value)> form to quote the keys of option pairs. -To align values of option pairs, you may use the "unspace" postfix forms: - - :longkey\ ($value) - :shortkey\ - :fookey\ { $^a <=> $^b } - -These will be interpreted as - - :longkey($value) - :shortkey - :fookey{ $^a <=> $^b } - -=head2 Double-underscore forms - -The double-underscore forms are going away: - - Old New - --- --- - __LINE__ $?LINE - __FILE__ $?FILE - __PACKAGE__ $?PACKAGE - __SUB__ &?ROUTINE - __END__ =begin finish - __DATA__ =begin data - -The C<=begin finish> Pod stream (usually written as just C<=finish>) is -special in that it assumes there's no corresponding C<=end finish> before -end of file. Anything in a source file after a C<=finish> is always treated -as Pod. - -There is no longer any special C stream--any Pod block in the current -file can be accessed via a Pod object, such as C<< $=data >> or C<< -$=SYNOPSIS >> or C<< $=UserBlock >> etc. That is: a variable with the same -name of the desired block, and a C<=> twigil. - -These Pod objects can be used as Cs (indexed by their block -sequence). They can also be treated as Cs (indexed by C<:key> -options specified with the block). Either way, each C or -C element represents the entire contents of the corresponding -Pod block. You have to split those contents into lines yourself. Each chunk -has a C<.range> property that indicates its line number range within the -source file. - -[Speculative] It may also be possible to treat a Pod object as an -IO::Handle, to read the Pod information line-by-line (like the C -filehandle in Perl 5, but for I Pod block). - -The lexical routine itself is C<&?ROUTINE>; you can get its name with -C<&?ROUTINE.name>. The current block is C<&?BLOCK>. If the block has any -labels, those shows up in C<&?BLOCK.labels>. Within the lexical scope of a -statement with a label, the label is a pseudo-object representing the -I visible instance of that statement. (If inside multiple -dynamic instances of that statement, the label represents the innermost -one.) This is known as I semantics. - -When you say: - - next LINE; - -it is really a method on this pseudo-object, and - - LINE.next; - -would work just as well. You can exit any labeled block early by saying - - MyLabel.leave(@results); - -=head2 Heredocs - -Heredocs are no longer written with C<<< << >>>, but with an adverb on any -other quote construct: - - print qq:to/END/; - Give $amount to the man behind curtain number $curtain. - END - -Other adverbs are also allowed, as are multiple heredocs within the same -expression: - - print q:c:to/END/, q:to/END/; - Give $100 to the man behind curtain number {$curtain}. - END - Here is a $non-interpolated string - END - -=head3 Optional whitespace - -Heredocs allow optional whitespace both before and after terminating -delimiter. Leading whitespace equivalent to the indentation of the -delimiter will be removed from all preceding lines. If a line is deemed to -have less whitespace than the terminator, only whitespace is removed, and a -warning may be issued. (Hard tabs will be assumed to align to the next -multiple of C<< ($?TABSTOP // 8) >> spaces, but as long as tabs and spaces -are used consistently that doesn't matter.) A null terminating delimiter -terminates on the next line consisting only of whitespace, but such a -terminator will be assumed to have no indentation. (That is, it's assumed -to match at the beginning of any whitespace.) - -=head3 One-pass heredoc parsing - -There are two possible ways to parse heredocs. One is to look ahead for the -newline and grab the lines corresponding to the heredoc, and then parse the -rest of the original line. This is how Perl 5 does it. Unfortunately this -suffers from the problem pervasive in Perl 5 of multi-pass parsing, which is -masked somewhat because there's no way to hide a newline in Perl 5. In -Perl 6, however, we can use "unspace" to hide a newline, which means that an -algorithm looking ahead to find the newline must do a full parse (with -possible untoward side effects) in order to locate the newline. - -Instead, Perl 6 takes the one-pass approach, and just lazily queues up the -heredocs it finds in a line, and waits until it sees a "real" newline to -look for the text and attach it to the appropriate heredoc. The downside of -this approach is a slight restriction--you may not use the actual text of -the heredoc in code that must run before the line finishes parsing. Mostly -that just means you can't write: - - BEGIN { say q:to/END/ }; morestuff(); - Say me! - END - -You must instead put the entire heredoc into the C: - - BEGIN { - say q:to/END/; - Say me! - END - }; morestuff(); - -The parser is, however, smart enough to recognize that it's already at -the end of a line if you don't put C there. Hence this works: - - BEGIN { say q:to/END/ } - Say me! - END - -=head2 Version literals - -A version literal is written with a 'v' followed by the version number in -dotted form. This always constructs a C object, not a string. -Only integers and certain wildcards are allowed; for anything fancier you -must coerce a string to a C: - - v1.2.3 # okay - v1.2.* # okay, wildcard version - v1.2.3+ # okay, wildcard version - v1.2.3beta # illegal - Version('1.2.3beta') # okay - -Note though that most places that take a version number in Perl accept it as -a named argument, in which case saying C<< :ver<1.2.3beta> >> is fine. See -S11 for more on using versioned modules. - -Version objects have a predefined sort order that follows most people's -intuition about versioning: each sorting position sorts numerically between -numbers, alphabetically between alphas, and alphabetics in a position before -numerics. Missing final positions are assumed to be '.0'. Except for '0' -itself, numbers ignore leading zeros. For splitting into sort positions, if -any alphabetics (including underscore) are immediately adjacent to a number, -a dot is assumed between them. Likewise any non-alphanumeric character is -assumed to be equivalent to a dot. So these are all equivalent: - - 1.2.1alpha1.0 - 1.2.1alpha1 - 1.2.1.alpha1 - 1.2.1alpha.1 - 1.2.1.alpha.1 - 1.2-1+alpha/1 - -And these are also equivalent: - - 1.2.1_01 - 1.2.1_1 - 1.2.1._1 - 1.2.1_1 - 1.2.1._.1 - 001.0002.0000000001._.00000000001 - 1.2.1._.1.0.0.0.0.0 - -So these are in sorted version order: - - 1.2.0.999 - 1.2.1_01 - 1.2.1_2 - 1.2.1_003 - 1.2.1a1 - 1.2.1.alpha1 - 1.2.1b1 - 1.2.1.beta1 - 1.2.1.gamma - 1.2.1α1 - 1.2.1β1 - 1.2.1γ - 1.2.1 - -Note how the last pair assume that an implicit .0 sorts after anything -alphabetic, and that alphabetic is defined according to Unicode, not just -according to ASCII. The intent of all this is to make sure that prereleases -sort before releases. Note also that this is still a subset of the -versioning schemes seen in the real world. Modules with such strange -versions can still be used by Perl since by default Perl imports external -modules by exact version number. (See S11.) Only range operations will be -compromised by an unknown foreign collation order, such as a system that -sorts "delta" before "gamma". - -=head2 Allomorphic value semantics - -When C processing is attempted on any list of strings (typically on -the individual words within angle brackets), the function attempts to -determine if the intent of the programmer or user might have been to provide -a numeric value. - -For any item in the list that appears to be numeric, the literal is stored -as an object with both a string and a numeric nature, where the string -nature always returns the original string. This is implemented via multiple -inheritance, to truly represent the allomorphic nature of a literal value -that has not committed to which type the user intends. The numeric type -chosen depends on the appearance of the literal. Hence: - - < 1 1/2 6.02e23 1+2i > - -produces objects of classes defined as: - - class IntStr is Int is Str {...}; IntStr('1') - class RatStr is Rat is Str {...}; RatStr('1/2') - class NumStr is Num is Str {...}; NumStr('6.02e23') - class ComplexStr is Complex is Str {...}; ComplexStr('1+2i') - -One purpose of this is to facilitate compile-time analysis of multi-method -dispatch, when the user prefers angle notation as the most readable way to -represent a list of numbers, which it often is. Due to the MI semantics, -the new object is equally a string and a number, and can be bound as-is to -either a string or a numeric parameter. - -In case multiple dispatch determines that it could dispatch as either string -or number, a tie results, which may result in an ambiguous dispatch error. -You'll need to use prefix C<+> or C<~> on the argument to resolve the -ambiguity in that case. - -[Conjecture: we may someday find a way to make strings bind a little looser -than the numeric types, but for now we conservatively outlaw the dispatch as -ambiguous, and watch how this plays out in use.] - -The allomorphic behavior of angle brackets is not a special case; it's -actually an example of a more general process of figuring out type -information by parsing text that comes from any situation where the user is -forced to enter text when they really mean other kinds of values. A -function prompting the user for a single value might usefully pass the -result through C to intuit the proper type. - -The angle form with a single value serves as the literal form of numbers -such as C and C that would otherwise have to be constructed -via constant folding. It also gives us a reasonable way of visually -isolating any known literal format as a single syntactic unit: - - <-1+2i>.polar - (-1+2i).polar # same, but only by constant folding - -Any such literal, when written without spaces, produces a pure numeric value -without a stringy allomorphism. Put spaces to override that: - - <1/2> # a Rat - < 1/2 > # a RatStr - -Or use the C<«»> form of quotewords, which is always allomorphic: - - «1/2» # a RatStr - « 1/2 » # a RatStr - -=head3 Allomorphic Rats - -Any rational literal that would overflow a C in the denominator is -also stored as a string. (That is, angle brackets will be assumed in this -case, producing a C.) If a coercion to a wider type, such as -C, is requested, the literal reconverts from the entire original -string, rather than just the value that would fit into a C. (It may -then cache that converted value for next time, of course.) So if you declare -a constant with excess precision, it does not automatically become a -C, which would force all calculations into the pessimal C -type. - - constant pi is export = 3.14159_26535_89793_23846_26433_83279_50288; - say pi.norm.nude # 1570796326794896619 500000000000000000 (as Rat, reduced) - say pi.perl; # 3.14159_26535_89793_23846_26433_83279_50288 - say pi.Num # 3.14159265358979 (approximately) - say pi.Str; # 3.14159_26535_89793_23846_26433_83279_50288 - say pi.FatRat; # 3.14159265358979323846264338327950288 - -=head1 Context - -=over 4 - -=item * - -Perl still has the three main contexts: sink (aka void), item (aka scalar), -and list. - -=item * - -In addition to undifferentiated items, we also have these item contexts: - - Context Type OOtype Operator - ------- ---- ------ -------- - boolean bit Bit ? - integer int Integral int - numeric num Num + - string buf Str ~ - -There are also various container contexts that require particular kinds of -containers (such as slice and hash context; see S03 for details). - -=item * - -Unlike in Perl 5, objects are no longer always considered true. It depends -on the state of their C<.Bool> method, which may either be a synthetic -attribute or an explicitly represented bit in the object. Classes get to -decide which of their values are true and which are false. In general, -most classes choose a single distinguished value to be false but defined, -such as 0 for the various numeric types, or the empty string for string types. -Individual objects can override the class definition: - - return 0 but True; - -This overrides the C<.Bool> method of the C<0> without changing its official -type (by mixing the method into an anonymous derived type). - -=item * - -The definition of C<.Bool> for the most ancestral type (that is, the C -type) is equivalent to C<.defined>. Since type objects are considered -undefined, all type objects (including C itself) are false unless the -type overrides the definition of C<.Bool> to include undefined values. -Instantiated objects default to true unless the class overrides the -definition. Note that if you could instantiate a C it would be -considered defined, and thus true. (It is not clear that this is allowed, -however.) - -=item * - -In general any container types should return false if they are empty, and -true otherwise. This is true of all the standard container types except -Scalar, which always defers the definition of truth to its contents. -Non-container types define truthiness much as Perl 5 does, except -that the string C<"0"> is now considered true. Coerce to numeric with -C< >> if you want the other semantics. - -Just as with the standard types, user-defined types should feel free to -partition their defined values into true and false values if such a -partition makes sense in control flow using boolean contexts. - -=back - -=head1 Lists - -=head2 Lazy flattening - -List context in Perl 6 is by default lazy. This means a list can contain -infinite generators without blowing up. No flattening happens to a lazy -list until it is bound to the signature of a function or method at call time -(and maybe not even then). We say that such an argument list is "lazily -flattened", meaning that we promise to flatten the list on demand, but not -before. - -=head2 C, C, C, and C<.tree> - -There is a "C" operator which imposes a list context on its arguments -even if C itself occurs in item context. - -To force explicit flattening, use the C contextualizer. This -recursively flattens all lists into a 1-dimensional list. When bound to a -slurpy parameter, a capture flattens the rest of its positional arguments. - -To reform a list so that sub-lists turn into tree nodes, use the C<.tree> -method, which is essentially a level-sensitive C, with one closure -provided for remapping the lists at each level: - - $p.tree # recursively set all levels to item - $p.tree(*) # same thing - $p.tree(*.item) # force level 1 lists to item - $p.tree(1) # same thing - $p.tree(*.item,*.list) # force level 1 lists to item, level 2 to list - $p.tree(*.Array,*) # Turn all sublists into item recursively - -When bound to a slice parameter (indicated with C<**>), a capture reforms -the rest of its positional arguments with one level of "treeness", -equivalent to C<@args.tree(1)>, that is, a list of lists, or C. The -sublists are not automatically flattened; that is, if a sublist is a -C, it remains a list until subsequent processing decides how flat or -treelike the sublist should be. - -To force a non-flattening item context, use the "C" operator. - -=head2 Forcing capture context - -The C<|> prefix operator may be used to force "capture" context on its -argument and I defeat any scalar argument checking imposed by -subroutine signature declarations. Any resulting list arguments are then -evaluated lazily. - -=head2 The C operator - -To force non-lazy list processing, use the C list operator. List -assignment is also implicitly eager. (Actually, when we say "eager" we -usually mean "mostly eager" as defined in L). - - eager $filehandle.lines; # read all remaining lines - -By contrast, - - $filehandle.lines; - -makes no guarantee about how many lines ahead the iterator has read. -Iterators feeding a list are allowed to process in batches, even when stored -within an array. The array knows that it is extensible, and calls the -iterator as it needs more elements. (Counting the elements in the array -will also force eager completion.) - -This operator is agnostic towards flattening or slicing. It merely changes -the work-ahead policy for the value generator. - -=head2 The C operator - -A variant of C is the C list operator, which declares not only -that you want all the values generated now, but that you want them badly -enough that you don't care what order they're generated in, as long as the -results come back in the right order. That is, C requires sequential -evaluation of the list, while C requests (but does not require) -parallel evaluation. In any case, it declares that you don't care about the -evaluation order, only the result order. - -This operator is agnostic towards flattening or slicing. It merely changes -the work-ahead policy for the value generator. - -=head2 The C operator - -A further variant of C is the C list operator, which declares -that you want the results so badly that you don't even care what order they -come back in. Within its arguments, the C operator forces parallel -evaluation of any iterator, hyper, or junction, such that if any single -thread dies or hangs its computation, it does not block any other thread -from returning its results to the race list. When the demand for the race -list drops, hung threads may be killed. You can think of it as a C -with a 'C' on parallel computation. Note that -exceptions are trapped by default; if your car crashes, you simply do not -finish the race. If you want notifications of some sort back to the pit -crew, you'll have to arrange them yourself. - -This operator is agnostic towards flattening or slicing. It merely changes -the work-ahead policy for the value generator. It is a transitive -contextualizer insofar as iterators will have to pass on the policy to -subiterators. - -=head2 The C<< => >> operator - -The C<< => >> operator now constructs C objects rather than merely -functioning as a comma. Both sides are in item context. - -=head2 The C<< .. >> operator -X<..> - -The C<< .. >> operator now constructs a C object rather than merely -functioning as an operator. Both sides are in item context. Semantically, -the C acts like a list of its values to the extent possible, but does -so lazily, unlike Perl 5's eager range operator. - -=head2 Hash assignment - -There is no such thing as a hash list context. Assignment to a hash -produces an ordinary list context. You may assign alternating keys and -values just as in Perl 5. You may also assign lists of C objects, in -which case each pair provides a key and a value. You may, in fact, mix the -two forms, as long as the pairs come when a key is expected. If you wish to -supply a C as a key, you must compose an outer C in which the -key is the inner C: - - %hash = (($keykey => $keyval) => $value); - -=head2 The anonymous C function - -The anonymous C function takes a list of keys or pairs, and adds -values to any keys that are not already part of a pair. The value added is -one more than the previous key or pair's value. This works nicely with the -new C form: - - %hash = enum <<:Mon(1) Tue Wed Thu Fri Sat Sun>>; - %hash = enum « :Mon(1) Tue Wed Thu Fri Sat Sun »; - -are the same as: - - %hash = (); - %hash = 1..7; - -=head2 Hash binding - -In contrast to assignment, binding to a hash requires a C (or C) -object, or anything that does the C role. - -=head1 Files - -=over 4 - -=item * - -Filename globs are no longer done with angle brackets. Use the C -function. - -=item * - -Input from a filehandle is no longer done with angle brackets. Instead of - - while () {...} - -you now write - - for $handle.lines {...} - -=back - -=head1 Grammatical Categories - -Lexing in Perl 6 is controlled by a system of grammatical categories. At -each point in the parse, the lexer knows which subset of the grammatical -categories are possible at that point, and follows the longest-token rule -across all the active alternatives, including those representing any -grammatical categories that are ready to match. See L for a detailed -description of this process. - -To get a list of the current categories, grep 'token category:' from -STD.pm6. - -Category names are used as the short name of both various operators and the -rules that parse them, though the latter include an extra "sym": - - infix: # the infix cmp operator - infix:sym # the rule that parses cmp - -As you can see, the extension of the name uses colon pair notation. The -C<:sym> typically takes an argument giving the string name of the operator; -some of the "circumfix" categories require two arguments for the opening and -closing strings. Since there are so many match rules whose symbol is an -identifier, we allow a shorthand: - - infix:cmp # same as infix:sym (not infix:) - -Conjecturally, we might also have other kinds of rules, such as tree rewrite -rules: - - infix:match # rewrite a match node after reducing its arguments - infix:ast # rewrite an ast node after reducing its arguments - -Within a grammar, matching the proto subrule C<< >> will match all -visible rules in the infix category as parallel alternatives, as if they -were separated by 'C<|>'. - -Here are some of the names of parse rules in STD: - - category:sym prefix:<+> - circumfix:sym<[ ]> [ @x ] - dotty:sym<.=> $obj.=method - infix_circumfix_meta_operator:sym['»','«'] @a »+« @b - infix_postfix_meta_operator:sym<=> $x += 2; - infix_prefix_meta_operator:sym $x !~~ 2; - infix:sym<+> $x + $y - package_declarator:sym role Foo; - postcircumfix:sym<[ ]> $x[$y] or $x.[$y] - postfix_prefix_meta_operator:sym('»') @array »++ - postfix:sym<++> $x++ - prefix_circumfix_meta_operator:sym<[ ]> [*] - prefix_postfix_meta_operator:sym('«') -« @magnitudes - prefix:sym !$x (and $x.'!') - quote:sym qq/foo/ - routine_declarator:sym sub foo {...} - scope_declarator:sym has $.x; - sigil:sym<%> %hash - special_variable:sym<$!> $! - statement_control:sym if $condition { 1 } else { 2 } - statement_mod_cond:sym .say if $condition - statement_mod_loop:sym .say for 1..10 - statement_prefix:sym gather for @foo { .take } - term:sym $x = { !!! } - trait_mod:sym my $x does Freezable - twigil:sym $?LINE - type_declarator:sym subset Nybble of Int where ^16 - -Note that some of these produce correspondingly named operators, but not all -of them. When they do correspond (such as in the C example above), -this is by convention, not by enforcement. (However, matching C<< >> -within one of these rules instead of the literal operator makes it easier to -set up this correspondence in subsequent processing.) - -The STD::Regex grammar also adds these: - - assertion:sym // - backslash:sym /\w/ and /\W/ - metachar:sym<.> /.*/ - mod_internal:sym m:/ ... :P5 ... / - quantifier:sym<*> /.*/ - -=head1 Deprecations - -A language that doesn't evolve, is a dead language. Constructs that seem -like a good idea now, may turn out not to be such a good idea in the future. -Such constructs will thus need to be deprecated. To mark a construct as -being deprecated, one can add the "is DEPRECATED($alternative)" trait to a -class, an attribute, or a sub / method. During execution, this will cause -the caller sites to be recorded without any warnings. When execution -finishes, a report should be printed to STDERR stating which deprecated -features where called where. - -=head1 AUTHORS - - Larry Wall - -=for vim:set expandtab sw=4: diff --git a/S03-operators.pod b/S03-operators.pod deleted file mode 100644 index 8e34caca..00000000 --- a/S03-operators.pod +++ /dev/null @@ -1,5446 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 3: Operators - -=head1 VERSION - - Created: 8 Mar 2004 - - Last Modified: 16 Oct 2015 - Version: 288 - -=head1 Overview - -For a summary of the changes from Perl 5, see L. - -=head1 Operator precedence - -Perl 6 has about the same number of precedence levels as Perl 5, -but they're differently arranged in spots. Here we list the -levels from "tightest" to "loosest", along with a few examples of -each level. (Column 'A' is for "associativity", see following table.) - - A Level Examples - = ===== ======== - O Terms 42 3.14 "eek" qq["foo"] $x :!verbose @$array - L Method postfix .meth .+ .? .* .() .[] .{} .<> .«» .:: .= .^ .: i - N Autoincrement ++ -- - R Exponentiation ** - L Symbolic unary ! + - ~ ? | || +^ ~^ ?^ ^ - L Multiplicative * / % %% +& +< +> ~& ~< ~> ?& div mod gcd lcm - L Additive + - +| +^ ~| ~^ ?| ?^ - L Replication x xx - X Concatenation ~ - X Junctive and & (&) ∩ - X Junctive or | ^ (|) (^) ∪ (-) - L Named unary temp let - N Structural infix but does <=> leg cmp .. ..^ ^.. ^..^ - C Chaining infix != == < <= > >= eq ne lt le gt ge ~~ === eqv !eqv (<) (elem) - X Tight and && - X Tight or || ^^ // min max - R Conditional ?? !! ff fff - R Item assignment = => += -= **= xx= .= - L Loose unary so not - X Comma operator , : - X List infix Z minmax X X~ X* Xeqv ... - R List prefix print push say die map substr ... [+] [*] any Z= - X Loose and and andthen notandthen - X Loose or or xor orelse - X Sequencer <== ==> <<== ==>> - O Terminator ; {...} unless extra ) ] } - -Using two C symbols below generically to represent any pair of operators -that have the same precedence, the associativities specified above -for binary operators are interpreted as follows: - - Assoc Meaning of $a ! $b ! $c - ===== ========================= - L left ($a ! $b) ! $c - R right $a ! ($b ! $c) - N non ILLEGAL - C chain ($a ! $b) and ($b ! $c) - X list infix:($a; $b; $c) - O N/A (not really an operator) - -For unaries this is interpreted as: - - Assoc Meaning of !$a! - ===== ========================= - L left (!$a)! - R right !($a!) - N non ILLEGAL - -(In standard Perl there are no unaries that can take advantage of -associativity, since at each precedence level the standard operators -are either consistently prefix or postfix.) - -Note that list associativity (X) only works between identical operators. -If two different list-associative operators have the same precedence, -they are assumed to be non-associative with respect to each other, -and parentheses must be used to disambiguate. - -For example, the C cross operator and the C zip operator both -have a precedence of "list infix", but: - - @a X @b Z @c - -is illegal and must be written as either of: - - (@a X @b) Z @c - @a X (@b Z @c) - -If the only implementation of a list-associative operator -is binary, it will be treated as right associative. - -The standard precedence levels attempt to be consistent in their -associativity, but user-defined operators and precedence levels may mix -right and left associative operators at the same precedence level. -If two conflicting operators are used ambiguously in the same -expression, the operators will be considered non-associative with -respect to each other, and parentheses must be used to disambiguate. - -If you don't see your favorite operator above, the following -sections cover all the operators in precedence order. Basic operator -descriptions are here; special topics are covered afterwards. - -=head2 Term precedence - -This isn't really a precedence level, but it's in here because no operator -can have tighter precedence than a term. See L for longer descriptions of -various terms. Here are some examples. - -=over - -=item * - -C literal - - 42 - -=item * - -C literal - - 3.14 - -=item * - -Non-interpolating C literal - - '$100' - -=item * - -Interpolating C literal - - "Answer = $answer\n" - -=item * - -Generalized C literal - - q["$100"] - qq["$answer"] - -=item * - -Heredoc - - qq:to/END/ - Dear $recipient: - Thanks! - Sincerely, - $me - END - -=item * - -Array composer - - [1,2,3] - -Provides list context inside. (Technically, it really provides a -"semilist" context, which is a semicolon-separated list of statements, -each of which is interpreted in list context; if there is only one -statement, it makes a 1-dimensional array, but if there are more, it -makes a 2-dimensional array instead.) - -=item * - -Hash composer - - { } - { a => 42 } - -Inside must be either empty, or a single list starting with a pair or a hash, -otherwise you must use C or C<%()> instead. - -By default a hash forces all its keys to be strings. To compose a hash that -allows arbitrary objects (such as numbers) as keys, add a colon on front: - - :{ } - :{ -1 => 41, 0 => 42, 1 => 43 } - -Note that with objects as keys, you cannot access non-string keys as strings: - - :{ -1 => 41, 0 => 42, 1 => 43 }<0> # Any - :{ -1 => 41, 0 => 42, 1 => 43 }{0} # 42 - -=item * - -Closure - - { ... } - -When found where a statement is expected, executes immediately. Otherwise -always defers evaluation of the inside scope. - -=item * - -Capture composer - - \(@a,$b,%c) - -An abstraction representing an argument list that doesn't yet know its context. - -=item * - -Sigiled variables - - $x - @y - %z - $^a - $?FILE - &func - &div:(Int, Int --> Int) - -=item * - -Sigils as contextualizer functions - - $() - @() - %() - &() - -=item * - -Regexes in quote-like notation - - /abc/ - rx:i[abc] - s/foo/bar/ - -=item * - -Transliterations - - tr/a..z/A..Z/ - -Note ranges use C<..> rather than C<->. - -=item * - -Type names - - Num - ::Some::Package - -=item * - -Subexpressions circumfixed by parentheses - - (1+2) - -Parentheses are parsed on the inside as a semicolon-separated list -of statements, which (unlike the statements in a block) returns the results -of all the statements concatenated together as a C of C. -How that is subsequently treated depends on its eventual binding. - -=item * - -Function call with parens: - - a(1) - -In term position, any identifier followed immediately by a -parenthesized expression is always parsed as a term representing -a function call even if that identifier also has a prefix meaning, -so you never have to worry about precedence in that case. Hence: - - not($x) + 1 # means (not $x) + 1 - -=item * - -Pair composers - - :limit(5) - :!verbose - -=item * - -Signature literal - - :(Dog $self:) - -=item * - -Method call with implicit invocant - - .meth # call on $_ - .=meth # modify $_ - -Note that this may occur only where a term is expected. Where a -postfix is expected, it is a postfix. If only an infix is expected -(that is, after a term with intervening whitespace), C<.meth> is a -syntax error. (The C<.=meth> form is allowed there only because there -is a special C<.=> infix assignment operator that is equivalent in -semantics to the method call form but that allows whitespace between -the C<=> and the method name.) - -=item * - -Listop (leftward) - - 4,3, sort 2,1 # 4,3,1,2 - -As in Perl 5, a list operator looks like a term to the expression on -its left, so it binds tighter than comma on the left but looser than -comma on the right--see List prefix precedence below. - -=back - -=head2 Method postfix precedence - -All method postfixes (except for C) start with a dot, though the dot is -optional for subscripts. Since these are the tightest standard operator, you can -often think of a series of method calls as a single term that merely expresses a -complicated name. - -See L for more discussion of single dispatch method calls. - -=over - -=item * - -Standard single-dispatch method calls - - $obj.meth - -=item * - -Variants of standard single-dispatch method call - - $obj.+meth - $obj.?meth - $obj.*meth - -In addition to the ordinary C<.> method invocation, there are variants -C<.*>, C<.?>, and C<.+> to control how multiple related methods of -the same name are handled. - -=item * - -Class-qualified method call - - $obj.::Class::meth - $obj.Class::meth # same thing, assuming Class is predeclared - -As in Perl 5, tells the dispatcher which class to start searching from, -not the exact method to call. - -=item * - -Mutating method call - - $obj.=meth - -The C<.=> operator does inplace modification of the object on the left. - -=item * - -Meta-method call - - $obj.^meth - -The C<.^> operator calls a class metamethod; -C is short for C. - -=item * - -Method-like postcircumfixes - - $routine.() - $array.[] - $hash.{} - $hash.<> - $hash.«» - -The dotless forms of these have exactly the same precedences. - -=item * - -Dotted form of any other postfix operator - - $x.++ # postfix:<++>($x) - -=item * - -Dotted postfix form of any other prefix operator - - $x.:<++> # prefix:<++>($x) - -=item * - -Imaginary number postfix - - 42i - $foo\i - -The only operator on this level that does not start with a dot. Turns a number -into a purely-imaginary number (a C with a zero real part). Must be -backslashed if after a name, including C and C. - -=item * - -There is specifically no C<< infix:<.> >> operator, so - - $foo . $bar - -will always result in a compile-time error indicating the user should -use C<< infix:<~> >> instead. This is to catch an error likely to -be made by Perl 5 programmers learning Perl 6. - -=back - -=head2 Autoincrement precedence - -As in C, these operators increment or decrement the object in question -either before or after the value is taken from the object, depending on -whether it is put before or after. Also as in C, multiple references -to a single mutating object in the same expression may result in undefined -behavior unless some explicit sequencing operator is interposed. -See L. - -As with all postfix operators in Perl 6, no space is allowed between -a term and its postfix. See L for why, and for how to work around the -restriction with an "unspace". - -As mutating methods, all these operators dispatch to the type of -the operand and return a result of the same type, but they are legal -on value types only if the (immutable) value is stored in a mutable -container. However, a bare undefined value (in a suitable C -container) is allowed to mutate itself into an C in order to -support the common idiom: - - say $x unless %seen{$x}++; - -Increment of a C (in a suitable container) works similarly to -Perl 5, but is generalized slightly. -A scan is made for the final alphanumeric sequence in -the string that is not preceded by a '.' character. Unlike in Perl 5, this -alphanumeric sequence need not be anchored to the beginning of the -string, nor does it need to begin with an alphabetic character; -the final sequence in the string matching C<< + >> -is incremented regardless of what comes before it. - -The C<< >> character class is defined as that subset of -characters that Perl knows how to increment within a range, as defined -below. - -The additional matching behaviors provide two useful benefits: -for its typical use of incrementing a filename, you don't have to -worry about the path name or the extension: - - $file = "/tmp/pix000.jpg"; - $file++; # /tmp/pix001.jpg, not /tmp/pix000.jph - -Perhaps more to the point, if you happen to increment a string that ends -with a decimal number, it's likely to do the right thing: - - $num = "123.456"; - $num++; # 124.456, not 123.457 - -Character positions are incremented within their natural range for -any Unicode range that is deemed to represent the digits 0..9 or -that is deemed to be a complete cyclical alphabet for (one case -of) a (Unicode) script. Only scripts that represent their alphabet -in codepoints that form a cycle independent of other alphabets may -be so used. (This specification defers to the users of such a script -for determining the proper cycle of letters.) We arbitrarily define -the ASCII alphabet not to intersect with other scripts that make use -of characters in that range, but alphabets that intersperse ASCII letters are -not allowed. - -If the current character in a string position is the final character -in such a range, it wraps to the first character of the range and -sends a "carry" to the position left of it, and that position is -then incremented in its own range. If and only if the leftmost -position is exhausted in its range, an additional character of the -same range is inserted to hold the carry in the same fashion as Perl 5, -so incrementing '(zz99)' turns into '(aaa00)' and incrementing -'(99zz)' turns into '(100aa)'. - -The following Unicode ranges are some of the possible rangechar ranges. -For alphabets we might have ranges like: - - A..Z # ASCII uc - a..z # ASCII lc - Α..Ω # Greek uc - α..ω # Greek lc (presumably skipping C, final sigma) - א..ת # Hebrew - etc. # (XXX out of my depth here) - -For digits we have ranges like: - - 0..9 # ASCII - ٠..٩ # Arabic-Indic - ०..९ # Devanagari - ০..৯ # Bengali - ੦..੯ # Gurmukhi - ૦..૯ # Gujarati - ୦..୯ # Oriya - etc. - -Certain other non-script 0..9 ranges may also be incremented, such as - - ⁰..⁹ # superscripts (note, cycle includes latin-1 chars) - ₀..₉ # subscripts - ０..９ # fullwidth digits - -Ranges that are open-ended simply because Unicode has not defined -codepoints for them (yet?) are counted as rangechars, but are -specifically excluded from "carry" semantics, because Unicode may add -those codepoints in the future. (This has already happened with the -circled numbers, for instance!) For such ranges, Perl will pretend -that the characters are contiguous for calculating successors and -predecessors, and will fail if you run off of either end. - - Ⅰ..Ⅻ # clock roman numerals uc - ⅰ..ⅻ # clock roman numerals lc - ⓪..㊿ # circled digits/numbers 0..50 - ⒜..⒵ # parenthesized lc - ⚀..⚅ # die faces 1..6 - ❶..❿ # dingbat negative circled 1..10 - etc. - -Note: for actual ranges in Perl you'll need to quote the characters above: - - '⓪'..'㊿' # circled digits/numbers 0..50 - -If you want to future-proof the top end of your range against further -Unicode additions, you may specify it as "whatever": - - '⓪'..* # circled digits/numbers up to current known Unicode max - -Since these non-carrying ranges fail when they run out, it is -recommended that you avoid non-carrying rangechars where, for instance, -you need to keep generating unique filenames. It's much better to -generate longer strings via carrying rangechars in such cases. - -Note that all character increments can be handled by lookup in a -single table of successors since we've defined our ranges not to overlap. - -Anyway, back to string increment. Only rangechars may be incremented; -we can't just increment unrecognized characters, because -we have to locate the string's final sequence of rangechars before knowing -which portion of the string to increment. - -Perl 6 also supports C decrement with similar semantics, simply by -running the cycles the other direction. However, leftmost characters -are never removed, and the decrement fails when you reach a string like -"aaa" or "000". - -Increment and decrement on non-C types are defined in terms of the -C<.succ> and C<.pred> methods on the type of object in the C -container. More specifically, - - ++$var - --$var - -are equivalent to - - $var.=succ - $var.=pred - -If the type does not support these methods, the corresponding increment -or decrement operation will fail. (The optimizer is allowed to assume -that the ordinary increment and decrement operations on integers will -not be overridden.) - -Increment of a C (in a suitable container) turns it true. -Decrement turns it false regardless of how many times it was -previously incremented. This is useful if your C<%seen> hash is -actually a C, in which case decrement actually deletes the key -from the C. - -Increment/decrement of an undefined C, C, or C variable -sets the variable to 0 and then performs the increment/decrement. Hence a -postincrement returns 0 the first time: - - my $x; say $x++; # 0, not Any - -=over - -=item * - -Autoincrement C<< prefix:<++> >> or C<< postfix:<++> >> operator - - $x++ - ++$x; - -=item * - -Autodecrement C<< prefix:<--> >> or C<< postfix:<--> >> operator - - $x-- - --$x - -=back - -=head2 Exponentiation precedence - -=over - -=item * - -C<< infix:<**> >> exponentiation operator - - $x ** 2 - -Unless the right argument is a non-negative integer the result is likely to -be an approximation. If the right argument is of an integer type, -exponentiation is at least as accurate as repeated multiplication on -the left side's type. (From which it can be deduced that C -is always exact, since C supports arbitrary precision. -C is accurate to the precision of C.) If the -right argument is an integer represented in a non-integer type, the -accuracy is left to implementation provided by that type; there is -no requirement to recognize an integer to give it special treatment. -(Coercion of an integer C via C is likely to do the right thing, however.) - -=back - -=head2 Symbolic unary precedence - -=over - -=item * - -C<< prefix: >>, boolean context - - ?$x - -Evaluates the expression as a boolean and returns C if expression -is true or C otherwise. -See "so" below for a low-precedence alternative. - -=item * - -C<< prefix: >>, boolean negation - - !$x - -Returns the opposite of what C would. -See "not" below for a low-precedence alternative. - -=item * - -C<< prefix:<+> >>, numeric context - - +$x - -Unlike in Perl 5, where C<+> is a no-op, this operator coerces to -numeric context in Perl 6. (It coerces only the value, not the -original variable.) For values that do not already do the -C role, the narrowest appropriate type of C, C, C, or -C will be returned; however, string containing two integers -separated by a C will be returned as a C (or a C if the -denominator overflows an C). Exponential notation -and radix notations are recognized. - -Only leading and trailing whitespace are allowed as extra characters; -any other unrecognized character results in the return of a failure. - -=item * - -C<< prefix:<-> >>, numeric negation - - -$x - -Coerces to numeric and returns the arithmetic negation of the resulting number. - -=item * - -C<< prefix:<~> >>, string context - - ~$x - -Coerces the value to a string, if it does not already do the C -role. (It only coerces the value, not the original variable.) As with -numerics, it is guaranteed only to coerce to something C, -not necessarily C. - -=item * - -C<< prefix:<|> >>, flatten object into arglist - - | $capture - -Interpolates the contents of the C (or C-like) value -into the current argument list as if they had been specified literally. -If the first argument of the capture is marked as an invocant but is used -in a context not expecting one, it is treated as an ordinary positional -argument. - -=item * - -C<< prefix:<||> >>, flatten object into semicolon list - - || $list - -Interpolates the elements of the C (or any other ordered or iterable value) -into the current argument list as if they had been specified literally, -separated by semicolons, that is, at the multi-dimensional level. -It is an error to use this operator outside of a lol context; in -other words it must be bound into a C<**> (slice) parameter rather -than a C<*> (slurpy) parameter. - -=item * - -C<< prefix:<+^> >>, numeric bitwise negation - - +^$x - -Coerces to C and then does bitwise negation on the number, returning an C. -(In order not to have to represent an infinitude of 1's, it represents -that value as some negative in 2's complement form.) - -=item * - -C<< prefix:<~^> >>, string bitwise negation - - ~^$x - -Coerces NFG strings to non-variable-encoding string buffer type (such as C, -C, or C) and then does negation (complement) on each -bit of each integer element, returning a buffer of the same size as the input. - -The use of coercion probably indicates a design error, however. This operator -is distinguished from numeric bitwise negation in order to provide bit vectors -that extend on the right rather than the left (and always do unsigned extension). - -=item * - -C<< prefix: >>, boolean negation - - ?^$x - -Coerces to boolean and then flips the bit. (Same as C.) - -=item * - -C<< prefix:<^> >>, upto operator - - ^$limit - -Constructs a range of C<0 ..^ +$limit>. See L. - -=back - -=head2 Multiplicative precedence - -=over - -=item * - -C<< infix:<*> >> - - $x*$y - -Multiplication, resulting in the wider type of the two. - -=item * - -C<< infix: >> - - $numerator / $denominator - -Performs division of real or complex numbers, returning a real or complex -number of appropriate type. - -If one of operands is of rational type, and the second operator is of integer -or rational type, the operator returns the corresponding C value (except -when the result does not fit into a C, as detailed in L). - -Otherwise, if either operand is of C type, converts both -operands to C and does division returning C. - -Otherwise, if either operand is of C type, converts both operands to C -and does division returning C. If the denominator is zero, -returns an object representing either C<+Inf>, C, or C<-Inf> -as the numerator is positive, zero, or negative. (This is construed -as the best default in light of the operator's possible use within -hyperoperators and junctions. Note however that these are not -actually the native IEEE non-numbers; they are undefined values of the -"unthrown exception" type that happen to represent the corresponding -IEEE concepts, and if you subsequently try to use one of these values -in a non-parallel computation, it will likely throw an exception at -that point.) - -=item * - -C<< infix:
>>, integer division - - $numerator div $denominator - -Dispatches to the C<< infix:
>> multi most appropriate to the -operand types, returning a value of the same type. -Not coercive, so fails on differing types. - -Policy on what to do about division by zero is up to the type, -but for the sake of hyperoperators and junctions those types that -can represent overflow (or that can contain an unthrown exception) -should try to do so rather than simply throwing an exception. (And in -general, other operators that might fail should also consider their -use in hyperops and junctions, and whether they can profitably benefit -from a lazy exception model.) - -On the other hand, C
wants to be very efficient and jittable when used -as a low-level operation, so when you use C
on two native ints, it relies on -hardware to detect division by 0. Hence, it will always throw an exception -rather than return a C. - -In general, C
should give the same result as - - $x div $y == floor($x/$y) - -but the return value should be the same type as $x. - -This identity stops holding when C<$x/$y> degrades to a C and runs -into precision limits. A C
operation on two C objects must always -be done precisely. - -=item * - -C<< infix:<%> >>, modulo - - $x % $y - -If necessary, coerces non-numeric arguments to an appropriate C type, -then calculates the remainder, which is defined as: - - $x % $y == $x - floor($x / $y) * $y - -If both operands are Cs, the operator returns an C. - -If both operands are of integer or rational type, the operator returns the -corresponding C value (except when the result does not fit into a -C, as detailed in L). - -=item * - -C<< infix:<%%> >>, is divisible by - - $x %% $y - -Performs a C<%> and then tests the result for 0, returning C if -the C<$x> is evenly divisible by C<$y>, and C otherwise. - -You may use C to mean "not divisible by", though C<%> itself generally -has the same effect. - -=item * - -C<< infix: >>, integer modulo - - $x mod $y - -Dispatches to the C<< infix: >> multi most appropriate to -the operand types, returning a value of the same type. -Not coercive, so fails on differing types. - -This should preserve the identity - - $x mod $y == $x - ($x div $y) * $y - -=item * - -C<< infix:<+&> >>, numeric bitwise and - - $x +& $y - -Converts both arguments to C and does a boolean AND between -corresponding bits of each integer, returning an C result. - -=item * - -C<< infix:«+<» >>, numeric shift left - - $integer +< $bits - -Shifts by a negative number of bits cause a corresponding right shift. -As such the C<:signed> or C<:!signed> adverbs may be applied (see below.) - -=item * - -C<< infix:«+>» >>, numeric shift right - - $integer +> $bits - -By default, signed types do sign extension, while unsigned types do not, but -this may be enabled or disabled with a C<:signed> or C<:!signed> adverb. - -Shifts by a negative number of bits cause a corresponding left shift. - -=item * - -C<< infix:<~&> >>, buffer bitwise and - - $x ~& $y - -Coerces NFG strings to non-variable-encoding string buffer type (such as C, -C, or C) and then does numeric bitwise AND on corresponding integers -of the two buffers, logically padding the shorter buffer with 0 values. -returning a buffer sufficiently large to contain all non-zero integer results -(which for AND is at most the size of the shorter of the two buffers). - -The use of coercion probably indicates a design error, however. This operator -is distinguished from numeric bitwise AND in order to provide bit vectors -that extend on the right rather than the left (and always do unsigned extension). - -=item * - -C<< infix:«~<» >>, buffer bitwise shift left - - $buf ~< $bits - -=item * - -C<< infix:«~>» >>, buffer bitwise shift right - - $buf ~> $bits - -Sign extension is not done by default but may be enabled with a C<:signed> -adverb. - -=item * - -C<< infix: >>, boolean and - - $x ?& $y - -Converts both arguments to type C and then ANDs those, returning the -resulting C. - -=item * - -C<< infix: >>, greatest common divisor - - $x gcd $y - -Converts both arguments to an integral type and then finds the largest integer -that both arguments are evenly divisible by, and returns that integer. - -=item * - -C<< infix: >>, least common multiple - - $x lcm $y - -Converts both arguments to an integral type and then finds the smallest integer -that is evenly divisible by both arguments, and returns that integer. - -=back - -Any bit shift operator may be turned into a rotate operator with the -C<:rotate> adverb. If C<:rotate> is specified, the concept of -sign extension is meaningless, and you may not specify a C<:signed> adverb. - -=head2 Additive precedence - -=over - -=item * - -C<< infix:<+> >>, numeric addition - - $x + $y - -Microeditorial: As with most of these operators, any coercion or type -mismatch is actually handled by multiple dispatch. The intent is that -all such variants preserve the notion of numeric addition to produce a -numeric result, presumably stored in a numeric type suitably "large" to -hold the result. Do not overload the C<+> operator for other purposes, -such as concatenation. (And please do not overload the bitshift -operators to do I/O.) In general we feel it is much better for you -to make up a different operator than overload an existing operator for -"off topic" uses. All of Unicode is available for this purpose. - -=item * - -C<< infix:<-> >>, numeric subtraction - - $x - $y - -=item * - -C<< infix:<+|> >>, numeric bitwise inclusive or - - $x +| $y - -Converts both arguments to C and does a boolean OR between -corresponding bits of each integer, returning an C result. - -=item * - -C<< infix:<+^> >> numeric bitwise exclusive or - - $x +^ $y - -Converts both arguments to C and does a boolean XOR between -corresponding bits of each integer, returning an C result. - -=item * - -C<< infix:<~|> >>, buffer bitwise inclusive or - - $x ~| $y - -Coerces NFG strings to non-variable-encoding string buffer type (such as C, -C, or C) and then does numeric bitwise OR on corresponding integers -of the two buffers, logically padding the shorter buffer with 0 values, and -returning a buffer sufficiently large to contain all non-zero integer results -(which for OR is at most the size of the longer of the two buffers). - -The use of coercion probably indicates a design error, however. This operator -is distinguished from numeric bitwise OR in order to provide bit vectors -that extend on the right rather than the left (and always do unsigned extension). - -=item * - -C<< infix:<~^> >> buffer bitwise exclusive or - - $x ~^ $y - -Coerces NFG strings to non-variable-encoding string buffer type (such as C, -C, or C) and then does numeric bitwise XOR on corresponding integers -of the two buffers, logically padding the shorter buffer with 0 values. -returning a buffer sufficiently large to contain all non-zero integer results -(which for XOR is at most the size of the longer of the two buffers). - -The use of coercion probably indicates a design error, however. This operator -is distinguished from numeric bitwise XOR in order to provide bit vectors -that extend on the right rather than the left (and always do unsigned extension). - -=item * - -C<< infix: >>, boolean inclusive or - - $x ?| $y - -Converts both arguments to type C and then ORs those, returning the -resulting C. - -=item * - -C<< infix: >> boolean exclusive or - - $x ?^ $y - -Converts both arguments to type C and then XORs those, returning the -resulting C. - -=back - -=head2 Replication - -=over - -=item * - -C<< infix: >>, string/buffer replication - - $string x $count - -Evaluates the left argument in string context, replicates the resulting -string value the number of times specified by the right argument, and -returns the result as a single concatenated string regardless of context. - -If the count is less than 1, returns the null string. -The count may not be C<*> because Perl 6 does not support -infinite strings. (At least, not yet...) Note, however, that an -infinite string may someday be emulated with C, -in which case C<$string x *> may be a shorthand for that. - -=item * - -C<< infix: >>, expression repetition operator - - @list xx $count - -Evaluates the left argument the number of times specified by the right -argument. Each evaluation is in list context, and returns a C. -The result of all these evaluations is returned as a list of arrays -(which will behave differently depending on whether it's bound into -a flat context or a lol context). - -If the count is less than 1, returns the empty list, C<()>. -If the count is C<*>, returns an infinite list (lazily, since lists -are lazy by default). - -Since the expression on the left is treated as a thunk that is re-evaluated -each time, expressions that rely on this behavior are possible: - - rand xx *; # infinite supply of random numbers - [ 0 xx $cols ] xx $rows # distinct arrays, not the same row replicated - -Of course, the optimizer can notice when the left side is a constant and avoid -re-evaluation. When this is not possible, you can subvert the re-evaluation -by use of a temporary. - -=back - -=head2 Concatenation - -=over - -=item * - -C<< infix:<~> >>, string/buffer concatenation - - $x ~ $y - -=back - -=head2 Junctive and (all) precedence - -=over - -=item * - -C<< infix:<&> >>, C operator - - $a & $b & $c ... - -By default junctions are allowed to reorder the comparisons in any -order that makes sense to the optimizer. To suppress this, use -the C metaoperator for force sequential evaluation, which will -construct a list of ANDed patterns with the same semantics as C<< -infix:<&> >>, but with left-to-right evaluation guaranteed, for use -in guarded patterns: - - $target ~~ MyType S& *.mytest1 S& *.mytest2 - -This is useful when later tests might throw exceptions if earlier -tests don't pass. This cannot be guaranteed by: - - $target ~~ MyType & *.mytest1 & *.mytest2 - -=back - -=head2 Junctive or (any) precedence - -=over - -=item * - -C<< infix:<|> >>, C operator - - $a | $b | $c ... - -=item * - -By default junctions are allowed to reorder the comparisons in -any order that makes sense to the optimizer. To suppress this, -use the C metaoperator for force sequential evaluation, which -will construct a list of ORed patterns with the same semantics as -C<< infix:<|> >>, but with left-to-right evaluation guaranteed, for -use in guarded patterns where the left argument is much more easily -falsifiable than the right: - - $target ~~ *.mycheaptest S| *.myexpensivetest - -This is also useful when you want to perform tests in order -of safety: - - $target ~~ MyType S| *.mysafetest S| *.mydangeroustest - -=item * - -C<< infix:<^> >>, C operator - - $a ^ $b ^ $c ... - -The C variant guarantees left-to-right evaluation, and in boolean -context short-circuits to false if it sees a second match. - -=back - -=head2 Named unary precedence - -Operators of one argument - - let - temp - -Note that, unlike in Perl 5, you must use the C<.meth> forms to default -to C<$_> in Perl 6. - -There is no unary C prefix in Perl 6, though there is a C<.rand> -method call and an argumentless C term. There is no unary C -prefix either; you must use a typecast to a type such as C or C. -(Typecasts require parentheses and may not be used as prefix operators.) -In other words: - - my $i = int $x; # ILLEGAL - -is a syntax error (two terms in a row), because C is a type name now. - -=head2 Nonchaining binary precedence - -=over - -=item * - -C<< infix: >> - - $value but Mixin - -=item * - -C<< infix: >> - - $object does Mixin - -=item * - -Sort comparisons - - $num1 <=> $num2 - $str1 leg $str2 - $obj1 cmp $obj2 - -These operators compare their operands using numeric, string, or C -semantics respectively, and if the left operand is smaller, the same, -or larger than the right operator, return respectively C, -C, or C (which numerify to -1, 0, or +1, -the customary values in most C-derived languages). See L. - -=item * - -Range object constructor - - $min .. $max - $min ^.. $max - $min ..^ $max - $min ^..^ $max - -Constructs C objects, optionally excluding one or both endpoints. -See L. - -=back - -=head2 Chaining binary precedence - -All operators on this precedence level may be I; see -L. They all return a boolean value. - -=over - -=item * - -C<< infix:<==> >> etc. - - == != < <= > >= - -As in Perl 5, converts to C before comparison. C is short for C. - -=item * - -C<< infix: >> etc. - - eq ne lt le gt ge - -As in Perl 5, converts to C before comparison. C is short for C. - -=item * - -Generic ordering - - $a before $b - $a after $b - -=item * - -Smart match - - $obj ~~ $pattern - -Perl 5's C<=~> becomes the "smart match" operator C<~~>, with an -extended set of semantics. See L for details. - -To catch "brainos", the Perl 6 parser defines an C<< infix:<=~> >> -operator, which always fails at compile time with a message directing -the user to use C<~~> or C<~=> (string append) instead if they meant -it as a single operator, or to put a space between if they really -wanted to assign a stringified value as two separate operators. - -A negated smart match is spelled C. - -=item * - -Container identity - - VAR($a) =:= VAR($b) - -See L. - -=item * - -Value identity - - $x === $y - -For objects that are not value types, their identities are their values. -(Identity is returned by the C<.WHICH> metamethod.) The actual contents of -the objects are ignored. These semantics are those used by hashes that -allow objects for keys. See also L. - -Note that C<===> is defined with an C<(Any,Any)> signature, and therefore -autothreads over junctions; hence it I be used to determine if two -objects are the same, if either or both of them are junctions. However, -since C<.WHICH> is a macro that always returns a value and never autothreads, -you can easily work around this limitation by saying: - - $junk1.WHICH eqv $junk2.WHICH - -[Conjecture: primitive identity is checked with C<< $junk1 \=== $junk2 >>.] - -=item * - -Canonical equivalence - - $obj1 eqv $obj2 - -Compares two objects for canonical equivalence. For value types compares -the values. For object types, compares current contents according to some -scheme of canonicalization. These semantics are those used by hashes -that allow only values for keys (such as Perl 5 string-key hashes). -See also L. - -Note that C autothreads over junctions, as do all other comparison -operators. (Do not be confused by the fact that these return boolean values; -in general, only boolean I forces junction collapse.) - -When comparing list-like objects, C must preserve lazy semantics of either -or both of its arguments. (That is, it may optimize by calling C<.elems> only when -it can prove that both its arguments are already fully evaluated.) - -[Conjecture: primitive equivalence is checked with C<< $junk1 \eqv $junk2 >>.] - -=item * - -Negated relational operators - - $num !== 42 - $str !eq "abc" - "foo" !~~ /^ $/ - VAR($a) !=:= VAR($b) - $a !=== $b - $a !eqv $b - -See L. - -=back - -=head2 Tight and precedence - -=over - -=item * - -C<< infix:<&&> >>, short-circuit and - - $a && $b && $c ... - -Returns the first argument that evaluates to false, otherwise -returns the result of the last argument. In list context forces -a false return to mean C<()>. See C below for low-precedence -version. - -=back - -=head2 Tight or precedence - -=over - -=item * - -C<< infix:<||> >>, short-circuit inclusive-or - - $a || $b || $c ... - -Returns the first argument that evaluates to a true value, otherwise -returns the result of the last argument. It is specifically allowed -to use a list or array both as a boolean and as a list value produced -if the boolean is true: - - @a = @b || @c; # broken in Perl 5; works in Perl 6 - -In list context this operator forces a false return to mean C<()>. -See C below for low-precedence version. - -=item * - -C<< infix:<^^> >>, short-circuit exclusive-or - - $a ^^ $b ^^ $c ... - -Returns the true argument if there is one (and only one). Returns the -last argument if all arguments are false. Returns C -otherwise (when more than one argument is true). In list context -forces a false return to mean C<()>. See C below for -low-precedence version. - -This operator short-circuits in the sense that it does not evaluate -any arguments after a 2nd true result. Closely related is the reduce -operator: - - [^^] a(), b(), c() ... - -but note that reduce operators are not macros but ordinary list -operators, so c() is always called before the reduce is done. - - -=item * - -C<< infix: >>, short-circuit default operator - - $a // $b // $c ... - -Returns the first argument that evaluates to a defined value, otherwise -returns the result of the last argument. In list context forces a -false return to mean C<()>. See C below for a similar but -not identical low-precedence version. - -=item * - -Minimum and maximum - - $a min $b min $c ... - $a max $b max $c ... - -These return the minimum or maximum value. See also the -C listop. - -Not all types can support the concept of infinity. Therefore any -value of any type may be compared with C<+Inf> or C<-Inf> values, -in which case the infinite value stands for "larger/smaller than any -possible value of the type." That is, - - "foo" min +Inf # "foo" - "foo" min -Inf # -Inf - "foo" max +Inf # +Inf - "foo" max -Inf # "foo" - -All orderable object types must support C<+Inf> and C<-Inf> values -as special forms of the undefined value. It's an error, however, -to attempt to store an infinite value into a native type that cannot -support it: - - my int $max; - $max max= -Inf; # ERROR - -=back - -=head2 Conditional operator precedence - -=over - -=item * - -Conditional operator - - say "My answer is: ", $maybe ?? "yes" !! "no"; - -Also known as the "ternary" or "trinary" operator, but we prefer -"conditional" just to stop people from fighting over the terms. The -operator syntactically separates the expression into three subexpressions. -It first evaluates the left part in boolean context, then based on that -selects one of the other two parts to evaluate. (It never evaluates -both of them.) If the conditional is true it evaluates and returns -the middle part; if false, the right part. The above is therefore -equivalent to: - - say "My answer is: ", do { - if $maybe { - "yes"; - } - else { - "no"; - } - }; - -It is a syntax error to use an operator in the middle part that binds -looser in precedence, such as C<=>. - - my $x; - hmm() ?? $x = 1 !! $x = 2; # ERROR - hmm() ?? ($x = 1) !! ($x = 2); # works - -Note that both sides have to be parenthesized. A partial fix is -even wronger: - - hmm() ?? ($x = 1) !! $x = 2; # parses, but WRONG - -That actually parses as: - - ( - hmm() ?? ($x = 1) !! $x - ) = 2; - -and always assigns C<2> to C<$x> (because C<($x = 1)> is a valid lvalue). - -And in any case, repeating the C<$x> forces you to declare it earlier. -The best don't-repeat-yourself solution is simply: - - my $x = hmm() ?? 1 !! 2; # much better - -=item * - -C<< infix: >> - -To catch likely errors by people familiar with C-derived languages -(including Perl 5), a bare question mark in infix position will -produce an error suggesting that the user use C instead. - -=item * - -Flipflop ranges - - start() ff end() - start() ^ff end() - start() ff^ end() - start() ^ff^ end() - -=item * - -Flipflop ranges (sed style) - - start() fff end() - start() ^fff end() - start() fff^ end() - start() ^fff^ end() - -=back - -=head2 Adverbs - -Operator adverbs are special-cased in the grammar, but give -the appearance of being parsed as trailing unary operators at a -pseudo-precedence level slightly tighter than item assignment. -(They're not officially "postfix" operators -because those require the absence of whitespace, and these allow whitespace. -These adverbs insert themselves in the spot where the parser is -expecting an infix operator, but the parser continues to look for -an infix after parsing the adverb and applying it to the previous -term.) Thus, - - $a < 1 and $b == 2 :carefully - -does the C<==> carefully, while - - $a < 1 && $b == 2 :carefully - -does the C<&&> carefully because C<&&> is of -tighter precedence than "comma". Use - - $a < 1 && ($b == 2 :carefully) - -to apply the adverb to the C<==> operator instead. We say that -C<==> is the "topmost" operator in the sense that it is at the -top of the parse tree that the adverb could possibly apply to. -(It could not apply outside the parens.) If you are unsure -what the topmost operator is, just ask yourself which operator -would be applied last. For instance, in - - +%hash{$key} :foo - -the subscript happens first and the C<+> operator happens last, -so C<:foo> would apply to that. Use - - +(%hash{$key} :foo) - -to apply C<:foo> to the subscripting operator instead. - -Adverbs will generally attach the way you want when you say things like - - 1 op $x+2 :mod($x) - -The proposed internal testing syntax makes use of these precedence rules: - - $x eqv $y+2 :ok<$x is equivalent to $y+2>; - -Here the adverb is considered to be modifying the C operator. - -=head2 Item assignment precedence - -=over - -=item * - -C<< infix:<=> >> - - $x = 1, $y = 2; - -With simple lvalues, C<=> has this precedence, which is tighter than comma. -(List assignments have listop precedence below.) - -=item * - -C<< infix:«=>» >>, Pair constructor - - foo => 1, bar => "baz" - -Binary C<< => >> is no longer just a "fancy comma". It now constructs -a C object that can, among other things, be used to pass named -arguments to functions. It provides item context to both sides. -It does not actually do an assignment except in a notional sense; -however its precedence is now equivalent to assignment, and it is -also right associative. Note that, unlike in Perl 5, C<< => >> -binds more tightly than comma. - -=item * - -Assignment operators - - += -= **= xx= .= etc. - -See L. - -=back - -=head2 Loose unary precedence - -=over - -=item * - -C<< prefix: >> - - not any(@args) eq '-v' | '-V' - -Returns a C value representing the logical negation of an expression. - -=item * - -C<< prefix: >> - - so any(@args) eq '-v' | '-V' - -Returns a C value representing the logical non-negation of an expression. -Mostly useful as documentation in parallel to a C when C isn't -appropriate: - - if not $x { print "LOL"; } - mumble(); - if so $x { print "SRSLY!" } - -=back - -=head2 Comma operator precedence - -=over - -=item * - -C<< infix:<,> >>, the argument separator - - 1, 2, 3, @many - -Unlike in Perl 5, comma operator never returns the last value. (In item -context it returns a list instead.) - -=item * - -C<< infix:<:> >>, the invocant marker - - say $*OUT: "howdy, world" - say($*OUT: "howdy, world") - push @array: 1,2,3 - push(@array: 1,2,3) - \($object: 1,2,3, :foo, :!bar) - -The colon operator parses just like a comma, but marks the argument to its left as an -invocant, which has the effect of turning what would otherwise be a function -call into a method call. It may only be used on the first argument of -an argument list or capture, and will fail to parse if used in any other position. -When used within a capture, it is not yet known what signature the capture will -be bound to; if bound to a non-method's signature, the invocant merely turns -into the first positional argument, as if the colon had been a comma. - -To avoid confusion with other colon forms, the colon infix operator -must be followed by whitespace or a terminator. It may optionally -have whitespace in front of it. - -Note: distinguish this infix operator from the colon in - - @array.push: 1,2,3 - @array.push(1,2,3): 4,5,6 - push(@array, 1,2,3): 4,5,6 - -which is a special form that turns an ordinary function or method -call into a list operator. The special form is recognized only after -a dotty method call, or after the right parenthesis of a method or -function call. The special form does not allow intervening whitespace, -but requires whitespace before the next argument. In all other -cases a colon will be parsed as the start of an adverb if possible, -or otherwise the invocant marker (the infix described above). - -Another way to think of it is that the special colon is allowed to -add listop arguments to a parenthesized argument list only after -the right parenthesis of that argument list, with the proviso that -you're allowed to shorten C<.foo(): 1,2,3> down to C<.foo: 1,2,3>. -(But only for method calls, since ordinary functions don't need the -colon in the first place to turn into a listop, just whitespace. -If you try to extend a function name with a colon, it's likely -to be taken as a label.) - - foo $obj.bar: 1,2,3 # special, means foo($obj.bar(1,2,3)) - foo $obj.bar(): 1,2,3 # special, means foo($obj.bar(1,2,3)) - foo $obj.bar(1): 2,3 # special, means foo($obj.bar(1,2,3)) - foo $obj.bar(1,2): 3 # special, means foo($obj.bar(1,2,3)) - foo($obj.bar): 1,2,3 # special, means foo($obj.bar, 1,2,3) - foo($obj.bar, 1): 2,3 # special, means foo($obj.bar, 1,2,3) - foo($obj.bar, 1,2): 3 # special, means foo($obj.bar, 1,2,3) - foo $obj.bar : 1,2,3 # infix:<:>, means $obj.bar.foo(1,2,3) - foo ($obj.bar): 1,2,3 # infix:<:>, means $obj.bar.foo(1,2,3) - foo $obj.bar:1,2,3 # syntax error - foo $obj.bar :1,2,3 # syntax error - foo $obj.bar :baz # adverb, means foo($obj.bar(:baz)) - foo ($obj.bar) :baz # adverb, means foo($obj.bar, :baz) - foo $obj.bar:baz # extended identifier, foo( $obj.'bar:baz' ) - foo $obj.infix:<+> # extended identifier, foo( $obj.'infix:<+>' ) - foo: 1,2,3 # label at statement start, else infix - -The moral of the story is: if you don't know how the colon is -going to bind, use whitespace or parentheses to make it clear. - -=back - -=head2 List infix precedence - -List infixes all have list associativity, which means that identical -infix operators work together in parallel rather than one after -the other. Non-identical operators are considered non-associative -and must be parenthesized for clarity. - -=over - -=item * - -C<< infix: >>, the zip operator - - 1,2 Z 3,4 # (1,3),(2,4) - -The C operator is actually a degenerate case of the C zipwith -metaoperator (see L below). - -=item * - -C<< infix: >>, the minmax operator - - @a minmax @b - -Returns a C from the minimum element of C<@a> and C<@b> to the maximum -element. C elements in the input are treated as if their -minimum and maximum values were passed individually, except that if the -corresponding C flag is set in Range, the excludes flag is also set -in the returned C. - -=item * - -C<< infix: >>, the cross operator - - 1,2 X 3,4 # (1,3), (1,4), (2,3), (2,4) - -In contrast to the zip operator, the C operator returns all possible -lists formed by taking one element from each of its list arguments. The -returned lists are ordered such that the rightmost elements vary most rapidly. -If there are just two lists, for instance, it forms all pairs -where one element is from the first list and the other one from -the second, with the second element varying most rapidly. Hence you may say: - - X <1 2> - -and you end up with - - ('a', '1'), ('a', '2'), ('b', '1'), ('b', '2') - -This becomes a flat list in flat context and a C in lol context: - - say flat( X <1 2>).perl - 'a', '1', 'a', '2', 'b', '1', 'b', '2' - say lol( X <1 2>).perl - LoL.new( ('a', '1'), ('a', '2'), ('b', '1'), ('b', '2') ) - -The operator is list associative, so - - 1,2 X 3,4 X 5,6 - -produces - - (1,3,5),(1,3,6),(1,4,5),(1,4,6),(2,3,5),(2,3,6),(2,4,5),(2,4,6) - -On the other hand, if any of the lists is empty, you will end up with -a null list. - -While either side's list may be infinite, use of an infinite list on -the right may produce unexpected results. For instance - - X 0..* - -would produce - - ('a',0), ('a',1), ('a',2), ('a',3), ('a',4), ('a',5), ... - -and you'd never get to 'b'. If your left list consists of only -a single element, though, this may be useful, especially if C is used as -a metaoperator. See below. - -=item * - -Cross metaoperators - - @files X~ '.' X~ @extensions - 1..10 X* 1..10 - @x Xeqv @y - etc. - -A common idiom is to have a list with a single element on one side or the other: - - @vector X* 2; # multiply each element by 2 - $prefix X~ @infinitelist; # prefix each element of an infinite list - -In this last case it's okay to have an infinite list on the right. - -See L. - - -=item * - -C<< infix:<...> >>, the sequence operator. - -As a list infix operator, C<...> takes a list on both its left and -right and evaluates them as lazily as possible to produce the desired -sequence of values. The lists are evaluated as flat lists. As with -all list infix operators, this operator is looser in precedence than -comma, so you do not need to parenthesize comma lists on either side -of it. - -The operator starts by getting the first value of the righthand list. -This is the only value of the right list that the C<...> operator is -actually interested in; any additional list elements are treasured -up lazily to be returned after the C<...> is done. - -The righthand first value is considered to be the endpoint or limit of the -sequence that is to be generated from the lefthand side by the C<...> -operator itself. - -Once we know the limit of the sequence, the left list is evaluated item -by item, and ordinary numeric or string values are passed through -unchanged (to the extent allowed by the limit on the right). -If any value in the sequence smartmatches the limit value, -the sequence terminates, including that final limit value. To omit -the final value, use the C<...^> form instead. - -Internally, these two forms are checking to see if an anonymous loop -is going to terminate, where the loop is what is returning the values -of the sequence. Assuming the next candidate value is in C<$x> and the -first element of the right side is in C<$limit>, the two operators -are implemented respectively as: - - ... last($x) if $x ~~ $limit; - ...^ last if $x ~~ $limit; - -Since this uses smartmatching via the C<~~> operator (see L below), the usual smartmatching rules apply. If the -limit is C<*>, the sequence has no limit. If the limit is a closure, -it will be evaluated for boolean truth on the current candidate, -and the sequence will continue as long as the closure returns false. -If the limit is a closure with more than 1 - or infinite - arguments -the appropriate number of elements from the end of the sequence -- or the whole sequence so far - are passed. -It's quite possible for a sequence to return fewer values than are -listed if the very first value matches the end test: - - my $lim = 0; - 1,2,3 ...^ * > $lim # returns (), since 1 > 0 - -This operator would be fairly useless if it could only return the -literal values on the left. The power comes from generating -new values from the old ones. You may, for instance, use an existing -generator that happens to produce an infinite list: - - 1..* ... * >= $lim - @fib ... * >= $lim - -More typically, if the next item in the left-hand -list is a closure, it is not returned; rather it is called -on the tail of the existing list to produce a new value. The -arity of the closure determines how many preceding values to -use as input in generating the next value in the sequence. For -instance, counting by twos only requires a single argument: - - 2, { $^a + 2 } ... * # 2,4,6,8,10,12,14,16... - -Generating the Fibonacci sequence takes two arguments at a time: - - 1, 1, { $^a + $^b } ... * # 1,1,2,3,5,8,13,21... - -Any means of specifying a function will do, as long as you arrange -it as a list value rather than calling it: - - 1, 1, &infix:<+> ... * # 1,1,2,3,5,8... - 1, 1, &[+] ... * # same thing - 1, 1, *+* ... * # same thing - -More typically the function is unary, in which case any extra values -in the lefthand list may be construed as human-readable documentation: - - 0,2,4, { $_ + 2 } ... 42 # all the evens up to 42 - 0,2,4, *+2 ... 42 # same thing - , { .succ } ... * # same as 'a'..* - -The function need not be monotonic: - - 1, -* ... * # 1, -1, 1, -1, 1, -1... - False, &prefix: ... * # False, True, False... - -The function can be 0-ary as well, in which case it's okay for the -closure to be the first thing: - - { rand } ... * # list of random numbers - -The function may also be slurpy (n-ary), in which case C the -preceding values are passed in (which means they must all be cached -by the operator, so performance may suffer, and you may find yourself -with a "space leak"). - -The arity of the function need not match the number of return values, but -if they do match you may interleave unrelated sequences: - - 1,1,{ $^a + 1, $^b * 2 }...* # 1,1,2,2,3,4,4,8,5,16,6,32... - -Note in this case that the any limit test is applied to the entire list -returned from the function, which contains two values. - -A sequence generated from an explicit function places no type -constraints on the sequence other than those constraints implied by -the signature of the function. If the signature of the function does -not match the existing values, however, an exception is thrown. - -If no generating closure is provided, and the sequence is numeric, -and is obviously arithmetic or geometric (from examining its I -3 values), the appropriate function is deduced: - - 1, 3, 5 ... * # odd numbers - 1, 2, 4 ... * # powers of 2 - 10,9,8 ... 0 # countdown - -That is, supposing we call the last three numbers C<$a>, C<$b>, and -C<$c>, and then define: - - $ab = $b - $a; - $bc = $c - $b; - -If C<$ab == $bc> and C<$ab> is not zero, then we deduce an arithmetic -progression determined by the function C<*+$ab>. If C<$ab> is zero, -and the three values look like numbers, then the function is C<*+0>. -If they do not look like numbers, then the function selected is either -C<*.succ> or C<*.pred> depending on whether C<$b cmp $c> appears to be -Increasing or Decreasing. If C returns Same then an identity -function is assumed. - -If C<$ab != $bc> and C, then a similar calculation -is done using division rather than subtraction to determine whether -a geometric progression is warranted. Define: - - $ab = $b / $a; - $bc = $c / $b; - -If the two quotients are equal (and finite), then a geometric -function of C<{$_ * $bc}> is deduced. - -The values on the left are considered samples of how the sequence will -start if the end test permits it to get that far. Hence, the test for -completion applies even to those values: - - 0,2,4 ... 16 # 0,2,4,8,16 - 0,2,4 ... 4 # 0,2,4 - 0,2,4 ... 2 # 0,2 - 0,2,4 ... 0 # 0 - -If there are more than three values, only the final three are tested -against the deduced function; the earlier ones are always produced -regardless of their value: - - 40, 2, 'Hike!', 0, 2, 4 ... 2 # 40, 2, 'Hike!', 0 - -If there are only two values in the list so far, C<$a> and C<$b>, and the difference C<$ab> -is non-zero, we assume an arithmetic progression of C<*+$ab>. If C<$ab> -is zero, then again whether we use C<*+0> or C<*.succ>/C<*.pred> depends on -whether the two values look like numbers. - -If there is only one value, we always assume incrementation via -C<.succ>. (This may be forced to C<.pred> by examination of a limit, -as specified below.) Hence these come out the same: - - 1 .. * - 1 ... * - 1,2 ... * - 1,2,3 ... * - <1 2 3> ... * - -Likewise, if the given value or values are not numeric, C<.succ> is assumed, -so these come out the same: - - 'a' .. * - 'a' ... * - 'a','b' ... * - 'a','b','c' ... * - ... * - -If the list on the left is C<()>, we use the function C<{()}> to generate an -infinite supply of nothing. - -When there is a deduced function from the last three values, and when -there is a limit that "misses" but is suitably literal and of a similar -type (that is, a numeric value for a numeric sequence, or a string value -for a string sequence), then the deduced function will attempt to detect -when the limit would be bypassed, and stop the sequence right there -instead of running off to infinity: - - 42,1,3,5 ... 8 # 42,1,3,5,7 - 42,1,3,5 ... 4 # 42,1,3 - 42,1,3,5 ... 2 # 42,1 - 42,1,3,5 ... 0 # 42 - 1,3,5 ... 2 # 1 - 1,3,5 ... 0 # () - -If a limit is given that is not a literal, or is not of a sufficiently -similar type, it must smartmatch exactly. If it does not, -an infinite list results. For instance, since "asymptotically -approaching" is not the same as "equals", both of the following are -infinite lists, as if you'd specified C<*> for the limit rather than 0: - - 1,1/2,1/4 ... 0 # like 1,1/2,1/4 ... * - 1,-1/2,1/4 ... 0 # like 1,-1/2,1/4 ... * - -Likewise, this is all of the even numbers: - - 0,2,4 ... * == 7 - -To catch such a situation, it is advised to write an inequality instead: - - 0,2,4 ...^ { $_ > 7 } - -When an explicit limit function is used, it -may choose to terminate its list by returning any true value. -Since this operator is list associative, an inner function may be -followed by a C<...> and another function to continue the list, -and so on. Hence, - - 1, *+1 ... { $_ == 9 }, - 10, *+10 ... { $_ == 90 }, - 100, *+100 ... { $_ == 900 } - -produces - - 1,2,3,4,5,6,7,8,9, - 10,20,30,40,50,60,70,80,90, - 100,200,300,400,500,600,700,800,900 - -Given the normal matching rules when there's no closure, -we can write that more simply as: - - 1, 2, 3 ... 9, - 10, 20, 30 ... 90, - 100, 200, 300 ... 900 - -or even just: - - 1, 2, 3 ... - 10, 20, 30 ... - 100, 200, 300 ... 900 - -since an exactly matching limit is returned as part of the -sequence, provided it is a value of the appropriate type, and -not a closure. - -For functions deduced when there is only one value on the left, -the final value is used to determine whether C<*.succ> or C<*.pred> is -more appropriate. The two values are compared with C to determine -the direction of the progression. - -Hence the sequence operator is "auto-reversing", unlike a range operator. - - 'z' .. 'a' # represents a null range - 'z' ... 'a' # z y x ... a - -For completeness, you may omit the first value using the C<^...> form: - - 'z' ^... 'a' # y x ... a - 5 ^... 1 # 4, 3, 2, 1 - -But be aware that this form will almost certainly confuse your readers if the list -on the left is complicated, especially if the left list is another sequence: - - 1, 2, 3 ^... *; # 2, 3 ... ! - 1, 2, 3 ... 10, 20, 30 ^... *; # 2, 3 ... !?!? - -And yes, there's also a C<^...^> form, for those people who have an -undue fondness for symmetry. - -As with numeric values, a string sequence with a literal string endpoint -will attempt to determine when it's traversing the endpoint without -matching exactly. In addition, however, if on an increasing sequence -the next string would be longer than the endpoint, the sequence stops for -that as well, since string comparison does not always map directly to the -order of successors. If this is insufficient, use a different endpoint -smartmatch such as a regular expression or a closure to do fancier tests. - -Note that the sequence - - 1.0, *+0.2 ... 2.0 - -is calculated in C arithmetic, not C, so the C<2.0> matches -exactly and terminates the sequence. - -Note: the yada operator is recognized only where a term is expected. -This operator may only be used where an infix is expected. If you -put a comma before the C<...> it will be taken as a yada list operator -expressing the desire to fail when the list reaches that point: - - 1..20, ... "I only know up to 20 so far mister" - -A special exception is made for any sequence whose endpoints are strings that -happen to represent single codepoints, since the user will typically be thinking -of such strings as characters rather than strings. If you say something like: - - 'A' ... 'z' - "\xff" ... "\0" - -it is assumed that you aren't interested in carrying within alphabetic -ranges, so instead of using the ordinary C<.succ>/C<.pred> for -strings, it uses a monotonic function that increments or decrements -the underlying codepoint number like - - 'A', { $^prev.ord.succ.chr } ... 'z'; - "\xff", { $^prev.ord.pred.chr } ... "\0"; - -You will note that this alternate definition doesn't change the meaning of -any sequence that falls within a conventional rangechar range: - - 'a'...'z' - '9'...'0' - -If the start and stop strings are the same length, this is applied at every position, with carry. - - 'aa' ... 'zz' # same as 'a' .. 'z' X~ 'a' .. 'z' - -Hence, to produce all octal numbers that fit in 16 bits, you can say: - - '000000' ... '177777' - -At need, you can override these numeric codepoint semantics by using -an explicit successor function: - - '⓪', *.succ ... '㊿' # circled digits/numbers 0..50 - -(In fact, this is precisely what the translation from ranges does, in -order to preserve the abstract ordering of rangechars that have -non-contiguous codepoints. But it's easier just to use the range -operator if that's the case.) - -If the start string is shorter than the stop string, the strings are -assumed to be right justified, and the leftmost start character is -duplicated when there is a carry: - - '0' ... '177777' # same octal sequence, without leading 0's - -Going the other way, digits are dropped when they go to the first existing -digit until the current value is as short as the final value, then the digits -are left there. Which is a fancy way of saying that - - '177777' ... '000000' - -and - - '177777' ... '0' - -both do exactly what the forward sequences do above, only in reverse. - -As an extra special rule, that works in either direction: if the bottom -character is a '0' and the top character is alphanumeric, it is assumed -to be representing a number in some base up to base 36, where digits above ten -are represented by letters. Hence the same sequences of 16-bit numbers, only in -hexadecimal, may be produced with: - - '0000' ... 'ffff' - '0' ... 'ffff' - 'ffff' ... '0000' - 'ffff' ... '0' - -And as a limiting case, this applies to single characters also: - - '0' .. 'F' # 0..9, 'A'..'F' - -Note that case is intuited from the top character of the range. - -There are many different possible semantics for string increment. -If this isn't the semantics you want, you can always write your own -successor function. Sometimes the stupid codepoint counting is what you want. -For instance, you can get away with ranges of capital Greek letters: - - 'ΑΑΑ' ... 'ΩΩΩ' - -However, if you try it with the lowercase letters, you'll get both -forms of lowercase sigma, which you probably don't want. If there's -only one or two letters you don't want, you can grep out those entries, -but in the general case, you need an incrementer that knows what sequence -you're interested in. Perhaps there can be a generic method, - - 'ααα', *.succ-in(@greek) ... 'ωωω' - -that will take any given sequence and use it as the universe of incrementation -for any matching characters in the string. - -To preserve Perl 5 length limiting semantics of a range like -C<'A'..'zzz'>, you'd need something like: - - 'A', *.succ ... { last if .chars > 3; $_ eq 'zzz' } - -(That's not an exact match to what Perl 5 does, since C is -a bit fancier in Perl 6, but starting with 'A' it'll work the same. -You can always supply your own increment function.) - -Note that the C call above returns no argument, so even though -the internal test calls C, this call to C bypasses that -as if the sequence had been specified with C<...^> instead. Going the -other way, a C<...^> maybe be forced to have a final value by passing -an argument to an explicit C. In the same way, -that will bypass the argumentless internal C. - -In a similar way, the sequence may be terminated by calling C -from the generator function: - - 10,9,8, { $_ - 1 || last } ... * # same as 10 ... 1 - -For purposes of deciding when to terminate the eager part of a 'mostly -eager' list, any sequence that terminates with an exact value (or -that starts another sequence with exact values) is considered finite, -as is any sequence that has an explicit ending closure. -However, any sequence that ends C<*> is considered to be of unknowable -length. However, by the definition of "mostly eager" in L, -the implementation may be able to determine that such a sequence is -finite by conjectural evaluation; such workahead cannot, of course, always -prove that a sequence is infinite without running a Very Long Time. -Note also that, by using the form that specifies both a closure and -a final value, it is possible to write a sequence that appears to be -finite but that never actually reaches its final value before resources -are exhausted; such a sequence will be treated as finite, but eventually -will come to grief: - - @a = 1, *+0.00000000000000000000000000000000000001 ... 2; # heat death - -For any such sequence or list that the user knows to be infinite, but -the computer can't easily know it, it is allowed to mark the end of -the list with a C<*>, which indicates that it is to be treated as an -infinite list in contexts that care. Similarly, any list ending -with an operator that interprets C<*> as infinity may be taken the -same way, such as C<$n xx *>, or C<1..*>. - -On the other hand, it's possible to write a sequence that appears to be -infinite, but is terminated by a C from the iterator closure. An -implementation is required to trap such a loop termination and change the -status of the list from 'infinite' to 'finite, such that C<.elems> reports -the actual produced length, not C. - - -=back - -Many of these operators return a list of Cs or Cs, which depending on -context may or may not flatten them all out into one flat list. The -default is to flatten, but see the contextualizers below. - -=head2 List prefix precedence - -=over - -=item * - -C<< infix:<=> >>, list assignment - - @array = 1,2,3; - -With compound targets, performs list assignment. The right side -is looser than list infix. You might be wondering why we've classified -this as a prefix operator when its token name is C<< infix:<=> >>. -That's because you can view the left side as a special syntax for a -prefix listop, much as if you'd said: - - @array.assign: 1,2,3 - -However, the tokener classifies it as infix because it sees it when -it's expecting an infix operator. Assignments in general are treated -more like retroactive macros, since their meanings depend greatly on -what is on the left, especially if what is on the left is a declarator -of some sort. We even call some of them pseudo-assignments, but they're -all a bit pseudo insofar as we have to figure out whether the left side -is a list or a scalar destination. - -In any case, list assignment is defined to be arbitrarily lazy, -insofar as it basically does the obvious copying as long as there -are scalar destinations on the left or already-computed values on -the right. However, many list lvalues end with an array destination -(where assignment directly to an array can be considered a degenerate -case). When copying into an array destination, the list assignment is -"mostly eager"; it requests the list to evaluate its leading iterators -(and values) to the extent that they are known to be finite, and -then suspend, returning the known values. The assignment then copies -the known values into the array. (These two steps might actually be -interleaved depending on how the iterator API ends up being defined.) -It then sets up the array to be self-extending by using the remainder -of the list as the "specs" for the array's remaining values, to be -reified on demand. Hence it is legal to say: - - @natural = 0..*; - -(Note that when we say that an iterator in list context suspends, -it is not required to suspend immediately. When the scheduler is -running an iterator, it may choose to precompute values in batches if -it thinks that approach will increase throughput. This is likely to -be the case on single-core architectures with heavy context switching, -and may very well be the case even on manycore CPU architectures when -there are more iterators than cores, such that cores may still have -to do context switching. In any case, this is all more-or-less -transparent to the user because in the abstract the list is all -there, even if it hasn't been entirely computed yet.) - -Though elements may be reified into an array on demand, they act -like ordinary array elements both before and after reification, as -far as the user is concerned. These elements may be written to if -the underlying container type supports it: - - @unnatural = 0..*; - @unnatural[42] = "Life, the Universe, and Everything"; - -Note that, unlike assignment, binding replaces the container, -so the following fails because a range object cannot be subscripted: - - @natural := 0..*; # bind a Range object - @natural[42] = "Life, the Universe, and Everything"; # FAILS - -but this succeeds: - - @unnatural := [0..*]; # bind an Array object - @unnatural[42] = "Life, the Universe, and Everything"; # ok - -It is erroneous to make use of any side effects of reification, such -as movement of a file pointer, since different implementations may -have different batch semantics, and in any case the unreified part -of the list already "belongs" to the array. - -When a self-extending array is asked for its count of elements, it -is allowed to return C<+Inf> without blowing up if it can determine -by inspection that its unreified parts contain any infinite lists. -If it cannot determine this, it is allowed to use all your -memory, and then some. C<:)> - -Assignment to a hash is not lazy (probably). - -=item * - -C<< infix:<:=> >>, run-time binding - - $signature := $capture - -A new form of assignment is present in Perl 6, called I, used in -place of typeglob assignment. It is performed with the C<:=> operator. -Instead of replacing the value in a container like normal assignment, it -replaces the container itself. For instance: - - my $x = 'Just Another'; - my $y := $x; - $y = 'Perl Hacker'; - -After this, both C<$x> and C<$y> contain the string C<"Perl Hacker">, -since they are really just two different names for the same variable. - -There is also an identity test, C<=:=>, which tests whether two names -are bound to the same underlying variable. C<$x =:= $y> would return -true in the above example. - -The binding fails if the type of the variable being bound is sufficiently -inconsistent with the type of the current declaration. Strictly speaking, -any variation on - - my Any $x; - $x := [1,2,3]; - -should fail because the type being bound is not consistent with -C, but since the C type is not a real instantiable -type but a generic (non)constraint, and C is sort of -a double non-constraint similar to C, we treat this situation -specially as the equivalent of binding to a typeless variable. - -The binding operator parses as a list assignment, so it is reasonable to -generate a list on the right without parens: - - @list := 1 ... *; - -=item * - -C<< infix:<::=> >>, bind and make readonly - - $signature ::= $capture - -This does the same as C<:=>, then marks any destination parameters as -readonly (unless the individual parameter overrides this with either -the C trait or the C trait). It's particularly useful -for establishing readonly dynamic variables for a dynamic scope: - - { - my $*OUT ::= open($file, :w) || die $!; - doit(); # runs with redirected stdout - } - doit(); # runs with original stdout - -If C wants to change C<$*OUT>, it must declare its own -dynamic variable. It may not simply assign to C<$*OUT>. - -Note that the semantics of C<::=> are virtually identical to -the normal binding of arguments to formal subroutine parameters -(which also default to readonly). - -This operator parses as a list assignment. - -=item * - -Normal listops - - print push say join split substr open etc. - -=item * - -Listop forms of junctional operators - - any all one none - -=item * - -Exception generators - - fail "Division by zero" - die System::Error(ENOSPC,"Drive $d seems to be full"); - warn "Can't open file: $!" - -=item * - -Stubby exception generators - - ... - !!! "fill this in later, Dave" - ??? "oops in $?CLASS" - -The C<...> operator is the "yada, yada, yada" list operator, which -among other things is used as the body in function prototypes. -It complains bitterly (by calling C) if it is ever executed. -Variant C calls C, and C calls C. The argument -is optional, but if provided, is passed onto the C, C, -or C. Otherwise the system will make up a message for you based -on the context, indicating that you tried to execute something that -is stubbed out. (This message differs from what C, C, and -C would say by default, since the latter operators typically point -out bad data or programming rather than just an incomplete design.) - -=item * - -Reduce operators - - [+] [*] [<] [\+] [\*] etc. - -See L below. - -=item * - -Sigils as coercions to roles - - Sigil Alpha variant - ----- ------------- - $ Scalar - @ Positional (or Iterable?) - % Associative - & Callable - -Note that, since these are coercions to roles, they are allowed -to return any actual type that does the role in question. - -Unless applied directly to a scalar variable, as in C<@$a>, these -may only be applied with explicit parens around an argument that -is processed as a bare C object, not a flattening list: - - $(1,2 Z 3,4) # Scalar((1,3),(2,4)) - @(1,2 Z 3,4) # ((1,3),(2,4)) - %(1,2 Z 3,4) # (1 => 3, 2 => 4) - - $(1,2 X 3,4) # Scalar((1,3),(1,4),(2,3),(2,4)) - @(1,2 X 3,4) # ((1,3),(1,4),(2,3),(2,4)) - -(Note, internal parens indicate nested C structure here, -since there is no flattening.) - -Since a C with one argument is transparent, there can be no -difference between the meaning of C<@($a)> and C<@$a>. - -=item * - -The C contextualizer - - item foo() - -The new name for Perl 5's C contextualizer. Equivalent to C<$(...)> -(except that empty C<$()> means C<$($/.made // ~$/)>, while empty C yields C). -We still call the values scalars, and talk about "scalar operators", but -scalar operators are those that put their arguments into item context. - -If given a list, this function makes a C object from it. The function -is agnostic about any C embedded in such a sequence, and any contextual -decisions will be deferred until subsequent use of the contents. - -Note that this parses as a list operator, not a unary prefix operator, -since you'd generally want it for converting a list to a sequence object. -(Single items don't need to be converted to items.) Note, however, that -it does no flattening of its list items: - - @x = lol(item (1,2),(3,4)) # @x eqv LoL( (1,2), (3,4) ) - -=item * - -The C contextualizer - - list foo() - -Forces the subsequent expression to be evaluated in list context. -Any flattening happens lazily. - -=item * - -The C contextualizer - - flat foo() - -Forces the subsequent expression to be evaluated in a flattening -list context. The result will be recursively flattened, i.e., -contain no embedded C, C or C objects. - -=item * - -The C contextualizer - - hash foo() - -Forces the subsequent expression to be evaluated in hash context. -The expression is evaluated in list context (flattening any Cs or -Cs), -then a hash will be created from the list, taken as a list of Cs. -(Any element in the list that is not a C will pretend to be a key -and grab the next value in the list as its value.) Equivalent to -C<%(...)> (except that empty C<%()> means C<%($/)>, while -empty C means an empty hash). - -=back - -=head2 Loose and precedence - -=over - -=item * - -C<< infix: >>, short-circuit and - - $a and $b and $c ... - -Returns the first argument that evaluates to false, otherwise -returns the result of the last argument. In list context forces -a false return to mean C<()>. See C<&&> above for high-precedence -version. - -=item * - -C<< infix: >>, proceed on success - - test1() andthen test2() andthen test3() ... - -Returns the first argument whose evaluation indicates failure -(that is, if the result is undefined). Otherwise it -evaluates and returns the right argument. - -If the right side is a block or pointy block, the result of the left -side is bound to any arguments of the block. If the right side is -not a block, a block scope is assumed around the right side, and the -result of the left side is implicitly bound to C<$_> for the scope -of the right side. That is, - - test1() andthen test2() - -is equivalent to - - test1() andthen -> $_ { test2() } - -There is no corresponding high-precedence version. - -If you wish to have the same semantics in the opposite order, use the C statement modifier. - -=back - -=head2 Loose or precedence - -=over - -=item * - -C<< infix: >>, short-circuit inclusive or - - $a or $b or $c ... - -Returns the first argument that evaluates to true, otherwise returns -the result of the last argument. In list context forces a false return -to mean C<()>. See C<||> above for high-precedence version. - -=item * - -C<< infix: >>, exclusive or - - $a xor $b xor $c ... - -Returns the true argument if there is one (and only one). Returns the -last argument if all arguments are false. Returns C -otherwise (when more than one argument is true). In list context -forces a false return to mean C<()>. See C<^^> above for -high-precedence version. - -=item * - -C<< infix: >>, proceed on failure - - test1() orelse test2() orelse test3() ... - -Returns the first argument that evaluates successfully (that is, -if the result is defined). Otherwise returns the result of the -right argument. - -If the right side is a block or pointy block, the result of the left -side is bound to any arguments of the block. If the right side is -not a block, a block scope is assumed around the right side, and the -result of the left side is implicitly bound to C<$_> for the scope -of the right side. That is, - - test1() orelse test2() - -is equivalent to - - test1() orelse -> $_ { test2() } - -(The high-precedence C operator is similar, but does not set C<$_> or -treat blocks specially.) - -If you wish to have the same semantics in the opposite order, use the C statement modifier. - -=back - -=head2 Terminator precedence - -As with terms, terminators are not really a precedence level, but -looser than the loosest precedence level. They all have the effect of -terminating any operator precedence parsing and returning a complete -expression to the main parser. They don't care what state the operator -precedence parser is in. If the parser is currently expecting a term -and the final operator in the expression can't deal with a nullterm, -then it's a syntax error. (Notably, the comma operator and many prefix -list operators can handle a nullterm.) - -=over - -=item * - -Semicolon: C<;> - - $x = 1; $y = 2; - -The context determines how the expressions terminated by semicolon -are interpreted. At statement level they are statements. Within a -bracketing construct they are interpreted as lists of Cs, -which in lol context will be treated as the multiple dimensions of a -multidimensional slice. (Other contexts may have other interpretations -or disallow semicolons entirely.) - -=item * - -Feed operators: C<< <== >>, C<< ==> >>, C<<< <<== >>>, C<<< ==>> >>> - - source() ==> filter() ==> sink() - -The forms with the double angle append rather than clobber the sink's -todo list. The C<<< ==>> >>> form always looks ahead for an appropriate -target to append to, either the final sink in the chain, or the next -filter stage with an explicit C<@(*)> or C<@(**)> target. This means -you can stack multiple feeds onto one filter command: - - source1() ==>> - source2() ==>> - source3() ==>> - filter(@(*)) ==> sink() - -Similar semantics apply to C<<< <<== >>> except it looks backward for -an appropriate target to append to. - -=item * - -Control block: C<{...}> - -When a block occurs after whitespace where an infix is expected, it is -interpreted as a control block for a statement control construct. -(If there is no whitespace, it is a subscript, and if it is where a -term is expected, it's just a bare closure.) If there is no statement -looking for such a block currently, it is a syntax error. - -=item * - -Statement modifiers: C, C, C, C, C - -Statement modifiers terminate one expression and start another. - -=item * - -Any unexpected C<)>, C<]>, C<}> at this level. - -Calls into the operator precedence parser may be parameterized -to recognize additional terminators, but right brackets of any -sort (except angles) are automatically included in the set of -terminators as tokens of length one. (An infix of longer length -could conceivably start with one of these characters, and would be -recognized under the longest-token rule and continue the expression, -but this practice is discouraged. It would be better to use Unicode -for your weird operator.) Angle brackets are exempted so that they -can form hyperoperators (see L). - -=item * - -A block-final C<}> at the end of the line terminates the current expression. -A block within an argument list terminates the argument list unless -followed by the comma operator. - -=back - -=head1 Changes to Perl 5 operators - -Several operators have been given new names to increase clarity and better -Huffman-code the language, while others have changed precedence. - -=over - -=item * - -Perl 5's C<${...}>, C<@{...}>, C<%{...}>, etc. dereferencing -forms are now C<$(...)>, C<@(...)>, C<%(...)>, etc. instead. -(Use of the Perl 5 curly forms will result in an error message -pointing the user to the new forms.) -As in Perl 5, the parens may be dropped when dereferencing -a scalar variable. - -=item * - -C<< -> >> becomes C<.>, like the rest of the world uses. There is -a pseudo C<< postfix:«->» >> operator that produces a compile-time -error reminding Perl 5 users to use dot instead. (The "pointy block" -use of C<< -> >> in Perl 6 requires preceding whitespace when the arrow -could be confused with a postfix, that is, when an infix is expected. -Preceding whitespace is not required in term position.) - -=item * - -The string concatenation C<.> becomes C<~>. Think of it as -"stitching" the two ends of its arguments together. String append -is likewise C<~=>. - -=item * - -The filetest operators are gone. We now use a C as a -pattern that calls an object's method: - - if $filename.IO ~~ :e { say "exists" } - -is the same as - - if so $filename.IO.e { say "exists" } - -Likewise - - if $filename.IO ~~ :!e { say "doesn't exist" } - -is the same as - - if not $filename.IO.e { say "doesn't exist" } - -The 1st form actually translates to the latter form, so the object's -class decides how to dispatch methods. It just so happens that the -C role defaults to the expected filetest semantics, but C<$regex.i> might -tell you whether the regex is case insensitive, for instance. Likewise, -you can test anything for definedness or undefinedness: - - $obj ~~ :defined - $obj ~~ :!defined - -Using the pattern form, multiple tests may be combined via junctions: - - given $path { - when :r & :w & :x {...} - when :!w | :!x {...} - when * {...} - } - -When adverbial pairs are stacked into one term, it is assumed they are -ANDed together, so - - when :r :w :x - -is equivalent to either of: - - when :r & :w & :x - when all(:r,:w,:x) - -The pair forms are useful only for boolean tests because the method's -value is evaluated as a C, so the -method form must be used for any numeric-based tests: - - if $filename.IO.s > 1024 {...} - -However, these still work: - - given $io { - when :s {...} # file has size > 0 - when :!s {...} # file size == 0 - } - -One advantage of the method form is that it can be used in places that -require tighter precedence than C<~~> provides: - - sort { $^a.modified <=> $^b.modified }, @files».IO - -though that's a silly example since you could just write: - - sort { .modified }, @files».IO - -But that demonstrates the other advantage of the method form, which is -that it allows the "unary dot" syntax to test the current topic. - -Unlike in earlier versions of Perl 6, these filetest methods do not return -stat buffers, but simple scalars of type C, C, or C. - -In general, the user need not worry about caching the stat buffer -when a filename is queried. The stat buffer will automatically be -reused if the same object has recently been queried, where "recently" -is defined as less than a second or so. If this is a concern, an -explicit C or C may be used to return an explicit C -object that will not be subject to timeout, and may be tested -repeatedly just as a filename or handle can. An C object has -a C<.path> method that can be queried for its path (if known). - -(Inadvertent use of the Perl 5 forms will normally result in treatment -as a negated postdeclared subroutine, which is likely to produce an -error message at the end of compilation.) - -=item * - -All postfix operators that do not start with a dot also have -an alternate form that does. (The converse does not hold--just because -you can write C doesn't mean you can write C. Likewise -the ability to say C<$x.'foo'> does not imply that C<$x'foo'> will work.) - -The postfix interpretation of an operator may be overridden by -use of a quoted method call, which calls the prefix form instead. -So C is always the postfix operator, but C will always -call C. In particular, you can say things like C<$array.'@'>. -This also includes any operator that would look like something -with a special meaning if used after the method-calling dot. For example, -if you defined a C<< prefix:<=> >>, and you wanted to write it using -the method-call syntax instead of C<=$object>, the parser would take -C<$object.=> as the mutation syntax (see L, "Mutating methods"). -Writing C<$object.'='> will call your prefix operator. - -=item * - -Unary C<~> now imposes a string (C) context on its -argument, and C<+> imposes a numeric (C) context (as opposed -to being a no-op in Perl 5). Along the same lines, C imposes -a boolean (C) context, and the C<|> unary operator imposes -a function-arguments (C or C) context on its argument. -Unary sigils are allowed when followed by a C<$> sigil on a scalar variable; -they impose the container context implied by their sigil. -As with Perl 5, however, C<$$foo[bar]> parses as C<( $($foo) )[bar]>, -so you need C<$($foo[bar])> to mean the other way. In other -words, sigils are not really parsed as operators, and you must -use the parenthetical form for anything complicated. - -=item * - -Bitwise operators get a data type prefix: C<+>, C<~>, or C. -For example, Perl 5's C<|> becomes either C<+|> or C<~|> or C, -depending on whether the operands are to be treated as numbers, -strings, or boolean values. Perl 5's left shift C< << > becomes -C< +< >, and correspondingly with right shift. Perl 5's unary C<~> -(one's complement) becomes either C<+^> or C<~^> or C, since a -bitwise NOT is like an exclusive-or against solid ones. Note that -C is functionally identical to C, but conceptually coerces to -boolean first and then flips the bit. Please use C instead. As -explained in L, a bitwise operator can be turned -into its corresponding assignment operator by following it with C<=>. -For example Perl 5's C< <<= > becomes C< +<= >. - -C is a logical OR but differs from C<||> in that C always -evaluates both sides and returns a standard boolean value. That is, -it's equivalent to C<< ?$a + ?$b != 0 >>. Another difference is that -it has the precedence of an additive operator. - -C is a logical AND but differs from C<&&> in that C always -evaluates both sides and returns a standard boolean value. That is, -it's equivalent to C<< ?$a * ?$b != 0 >>. Another difference is that -it has the precedence of a multiplicative operator. - -Bitwise string operators (those starting with C<~>) may only be -applied to C types or similar compact integer arrays, and treat -the entire chunk of memory as a single huge integer. They differ from -the C<+> operators in that the C<+> operators would try to convert -the string to a number first on the assumption that the string was an -ASCII representation of a number. - -=item * - -C splits into two operators: C (which concatenates repetitions -of a string to produce a single string), and C (which creates a list of -repetitions of a list or item). C<"foo" xx *> represents an arbitrary -number of copies, useful for initializing lists. The left side of -an C is re-evaluated for each copy; use a temporary to force a single -evaluation. (But note that this is not necessary when the optimizer will -do constant folding.) - -=item * - -The C conditional operator becomes C. A pseudo operator, -C<< infix: >>, catches migratory brainos at compile time. - -=item * - -C gets a synonym: C<< < ... > >>, and an interpolating -variant, C<«...»>. -For those still living without the blessings of Unicode, that can also be -written: C<<< << ... >> >>>. - -=item * - -Comma C<,> now constructs a C object from its operands. You have to -use a C<[*-1]> subscript to get the last one. -(Note the C<*>. Negative subscripts no longer implicitly count from -the end; in fact, the compiler may complain if you use C<[-1]> on an -object known at compile time not to have negative subscripts.) - -=item * - -The unary backslash operator is not really an operator, but a special noun form. -It "captures" its argument or arguments, and returns an -object representing those arguments. You can I this object -in several ways to retrieve different parts of the arguments; see the -definition of C in L for details. (No whitespace is allowed -after the backslash because that would instead start an "unspace", that is, -an escaped sequence of whitespace or comments. See L for details. -However, oddly enough, because of that unspace rule, saying C<\\ $foo> -turns out to be equivalent to C<\$foo>.) - -=item * - -The old C<..> flipflop operator is now done with -C operator. (C<..> now always produces a C object -even in item context.) The C operator may take a caret on -either end to exclude either the beginning or ending. There is -also a corresponding C operator with Perl 5's C<...> semantics. - -The two sides of a flipflop are evaluated as smartmatches against -the current value of the topic stored in C<$_>. For instance, you may say - - /foo/ ff * - -to match the first line containing 'foo', along with all following -lines: since the C<*> always smartmatches, it create a flipflop that -never flops once flipped. - -The state of a flipflop is kept in an anonymous state variable, so separate -closure clones get their own states. - -Note that unlike Perl 5's flipflop, numeric values are not -automatically checked against the current line number. (If you -wish to have those semantics for your smartmatches, you could mixin -a numeric value to C<$_> to create a chimeric object that is both -integer and string. Conjecture: C should have an option that -does this.) - -=item * - -All comparison operators are unified at the same precedence level. -See L below. - -=item * - -The list assignment operator now parses on the right like -any other list operator, so you don't need parens on the right side of: - - @foo = 1, 2, 3; - -You do still need them on the left for - - ($a, $b, $c) = 1, 2, 3; - -since assignment operators are tighter than comma to their left. - -"Don't care" positions may be indicated by assignment to the C<*> token. -A final C<*> throws away the rest of the list: - - ($a, *, $c) = 1, 2, 3; # throw away the 2 - ($a, $b, $c, *) = 1..42; # throw away 4..42 - -(Within signature syntax, a bare C<$> can ignore a single argument as well, -and a bare C<*@> can ignore the remaining arguments.) - -List assignment offers the list on the right to each container on the -left in turn, and each container may take one or more elements from the -front of the list. If there are any elements left over, a warning is -issued unless the list on the left ends with C<*> or the final iterator -on the right is defined in terms of C<*>. Hence none of these warn: - - ($a, $b, $c, *) = 1..9999999; - ($a, $b, $c) = 1..*; - ($a, $b, $c) = 1 xx *; - ($a, $b, $c) = 1, 2, *; - -This, however, warns you of information loss: - - ($a, $b, $c) = 1, 2, 3, 4; - -As in Perl 5, assignment to an array or hash slurps up all the -remaining values, and can never produce such a warning. (It will, -however, leave any subsequent lvalue containers with no elements, -just as in Perl 5.) - -The left side is evaluated completely for its sequence of containers before -any assignment is done. Therefore this: - - my $a = 0; my @b; - ($a, @b[$a]) = 1, 2; - -assigns 2 to C<@b[0]>, not C<@b[1]>. - -=item * - -The item assignment operator expects a single expression with -precedence tighter than comma, so - - loop ($a = 1, $b = 2; ; $a++, $b++) {...} - -works as a C programmer would expect. The term on the right of the -C<=> is always evaluated in item context. - -The syntactic distinction between item and list assignment is similar -to the way Perl 5 defines it, but has to be a little different because -we can no longer decide the nature of an inner subscript on the basis -of the outer sigil. So instead, item assignment is restricted to -lvalues that are simple scalar variables, and assignment to anything -else is parsed as list assignment. The following forms are parsed as -"simple lvalues", and imply item assignment to the scalar container: - - $a = 1 # scalar variable - $foo::bar = 1 # scalar package variable - $(ANY) = 1 # scalar dereference (including $$a) - $::(ANY) = 1 # symbolic scalar dereference - $foo::(ANY) = 1 # symbolic scalar dereference - -Such a scalar variable lvalue may be decorated with declarators, -types, and traits, so these are also item assignments: - - my $fido = 1 - my Dog $fido = 1 - my Dog $fido is trained is vicious = 1 - -However, anything more complicated than that (including parentheses -and subscripted expressions) forces parsing as list assignment instead. -Assignment to anything that is not a simple scalar container also forces -parsing as list assignment. List assignment expects an expression -that is looser than comma precedence. The right side is always -evaluated in list context: - - ($x) = 1,2,3 - $x[1] = 1,2,3 - @$array = 1,2,3 - my ($x, $y) = 1,2,3 - our %hash = :a<1>, :b<2> - -The rules of list assignment apply, so all the assignments involving -C<$x> above produce warnings for discarded values. A warning may be -issued at compile time if it is detected that a run-time warning is -inevitable. - -The C<=> in a default declaration within a signature is not really -assignment, and is always parsed as item assignment. (That is, to -assign a list as the default value you must use parentheses to hide -any commas in the list value.) - -To assign a list to a scalar value, you cannot say: - - $a = 1, 2, 3; - -because the 2 and 3 will be seen as being in a sink (void) context, as if -you'd said: - - ($a = 1), 2, 3; - -Instead, you must do something to explicitly disable or subvert the -item assignment interpretation: - - $a = [1, 2, 3]; # force construction (probably best practice) - $a = (1, 2, 3); # force grouping as syntactic item - $a = list 1, 2, 3; # force grouping using listop precedence - $a = @(1, 2, 3); # same thing - @$a = 1, 2, 3; # force list assignment - $a[] = 1, 2, 3; # same thing - -If a function is contextually sensitive and you wish to return a scalar -value, you must use C (or C<$> or C<+> or C<~>) if you wish to -force item context for either the subscript or the right side: - - @a[foo()] = bar(); # foo() and bar() called in list context - @a[item foo()] = item bar(); # foo() and bar() called in item context - @a[$(foo())] = $(bar()); # same thing - @a[+foo()] = +bar(); # foo() and bar() called in numeric context - %a{~foo()} = ~bar(); # foo() and bar() called in string context - -But note that the first form still works fine if C and C -are item-returning functions that are not context sensitive. - -In general, this will all just do what the user expects most of the time. -The rest of the time item or list behavior can be forced with minimal -syntax. - -=item * - -List operators are all parsed consistently. As in Perl 5, -to the left a list operator looks like a term, while to the right it looks like -an operator that is looser than comma. Unlike in Perl 5, the difference -between the list operator form and the function form is consistently -indicated via whitespace between the list operator and the first -argument. If there is whitespace, it is always a list operator, -and the next token will be taken as the first term of the list (or -if there are no terms, as the expression terminator). Any infix operator -occurring where a term is expected will be misinterpreted as a term: - - say + 2; # means say(+2); - -If there is no whitespace, subsequent parsing depends on the -syntactic category of the next item. Parentheses (with or without -a dot) turn the list operator into a function call instead, and -all the function's arguments must be passed inside the parentheses -(except for postfix adverbs, which may follow the parentheses provided they -would not attach to some other operator by the rules of precedence). - -A postfix operator following a listop is parsed as working on -the return value of the listop. - - foo.[] # same as foo()[] - foo.() # same as foo()() - foo++ # legal (if foo() is rw) - -If the next item after the list operator is an infix operator, -a syntax error is reported. - -Examples: - - say foo + 1; say(foo(+1)); - say foo $x; say(foo($x)); - say foo$x; ILLEGAL, need space or parens - say foo+1; ILLEGAL, need space or parens - - say foo($bar+1),$baz say(foo($bar+1), $baz); - say foo.($bar+1),$baz say(foo().($bar+1), $baz); - say foo ($bar+1),$baz say(foo($bar+1, $baz)); - say foo .($bar+1),$baz say(foo($_.($bar+1), $baz)); - - say foo[$bar+1],$baz say((foo()[$bar+1]), $baz); - say foo.[$bar+1],$baz say((foo()[$bar+1]), $baz); - say foo [$bar+1],$baz say(foo([$bar+1], $baz)); - say foo .[$bar+1],$baz say(foo($_.[$bar+1], $baz)); - - say foo{$bar+1},$baz say((foo(){$bar+1}), $baz); - say foo.{$bar+1},$baz say((foo(){$bar+1}), $baz); - say foo {$bar+1},$baz say(foo({$bar+1}, $baz)); - say foo .{$bar+1},$baz say(foo($_.{$bar+1}, $baz)); - - say foo<$bar+1>,$baz say(foo()<$bar+1>, $baz); - say foo.<$bar+1>,$baz say(foo()<$bar+1>, $baz); - say foo <$bar+1>,$baz say(foo(<$bar+1>, $baz)); - say foo .<$bar+1>,$baz say(foo($_.<$bar+1>, $baz)); - -Note that Perl 6 is making a consistent three-way distinction between -term vs postfix vs infix, and will interpret an overloaded character -like C<< < >> accordingly: - - any any('a','b','c') # term - any() (any).{'a','b','c'} # postfix - any() < $x (any) < $x # infix - any ILLEGAL # stealth postfix - -This will seem unfamiliar and "undwimmy" to Perl 5 programmers, who -are used to a grammar that sloppily hardwires a few postfix operators -at the price of extensibility. Perl 6 chooses instead to mandate a -whitespace dependency in order to gain a completely extensible class -of postfix operators. - -=item * - -A list operator's arguments are also terminated by a closure -that is not followed by a comma or colon. (And a semicolon is implied -if the closure is the final thing on a line. Use an "unspace" to -suppress that.) This final closure may be followed by a postfix, -in which case the postfix is applied to the result of the entire -list operator. - -=item * - -A function predeclared with an empty signature is considered 0-ary -at run time but is still parsed as a list prefix operator, and looks -for a following argument list, which it may reject at run time. - - my sub foo () {...}; - foo; # okay - foo(); # okay - foo (),(),(); # okay - foo 1; # fails to dispatch - -The compiler is allowed to complain about anything it knows cannot -succeed at run time. Note that a multi may contain () as one -of its signatures, however: - - my multi foo () {...}; - my multi foo ($x) {...}; - foo; # okay - foo(); # okay - foo (),(),(); # okay - foo 1; # okay - -To declare an item that is parsed as a simple term, you must use the -form C<< term: >>, or some other form of constant declaration such -as an enum declaration. Such a term never looks for its arguments, -is never considered a list prefix operator, and may not work with -subsequent parentheses because it will be parsed as a function call -instead of the intended term. (The function in question may or -may not exist.) For example, C is a simple term in Perl 6 -and does not allow parens, because there is no C function -(though there's a C<$n.rand> method). Most constant values such as -C and C are in the same category. After parsing one of these -the parser expects to see a postfix or an infix operator, not a term. -Therefore any attempt to use a simple value as a list operator is -destined to fail with an error indicating the parser saw two terms -in a row. - -For those values (such as types) that do respond to parentheses -(that is, that do the C role), the parentheses (parsed as -a postfix operator) are required in order to invoke the object: - - my $i = Int.($x); # okay - my $i = Int($x); # okay - my $i = Int $x; # ILLEGAL, two terms in a row - -=item * - -A non-multi sub predeclared with an arity of exactly 1 also still -parses as a list prefix operator expecting multiple arguments. You must explicitly use the form -C<< prefix: >> to declare C as a named unary in precedence; -it must still take a single positional parameter (though any number of -named parameters are allowed, which can be bound to adverbs). -All other subs with arguments parse as list operators. - -=back - -=head1 Junctive operators - -C<|>, C<&>, and C<^> are no longer bitwise operators (see -L) but now serve a much higher cause: -they are now the junction constructors. - -A junction is a single value that is equivalent to multiple values. They -thread through operations, returning another junction representing the -result: - - (1|2|3) + 4; # 5|6|7 - (1|2) + (3&4); # (4|5) & (5|6) - -As illustrated by the last example, when two junctions are applied -through a single operator, the result is a junction representing the -application of the operator to each possible combination of values. - -Junctions come with the functional variants C, C, C, and C. - -This opens doors for constructions like: - - if $roll == none(1..6) { print "Invalid roll" } - - if $roll == 1|2|3 { print "Low roll" } - -Junctions work through subscripting: - - doit() if @foo[any(1,2,3)] - -Junctions are specifically unordered. So if you say - - foo() | bar() | baz() == 42 - -it indicates to the compiler that there is no coupling between -the junctional arguments. They can be evaluated in any order or in -parallel. They can short-circuit as soon as any of them return 42, -and not run the others at all. Or if running in parallel, the first -successful thread may terminate the other threads abruptly. In general -you probably want to avoid code with side effects in junctions. - -Use of negative operators with junctions is potentially problematic if -autothreaded naively. However, by defining C and C in terms -of the negation metaoperator, we automatically get the "not raising" -that is expected by an English speaker. That is - - if $a != 1 | 2 | 3 {...} - -really means - - if $a ![==] 1 | 2 | 3 {...} - -which the metaoperator rewrites to a higher-order function resembling -something like: - - negate((* == *), $a, (1|2|3)); - -which ends up being equivalent to: - - if not $a == 1 | 2 | 3 {...} - -which is the semantics an English speaker expects. However, it may well -be better style to write the latter form yourself. - -Junctive methods on arrays, lists, and sets work just like the -corresponding list operators. However, junctive methods on a hash -make a junction of only the hash's keys. Use the listop form (or an -explicit C<.pairs>) to make a junction of pairs. - -The various operators for sets and bags (intersection, union, -etc.) also have junctive precedence (except for those that return C, -which are instead classified as chaining operators). - -=head1 Comparison semantics - -=over - -=item * - -Perl 5's comparison operators are basically unchanged, except that they -can be chained because their precedence is unified. - -=item * - -Binary C<===> tests immutable type and value correspondence: -for two value types (that is, immutable types), tests whether -they are the same value (eg. C<1 === 1>); for two mutable types -(object types), checks whether they have the same identity value. -(For most such types the identity is simply the reference itself.) -It is not true that C<[1,2] === [1,2]> because those are different -C objects, but it is true that C<@a === @a> because those are -the same C object). - -Any object type may pretend to be a value type by defining a C<.WHICH> -method which returns a value type that can be recursively compared -using C<===>, or in cases where that is impractical, by overloading -C<===> such that the comparison treats values consistently with their -"eternal" identity. (Strings are defined as values this way despite -also being objects.) - -Two values are never equivalent unless they are of exactly the same type. By -contrast, C always coerces to string, while C<==> always coerces to -numeric. In fact, C<$a eq $b> really means C<~$a === ~$b> and C<$a == $b> -means C<+$a === +$b>. - -Note also that, while string-keyed hashes use C semantics by default, -object-keyed hashes use C<===> semantics, and general value-keyed hashes -use C semantics. - -=item * - -Binary C tests equality much like C<===> does, but does -so with "snapshot" semantics rather than "eternal" semantics. For -top-level components of your value that are of immutable types, C -is identical in behavior to C<===>. For components of your value -that are mutable, however, rather than comparing object identity using -C<===>, the C operator tests whether the canonical representation -of both subvalues would be identical if we took a snapshot of them -right now and compared those (now-immutable) snapshots using C<===>. - -If that's not enough flexibility, there is also an C function -that can be passed additional information specifying how you want -canonical values to be generated before comparison. This gives -C the same kind of expressive power as a sort signature. -(And indeed, the C operator from Perl 5 also has a functional -analog, C, that takes additional instructions on how to -do 3-way comparisons of the kind that a sorting algorithm wants.) -In particular, a signature passed to C will be bound to the -two operands in question, and then the comparison will proceed -on the formal parameters according to the information contained -in the signature, so you can force numeric, string, natural, or -other comparisons with proper declarations of the parameter's type -and traits. If the signature doesn't match the operands, C -reverts to standard C comparison. (Likewise for C.) - -=item * - -Binary C is no longer the comparison operator that -forces stringification. Use the C operator for the old Perl 5 -C semantics. The C is just like the C above except that -instead of returning C or C values it always -returns C, C, or C -(which numerify to -1, 0, or +1). - -=item * - -The C operator (less than, equal to, or greater than) is defined -in terms of C, so C<$a leg $b> is now defined as C<~$a cmp ~$b>. -The sort operator still defaults to C rather than C. The -C<< <=> >> operator's semantics are unchanged except that it returns -an C value as described above. In other words, C<< $a <=> $b >> -is now equivalent to C<+$a cmp +$b>. - -=item * - -For boolean comparison operators with non-coercive C -semantics, use the generic C and C infix operators. -As ordinary infix operators these may be negated (C and C) -as well as reduced (C<[before]> and C<[after]>). - -=item * - -Infix C and C may be used to select one or the other -of their arguments. Reducing listop forms C<[min]> and C<[max]> are -also available, as are the C and C assignment operators. -By default C and C use C semantics. As with all C-based -operators, this may be modified by an adverb specifying different semantics. - -=item * - -Note that, like most other operators, a comparison naturally returns -failure if either of its arguments is undefined, and the general -policy on unthrown exceptions is that the exception is thrown as soon -as you try to use the exception as a real value. However, various -parallelizable contexts such as hyper (or other "mass production" -contexts such as sort) will pass through unthrown exceptions rather -than throwing them. - -=back - -=head1 Range and RangeIter semantics - -The C<..> range operator has variants with C<^> on either end to -indicate exclusion of that endpoint from the range. It always -produces a C object. Range objects are immutable, and primarily -used for matching intervals. C<1..2> is the interval from 1 to 2 -inclusive of the endpoints, whereas C<1^..^2> excludes the endpoints -but matches any real number in between. - -For numeric arguments of differing type, ranges coerce to the wider type, so: - - 1 .. 1.5 - -is taken to mean: - - 1.0 .. 1.5 - -These coercions are defined by multi signatures. (Other types may -have different coercion policies.) It is specifically illegal to -use a C as an endpoint: - - 0 ..^ 10 # 0 .. 9 - 0 .. ^10 # ERROR - -For ranges with other non-numeric types on the right, the right -argument is coerced to numeric and then used above. -Hence, C types in the second argument are assumed -to be intended as numeric if the left argument is numeric: - - 0 ..^ @x # okay - 0 ..^ +@x # same thing - -Likewise for strings: - - 0 .. '1.5' # okay - 0 .. +'1.5' # same thing - -C types are also supported to represent C<-Inf>/C<+Inf>. If -either endpoint is a C, the range is primed into -another C. - -For other types, ranges may be composed for any two arguments -of the same type, if the type itself supports it. That is, -in general, C<< infix:<..>:(::T Any $x, T $y) >> is defined such that, -if type C defines generic comparison (that is, by defining -C<< infix: >> or equivalent), a range is constructed in that type. -If C also defines C<.succ>, then the range may be iterated. -(Otherwise the range may only be used as an interval, and will return -failure if asked for a C.) Note that it is not necessary -to define a range multimethod in type C, since the generic -routine can usually auto-generate the range for you. - -Range objects support C<.min> and C<.max> methods representing -their left and right arguments. The C<.bounds> method returns both -values as a two-element list representing the interval. Ranges are -not autoreversing: C<2..1> is always a null range. (The sequence -operator C<...> can autoreverse, however. See below.) - -Range objects support C<.excludes-min> and C<.excludes-max> methods -representing the exclusion (has C<^>) or inclusion (no C<^>) of each -endpoint in the C. - - Range | .min | .max | .excludes-min | .excludes-max - -----------+------+------+---------------+------------ - 1..10 | 1 | 10 | Bool::False | Bool::False - 2.7..^9.3 | 2.7 | 9.3 | Bool::False | Bool::True - 'a'^..'z' | 'a' | 'z' | Bool::True | Bool::False - 1^..^10 | 1 | 10 | Bool::True | Bool::True - -If used in a list context, a C object returns an iterator that -produces a sequence of values starting at the min and ending at the max. -Either endpoint may be excluded using C<^>. Hence C<1..2> produces -C<(1,2)> but C<1^..^2> is equivalent to C<2..1> and produces no values, like C<()> does. -To specify a sequence that counts down, use a reverse: - - reverse 1..2 - reverse 'a'..'z' - -Alternately, for numeric sequences, you can use the sequence operator instead -of the range operator: - - 100,99,98 ... 0 - 100, *-1 ... 0 # same thing - -In other words, any C used as a list assumes C<.succ> semantics, -never C<.pred> semantics. No other increment is allowed; if you wish -to increment a numeric sequence by some number other than 1, you must -use the C<...> sequence operator. - - 0, *+0.1 ... 100 # 0, 0.1, 0.2, 0.3 ... 100 - -A C may be iterated only if the type in question supports the C<.succ> method. -If it does not, any attempt to iterate returns failure. - -Smart matching against a C object does comparisons -(by coercion, if necessary) in the C domain -if either endpoint does C. Otherwise comparison is in -the C domain if either argument does C. -Otherwise the min's type is used if it defines ordering, or if not, -the max's type. If neither min nor max have an ordering, -dispatch to C<.ACCEPTS> fails. It may also fail if the ordering -in question does not have any way to coerce the object -being smartmatched into an appropriate type implied by the -chosen domain of ordering. - -In general, the domain of comparison should be a type that can -represent all the values in question, if possible. Hence, since C -is not such a type, it is promoted to a C, so fractional numbers -are I truncated before comparison to integer ranges. Instead the -integers are assumed to represent points on the real number line: - - 1.5 ~~ 1^..^2 # true, equivalent to 1 < 1.5 < 2 - 2.1 ~~ 1..2 # false, equivalent to 1 <= 2.1 <= 2 - -If a C<*> (see the "Whatever" type in L) occurs on the right side -of a range, it is taken to mean "positive infinity" in whatever -typespace the range is operating, as inferred from the left operand. -A C<*> on the left means "negative infinity" for types that support -negative values, and the first value in the typespace otherwise as -inferred from the right operand. - - 0..* # 0 .. +Inf - 'a'..* # 'a' le $_ - *..0 # -Inf .. 0 - *..* # -Inf .. +Inf - v1.2.3 .. * # Any version higher than 1.2.3. - May .. * # May through December - -An empty range cannot be iterated; it returns C<()> instead. An empty -range still has a defined C<.min> and C<.max>, but one of the following is -true: 1. The C<.min> is greater than the C<.max>. 2. The C<.min> is equal -to the C<.max> I at least one of C<.excludes-min> or C<.excludes-max> is true. -3. Both C<.excludes-min> and C<.excludes-max> are true I C<.min> and C<.max> -are consecutive values in a discrete type that cannot create new -values between those two consecutive values. For this purpose, -interval representations in C (including integers) are -considered infinitely divisible even though there is a practical -limit depending on the actual representation, so #3 does not apply. -(Nor does it apply to strings, versions, instants, or durations. -#3 does apply to enums, however, so C<< Tue ^..^ Wed >> is considered -empty because the enum in question does not define "Tuesday and a half".) - -An empty range evaluates to C in boolean context; all other -ranges evaluate to C. - -Ranges that are iterated transmute into the corresponding sequence -operator, using C<.succ> semantics to find the next value, and the -appropriate inequality semantics to determine an end to the sequence. -For a non-discrete type with a discrete C<.succ> (such as C), -it is possible to write a range that, when iterated, produces no -values, but evaluates to true, because the C<.succ> function skips -over divisible intervals: - - say +( 0 ^..^ 1 ) # 0 elements - say ?( 0 ^..^ 1 ) # True - say 0.5 ~~ 0 ^..^ 1 # True; range contains non-integer values - -=head2 Unary ranges - -The unary C<^> operator generates a range from C<0> up to -(but not including) its argument. So C<^4> is short for C<0..^4>. - - for ^4 { say $_ } # 0, 1, 2, 3 - -=head2 Auto-priming of ranges - -[This section is conjectural, and may be ignored for 6.0.] - -Since use of C objects in item context is usually -non-sensical, a C object used as an operand for scalar operators -will generally attempt to distribute the operator to its endpoints and -return another suitably modified C instead, much like a junction of two items, -only with proper interval semantics. (Notable exceptions to this autothreading -include C<< infix:<~~> >>, which does smart matching, and C<< prefix:<+> >> -which returns the length of the range.) Therefore if you wish to -write a slice using a length instead of an endpoint, you can say - - @foo[ start() + ^$len ] - -which is short for: - - @foo[ start() + (0..^$len) ] - -which is equivalent to something like: - - @foo[ list do { my $tmp = start(); $tmp ..^ $tmp+$len } ] - -In other words, operators of numeric and other ordered types are -generally overloaded to do something sensible on C objects. - -=head1 Chained comparisons - -Perl 6 supports the natural extension to the comparison operators, -allowing multiple operands: - - if 1 < $a < 100 { say "Good, you picked a number *between* 1 and 100." } - - if 3 < $roll <= 6 { print "High roll" } - - if 1 <= $roll1 == $roll2 <= 6 { print "Doubles!" } - -A chain of comparisons short-circuits if the first comparison fails: - - 1 > 2 > die("this is never reached"); - -Each argument in the chain will evaluate at most once: - - 1 > $x++ > 2 # $x increments exactly once - -Note: any operator beginning with C<< < >> must have whitespace -in front of it, or it will be interpreted as a hash subscript instead. - -=head1 Smart matching - -Here is the table of smart matches for standard Perl 6 -(that is, the dialect of Perl in effect at the start of your -compilation unit). Smart matching is generally done on the current -"topic", that is, on C<$_>. In the table below, C<$_> represents the -left side of the C<~~> operator, or the argument to a C, -or to any other topicalizer. C represents the pattern to be -matched against on the right side of C<~~>, or after a C. -(And, in fact, the C<~~> operator works as a small topicalizer; that is, -it binds C<$_> to the value of the left side for the evaluation -of the right side. Use the underlying C<.ACCEPTS> form to avoid -this topicalization.) - -The first section contains privileged syntax; if a match can be done -via one of those entries, it will be. These special syntaxes are -dispatched by their form rather than their type. Otherwise the rest -of the table is used, and the match will be dispatched according to -the normal method dispatch rules. The optimizer is allowed to assume -that no additional match operators are defined after compile time, -so if the pattern types are evident at compile time, the jump table -can be optimized. However, the syntax of this part of the table -is still somewhat privileged, insofar as the C<~~> operator is one -of the few operators in Perl that does not use multiple dispatch. -Instead, type-based smart matches singly dispatch to an underlying -method belonging to the C pattern object. - -In other words, smart matches are dispatched first on the basis of the -pattern's form or type (the C below), and then that pattern itself -decides whether and how to pay attention to the type of the topic -(C<$_>). So the second column below is really the primary column. -The C entries in the first column indicate a pattern that either -doesn't care about the type of the topic, or that picks that entry -as a default because the more specific types listed above it didn't match. - - $_ X Type of Match Implied Match if (given $_) - ====== ===== ===================== =================== - Any True ~~ True (parsewarn on literal token) - Any False ~~ False match (parsewarn on literal token) - Any Match ~~ Successful match (parsewarn on literal token) - Any Nil ~~ Benign failure (parsewarn on literal token) - Any Failure Failure type check (okay, matches against type) - Any * block signature match block successfully binds to |$_ - - Any Callable:($) item sub truth X($_) - Any Callable:() simple closure truth X() (ignoring $_) - Any Bool simple truth X (treats Bool value as success/failure) - Positional List lists are comparable $_ »~~« X (but dwims ** wildcards!) - Any Match match success X (treats Match value as success) - Any Nil benign failure X (treats Nil value as failure) - Any Failure malign failure X (passes Failure object through) - Any Numeric numeric equality +$_ == X - Any Stringy string equality ~$_ eq X - Any Whatever always matches True - - Associative Pair test hash mapping $_{X.key} ~~ X.value - Any Pair test object attribute ?."{X.key}" === ?X.value (e.g. filetests) - - Set Set identical sets $_ === X - Any Setty force set comparison $_.Set === X.Set - - Bag Bag identical bags $_ === X - Any Baggy force bag comparison $_.Bag === X.Bag - - Mix Mix identical bags $_ === X - Any Mixy force mix comparison $_.Mix === X.Mix - - Associative Array keys/list are comparable +X == +$_ and $_{X.all}:exists - Callable Positional list vs predicate so $_(X) - Any Positional lists are comparable $_[] «===» X[] - - Hash Hash hash mapping equivalent $_ eqv X - Associative Hash force hash comparison $_.Hash eqv X - Callable Hash hash vs predicate so $_(X) - Positional Hash attempted any/all FAIL, point user to [].any and [].all for LHS - Pair Hash hash does mapping X{.key} ~~ .value - Any Hash hash contains object X{$_}:exists - - Str Regex string pattern match .match(X) - Associative Regex attempted reverse dwim FAIL, point user to any/all vs keys/values/pairs - Positional Regex attempted any/all/cat FAIL, point user to any/all/cat/join for LHS - Any Regex pattern match .match(X) - - Range Range subset range !$_ or .bounds.all ~~ X (mod ^'s) - Any Range in real range X.min <= $_ <= X.max (mod ^'s) - Any Range in stringy range X.min le $_ le X.max (mod ^'s) - Any Range in generic range [!after] X.min,$_,X.max (etc.) - - Any Type type membership $_.does(X) - - Signature Signature sig compatibility $_ is a subset of X ??? - Callable Signature sig compatibility $_.sig is a subset of X ??? - Capture Signature parameters bindable $_ could bind to X (doesn't!) - Any Signature parameters bindable |$_ could bind to X (doesn't!) - - Signature Capture parameters bindable X could bind to $_ - - Any Any scalars are identical $_ === X - -The final rule is applied only if no other pattern type claims X. - -All smartmatch types are "itemized"; both C<~~> and C/C -provide item contexts to their arguments, and autothread any -junctive matches so that the eventual dispatch to C<.ACCEPTS> never -sees anything "plural". So both C<$_> and C above are potentially -container objects that are treated as scalars. (You may hyperize -C<~~> explicitly, though. In this case all smartmatching is done -using the type-based dispatch to C<.ACCEPTS>, not the form-based -dispatch at the front of the table.) - -The exact form of the underlying type-based method dispatch is: - - X.ACCEPTS($_) - -As a single dispatch call this pays attention only to the type of -C initially. The C method interface is defined by the -C role. Any class composing the C role may choose -to provide a single C method to handle everything, which -corresponds to those pattern types that have only one entry with -an C on the left above. Or the class may choose to provide -multiple C multi-methods within the class, and these -will then redispatch within the class based on the type of C<$_>. - -The smartmatch table is primarily intended to reflect forms and types that -are recognized at compile time. To avoid an explosion of entries, -the table assumes the following types will behave similarly: - - Actual type Use entries for - =========== =============== - Iterator Array List - named values created with - Class, Enum, or Role, - or generic type binding Type - Cat Str - Int UInt etc. Num - Buf Str or Array of Int - -(Note, however, that these mappings can be overridden by explicit -definition of the appropriate C methods. -If the redefinition occurs at compile time prior to analysis of the -smart match then the information is also available to the optimizer.) - -A C type containing any bytes or integers outside the ASCII -range may silently promote to a C type for pattern matching if -and only if its relationship to Unicode is clearly declared or typed. -This type information might come from an input filehandle, or the -C role may be a parametric type that allows you to instantiate -buffers with various known encodings. In the absence of such typing -information, you may still do pattern matching against the buffer, but -(apart from assuming the lowest 7 bits represent ASCII) any attempt -to treat the buffer as other than a sequence of integers is erroneous, -and warnings may be generously issued. - -Matching against a C treats the grammar as a typename, -not as a grammar. You need to use the C<.parse> or C<.parsefile> -methods to invoke a grammar. - -Matching against a C does not actually bind any variables, -but only tests to see if the signature I bind. To really bind -to a signature, use the C<*> pattern to delegate binding to the C -statement's block instead. Matching against C<*> is special in that -it takes its truth from whether the subsequent block is bound against -the topic, so you can do ordered signature matching: - - given $capture { - when * -> Int $a, Str $b { ... } - when * -> Str $a, Int $b { ... } - when * -> $a, $b { ... } - when * { ... } - } - -This can be useful when the unordered semantics of multiple dispatch -are insufficient for defining the "pecking order" of code. Note that -you can bind to either a bare block or a pointy block. Binding to a -bare block conveniently leaves the topic in C<$_>, so the final form -above is equivalent to a C. (Placeholder parameters may -also be used in the bare block form, though of course their types -cannot be specified that way.) - -There is no pattern matching defined for the C pattern, so if you -find yourself in the situation of wanting a reversed smartmatch test -with an C on the right, you can almost always get it by an explicit -call to the underlying C method using C<$_> as the pattern. -For example: - - $_ X Type of Match Wanted What to use on the right - ====== === ==================== ======================== - Callable Any item sub truth .ACCEPTS(X) or .(X) - Range Any in range .ACCEPTS(X) - Type Any type membership .ACCEPTS(X) or .does(X) - Regex Any pattern match .ACCEPTS(X) - etc. - -Similar tricks will allow you to bend the default matching rules for -composite objects as long as you start with a dotted method on C<$_>: - - given $somethingordered { - when .values.'[<=]' { say "increasing" } - when .values.'[>=]' { say "decreasing" } - } - -In a pinch you can define a macro to do the "reversed when": - - my macro statement_control: () { "when .ACCEPTS: " } - given $pattern { - ACCEPTS $a { ... } - ACCEPTS $b { ... } - ACCEPTS $c { ... } - } - -Various proposed-but-deprecated smartmatch behaviors may be easily -(and we hope, more readably) emulated as follows: - - $_ X Type of Match Wanted What to use on the right - ====== === ==================== ======================== - Array Num array element truth .[X] - Array Num array contains number *,X,* - Array Str array contains string *,X,* - Array List array begins /w List X,* - Array List array contains List *,X,* - Array List array ends with List *,X - Hash Str hash element truth .{X} - Hash Str hash key existence .{X}:exists - Hash Num hash element truth .{X} - Hash Num hash key existence .{X}:exists - Buf Int buffer contains int .match(X) - Str Str string contains string .match(X) - Array Scalar array contains item .any === X - Str Array array contains string X.any - Num Array array contains number X.any - Scalar Array array contains object X.any - Hash Array hash slice exists .{X.all}:exists .{X.any}:exists - Set Set subset relation .{X.all}:exists - Set Hash subset relation .{X.all}:exists - Any Set subset relation .Set.{X.all}:exists - Any Hash subset relation .Set.{X.all}:exists - Any Set superset relation X.{.all}:exists - Any Hash superset relation X.{.all}:exists - Any Set sets intersect .{X.any}:exists - Set Array subset relation X,* # (conjectured) - Array Regex match array as string .Cat.match(X) cat(@$_).match(X) - -(Note that the C<.cat> method and the C type coercion both take a -single object, unlike the C function which, as a list operator, -takes a syntactic list (or multilist) and flattens it. All of these -return a C object, however.) - -Boolean expressions are those known to return a boolean value, such -as comparisons, or the unary C operator. They may reference C<$_> -explicitly or implicitly. If they don't reference C<$_> at all, that's -okay too--in that case you're just using the switch structure as a more -readable alternative to a string of elsifs. Note, however, that this means -you can't write: - - given $boolean { - when True {...} - when False {...} - } - -because it will always choose the C case. Instead use something like -a conditional context uses internally: - - given $boolean { - when .Bool == 1 {...} - when .Bool == 0 {...} - } - -Better, just use an C statement. In any case, if you try to smartmatch -with C<~~> or C, it will recognize C or C syntactically -and warn you that it won't do what you expect. The compiler is also allowed -to warn about any other boolean construct that does not test C<$_>, to the -extent it can detect that. - -In a similar vein, any function (such as C) that takes a -C will not accept an argument of type C, since that -almost always indicates a programming error. (One may always use -C<*> to match anything, if that's what you really want. Or use a closure -that returns a constant boolean value.) - -Note also that regex matching does I return a C, but merely -a C object (or a C) that can be used as a boolean value. Use an explicit -C or C to force a C value if desired. A C object -represents a successful match and is treated by smartmatching the same as a C, -Similarly, a C represents a failure, and cannot be used directly on the -right side of a smartmatch. Test for definedness instead, or use C<* === Nil>. - -Regex matches with modifiers such as C<:g> that wish to return multiple -matches do so using a C. As with any list, the value evaluates -to true if there are 1 or more entries. If there are no matches, an -empty list is returned, which evaluates to false in a Boolean context. - -For the purpose of smartmatching, all C, C, and C -values are considered equivalent to the corresponding hash type, -C, C, and C, that is, C containers -where the keys represent the unique objects and the values represent -the replication count of those unique keys. (Obviously, a C can -have only 0 or 1 replication because of the guarantee of uniqueness). -So all of these C types only compare keys, not values. Use C -instead to test the equivalence of both keys and values. - -Despite the need for an implementation to examine the bounds of a -range in order to perform smartmatching, the result of smartmatching -two C objects is not actually defined in terms of bounds, but -rather as a subset relationship between two (potentially infinite) sets -of values encompassed by the intervals involved, for any orderable -type such as real numbers, strings, or versions. The result is -defined as true if and only if all potential elements that would -be matched by the left range are also matched by the right range. -Hence it does not matter to what extent the bounds of an empty range -are "overspecified". If the left range is empty, it always matches, -because there exists no value to falsify it. If the right range is -empty, it can match only if the left range is also empty. - -The C type allows you to have an infinitely extensible string. -You can match an array or iterator by feeding it to a C, -which is essentially a C interface over an iterator of some sort. -Then a C can be used against it as if it were an ordinary -string. The C engine can ask the string if it has more -characters, and the string will extend itself if possible from its -underlying iterator. (Note that such strings have an indefinite -number of characters, so if you use C<.*> in your pattern, or if you -ask the string how many characters it has in it, or if you even print -the whole string, it may feel compelled to slurp in the rest of -the string, which may or may not be expeditious.) - -The C operator takes a (potentially lazy) list and returns a -C object. In string context this coerces each of its elements -to strings lazily, and behaves as a string of indeterminate length. -You can search a gather like this: - - my $lazystr := cat gather for @foo { take .bar } - - $lazystr ~~ /pattern/; - -The C interface allows the regex to match element boundaries -with the C<< <,> >> assertion, and the C objects provide a way -to get both the element's index and the position within that list element. -If the underlying data structure is a mutable array, changes to the array -(such as by C or C) are tracked by the C so that the element -numbers remain correct. Strings, arrays, lists, sequences, captures, and -tree nodes can all be pattern matched by regexes or by signatures more or -less interchangeably. - -=head1 Invocant marker - -An appended C<:> marks the invocant when using the indirect-object -syntax for Perl 6 method calls. The following two statements are -equivalent: - - $hacker.feed('Pizza and cola'); - feed $hacker: 'Pizza and cola'; - -A colon may also be used on an ordinary method call to indicate that -it should be parsed as a list operator: - - $hacker.feed: 'Pizza and cola'; - -This colon is a separate token. A colon prefixing an adverb is not -a separate token. Therefore, under the longest-token rule, - - $hacker.feed:xxx('Pizza and cola'); - -is tokenized as an adverb applying to the method as its "toplevel preceding operator": - - $hacker.feed :xxx('Pizza and cola'); - -not as an xxx sub in the argument list of .feed: - - $hacker.feed: xxx('Pizza and cola'); # wrong - -If you want both meanings of colon in order to supply both an adverb -and some positional arguments, you have to put the colon twice: - - $hacker.feed: :xxx('Pizza and cola'), 1,2,3; - -(For similar reasons it's required to put whitespace after the colon of a label.) - -Note in particular that because of adverbial precedence: - - 1 + $hacker.feed :xxx('Pizza and cola'); - -will apply the C<:xxx> adverb to the C<+> operator, not the method call. -This is not likely to succeed. - -=head1 Feed operators - -The new operators C<< ==> >> and C<< <== >> are akin to UNIX pipes, -but work with functions or statements that accept and return lists. -Since these lists are composed of discrete objects and not liquids, -we call these I operators rather than pipes. For example, - - @result = map { floor($^x / 2) }, - grep { /^ \d+ $/ }, - @data; - -can also now be written with rightward feeds as: - - @data ==> grep { /^ \d+ $/ } - ==> map { floor($^x / 2) } - ==> @result; - -or with leftward feeds as: - - @result <== map { floor($^x / 2) } - <== grep { /^ \d+ $/ } - <== @data; - -Either form more clearly indicates the flow of data. See L for -more of the (less-than-obvious) details on these two operators. - -=head1 Meta operators - -Perl 6's operators have been greatly regularized, for instance, by -consistently prefixing numeric, stringwise, and boolean operators -with C<+>, C<~> and C respectively to indicate whether the bitwise -operation is done on a number, a string, or a single bit. -But that's just a naming convention, and if you wanted to add a new -bitwise C<¬> operator, you'd have to add the C<+¬>, C<~¬>, and C -operators yourself. Similarly, the carets that exclude the endpoints -on ranges are there by convention only. - -In contrast to that, Perl 6 has eight standard metaoperators for -turning a given existing operator into a related operator that is -more powerful (or at least differently powerful). These differ from a -mere naming convention in that Perl automatically generates these new -operators from user-defined operators as well as from builtins. -In fact, you're not generally supposed to define the individual -metaoperations--their semantics are supposed to be self-evident by -the transformation of the base operator. In other words, these -metaoperators are really just shorthand for higher-order functions -(functions that take other functions as arguments). - -Constructs containing metaoperators are considered "metatokens", -by which we mean that they are not subject to ordinary longest-token -matching rules, although their components are. Like ordinary -tokens, however, metatokens do not allow whitespace between -their subparts. - -=head2 Assignment operators - -Assignment operators are already familiar to C and Perl programmers. (Though the -C<.=> operator now means to call a mutating method on the object on -the left, and C<~=> is string concatenation.) Most non-relational -infix operators may be turned into their corresponding assignment -operator by suffixing with C<=>. The limitation is actually based -on whether the left side can function both as an rvalue and an lvalue -by the usual correspondence: - - A op= B; - A = A op B; - -Existing forms ending in C<=> may not be modified with this metaoperator. - -Regardless of the precedence of the base operator, the precedence -of any assignment operator is forced to be the same as that of -ordinary assignment. If the base operator is tighter than comma, -the expression is parsed as item assignment. If the base operator is -the same or looser than comma, the expression is parsed as a list assignment: - - $a += 1, $b += 2 # two separate item assignments - @foo ,= 1,2,3 # same as push(@foo,1,2,3) - @foo Z= 1,2,3 # same as @foo = @foo Z 1,2,3 - -Note that metaassignment to a list does not automatically distribute -the right argument over the assigned list unless the base operator -does (as in the C case above). Hence if you want to say: - - ($a,$b,$c) += 1; # ILLEGAL - -you must instead use a hyperoperator (see below): - - ($a,$b,$c) »+=» 1; # add one to each of three variables - -If you apply an assignment operator to a container containing a type object -(which is undefined), it is assumed that -you are implementing some kind of notional "reduction" to an accumulator -variable. To that end, the operation is defined in terms -of the corresponding reduction operator, where the type object -autovivifies to the operator's identity value. So if you say: - - $x -= 1; - -it is more or less equivalent to: - - $x = [-]() unless defined $x; # 0 for [-]() - $x = $x - 1; - -and $x ends up with -1 in it, as expected. - -Hence you may correctly write: - - my Num $prod; - for @factors -> $f { - $prod *= $f; - } - -While this may seem marginally useful in the scalar variable case, -it's much more important for it to work this way when the modified -location may have only just been created by autovivification. In other -words, if you write: - - %prod{$key} *= $f - -you need not worry about whether the hash element exists yet. If it -does not, it will simply be initialized with the value of C<$f>. - -=head2 Negated relational operators - -Any infix relational operator returning type C may be transformed -into its negative by prefixing with C. A couple of these have -traditional shortcuts: - - Full form Shortcut - --------- -------- - !== != - !eq ne - -but most of them do not: - - !~~ - !< - !>= - !ge - !=== - !eqv - !=:= - -To avoid visual confusion with the C operator, you may not modify -any operator already beginning with C. - -The precedence of any negated operator is the same as the base operator. - -You may negate only those operators that return a C. Note that -logical operators such as C<||> and C<^^> do not return a C, -but rather one of the operands. - -=head2 Reversed operators - -Any infix operator may be called with its two arguments reversed -by prefixing with C. For instance, to do reversed comparisons: - - Rcmp - Rleg - R<=> - -The precedence of any reversed operator is the same as the base operator. -The associativity, however, is reversed, so - - [R-] 1,2,3 # produces 0 from 3 - 2 - 1 - [R**] 2,3,4 # produces 262144 from 4 ** 3 ** 2 - -Using both left and right associativity at the same precedence level is -not prohibited, but is likely to drive you mad, unless of course you were -mad in the first place, which seems almost a certainty by this point. - -=head2 Hyper operators - -The Unicode characters C<»> (C) and C<«> (C) and -their ASCII digraphs C<<< >> >>> and C<<< << >>> are used to denote a -"list operation" that operates on each element of its list (or array) -argument (or arguments) and returns a single list (or array) of -the results. In other words, a hyper operator evaluates its arguments in -item context but then distributes the operator over them as lists. - -When writing a hyper operator, spaces are not allowed on the inside, -that is, between any "hyper" marker and the operator it's modifying. -On the outside the spacing policy is the same as the base operator. -Likewise the precedence of any hyperoperator is the same as its -base operator. This means that you must parenthesize your comma -lists for most operators. For example: - - -« (1,2,3); # (-1, -2, -3) - (1,1,2,3,5) »+« (1,2,3,5,8); # (2,3,5,8,13) - -(If you find yourself doing this, ask yourself whether you are really -working with objects or lists; in the latter case, there may be other -metaoperators such as C or C that are more appropriate, and will not -require parens.) - -A unary hyper operator (either prefix or postfix) has only one -hyper marker, located on its argument side, while an infix operator -always has one on each side to indicate there are two arguments. - -=head3 Unary hyper operators - -The meaning of a unary hyper operator depends on whether the operator -is considered to be a structural dereferencing operator. Most operators -are not structural. - -=head4 Non-structural unary hyper operators - -Non-structural unary hyper operators produce a hash or array of exactly the -same shape as the single argument. The hyper will descend into nested -lists and hashes to distribute over the lower-level values just as they -distribute over the top-level values that are leaves in the tree. Non-structural -unary hypers do not care whether the nesting is achieved by declaration -in the case of shaped arrays, or by mere incorporation of sublists and subhashes -dynamically. In any case the operator is applied only to the leaves of the -structure. - -=head4 Structural unary hyper operators - -There are a few operators that are deemed to be structural, -however, and will produce counterintuitive results if treated as -ordinary operators. These include the dereferencing operators -such as subscripts, as well as any method whose least-derived -variant (or proto, in the case of a multi method) is declared -or autogenerated in a class derived from Iterable. Additionally, -structural methods include any method placed in class C with -the intent of treating items as lists of one item. So C<.elems> -is considered structural, but a C> that happens to call -C<.elems> internally is not considered structural. - -These operations are marked by declaring them with the C -property, which is available by inspection to the hyper controller -when it examines the function it was passed. (Hypers are just one -form of higher-order programming, after all, and functions are also -objects with properties.) So this declaration is to be placed on -the top-level declaration of the operator, a proto declaration when -there are multiple candidates, or the candidate itself when there is -only one candidate. If the C trait is declared, the hyper -controller will consider it to be structural. - -[Conjecture: we can assume C on methods declared -in a class that is C, to save having to mark every method -as nodal. Or we provide a pragma within a lexical scope that assumes -C, so we can use it inside C as well.] - -[Conjecture: we might revise this be a C role instead of -a trait, if the implementors decide that makes more sense.] - -For structural hypers, we never implicitly follow references to -substructures, since the operator itself wants to deal with the -structure. So these operators distribute only over the top level -of the structure. - -For arrays or hashes declared with a shape (see S09), this top level -may be multidimensional; unary hypers consider shaped arrays to really -be one-dimensional (and indeed, for compactly stored multidimensional -arrays, multidimensional subscripts can just be calculations into an -underlying linear representation, which can be optimized to run on -a GPU, so this makes implementational sense). - -If the item is not declared with a shape, only the top dimension -is mapped, equivalent to a normal C<.map> method. (To map deeper -dimensions than provided for by hypers, use the either C<.duckmap> -or C<.deepmap> method, depending on whether you want to give the item -mapping or the substructure first shot at each node.) - -=head3 Binary hyper operators - -In contrast to unary operators that allows for (a few) structural -operators, infix operators are never considered structural, so the -hyper infix controller will always consider the dynamic shape as -potentially traversable in addition to any static shape. That is, -it is allowed to follow references from any parent node to dynamically -nested structures. (Whether it actually follows a particular reference -depends on the relative shapes of the two arguments.) - -When infix operators are presented with two lists or arrays of -identical shape, a result of that same shape is produced. Otherwise -the result depends on how you write the hyper markers. - -For an infix operator, if either argument is insufficiently -dimensioned, Perl "upgrades" it, but only if you point the "sharp" end -of the hypermarker at it. - - (3,8,2,9,3,8) >>->> 1; # (2,7,1,8,2,7) - @array »+=» 42; # add 42 to each element - -In fact, an upgraded scalar is the only thing that will work for an -unordered type such as a C: - - Bag(3,8,2,9,3,8) >>->> 1; # Bag(2,7,1,8,2,7) === Bag(1,2,2,7,7,8) - -In other words, pointing the small end at an argument tells the hyperoperator -to "dwim" on that side. If you don't know whether one side or the other will -be underdimensioned, you can dwim on both sides: - - $left «*» $right - -[Note: if you are worried about Perl getting confused by something like this: - - func «*» - -then you shouldn't worry about it, because unlike previous versions, -Perl 6 never guesses whether the next thing is a term or operator. -In this case it is always expecting a term unless C is predeclared -to be a type or value name.] - -The upgrade never happens on the "blunt" end of a hyper. If you write - - $bigger «*« $smaller - $smaller »*» $bigger - -an exception is thrown, and if you write - - $foo »*« $bar - -you are requiring the shapes to be identical, or an exception will be thrown. - -For all hyper dwimminess, if a scalar is found where the other side expects a list, -the scalar is considered to be a list of one element repeated C<*> times. - -Once we have two lists to process, we have to decide how to put the elements -into correspondence. If both sides are dwimmy, the short list will have be repeated -as many times as necessary to make the appropriate number of elements. - -If only one side is dwimmy, then the list on that side only will be -grown or truncated to fit the list on the non-dwimmy side. - -Regardless of whether the dwim is forced or emergent from the shapes -of the arrays, once the side to dwim on has been chosen, the dwim -semantics on the dwimmy side are always: - - (@dwimmyside xx *).batch(@otherside.elems) - -This produces a list the same length as the corresponding dimension -on the other side. The original operator is then recursively applied -to each corresponding pair of elements, in case there are more dimensions -to handle. - -Here are some examples: - - (1,2,3,4) »+« (1,2) # always error - (1,2,3,4) «+» (1,2) # 2,4,4,6 rhs dwims to 1,2,1,2 - (1,2,3) «+» (1,2) # 2,4,4 rhs dwims to 1,2,1 - (1,2,3,4) «+« (1,2) # 2,4 lhs dwims to 1,2 - (1,2,3,4) »+» (1,2) # 2,4,4,6 rhs dwims to 1,2,1,2 - (1,2,3) »+» (1,2) # 2,4,4 rhs dwims to 1,2,1 - (1,2,3) »+» 1 # 2,3,4 rhs dwims to 1,1,1 - -Another way to look at it is that the dwimmy list's elements are -indexed modulo its number of elements so as to produce as many or as -few elements as necessary. - -Note that each element of a dwimmy list may in turn be expanded into -another dimension if necessary, so you can, for instance, add one to -all the elements of a matrix regardless of its dimensionality: - - @fancy »+=» 1 - -On the non-dwimmy side, any scalar value that does not know how to -do C will be treated as a list of one element, and for infix -operators must be matched by an equivalent one-element list on the -other side. That is, a hyper operator is guaranteed to degenerate -to the corresponding scalar operation when all its arguments are -non-list arguments. - -When using a unary operator, you always aim the blunt end at the -single operand, because no replicative dwimmery ever happens: - - @negatives = -« @positives; - - @positions»++; # Increment all positions - - @positions.»++; # Same thing, dot form - @positions».++; # Same thing, dot form - @positions.».++; # Same thing, dot form - @positions\ .»\ .++; # Same thing, unspace form - - @objects.».run(); - ("f","oo","bar").>>.chars; # (1,2,3) - -Note that method calls are really postfix operators, not infix, so you -shouldn't put a C<«> after the dot. - -Hyper operators are defined recursively on nested arrays, so: - - -« [[1, 2], 3] # [-«[1, 2], -«3] - # == [[-1, -2], -3] - -Likewise the dwimminess of dwimmy infixes propagates: - - [[1, 2], 3] «+» [4, [5, 6]] # [[1,2] «+» 4, 3 «+» [5, 6]] - # == [[5, 6], [8, 9]] - -More generally, a dwimmy hyper operator works recursively for any object -matching the C role even if the object itself doesn't support -the operator in question: - - Bag(3,8,[2,(9,3)],8) >>->> 1; # Bag(2,7,[1,(8,2)],7) - (3,8,[2,(9,3)],8) >>->> (1,1,2,1); # (2,7,[0,(7,1)],7) - -In particular, tree node types with C semantics enable visitation: - - $node.».foo; - -which means something like: - - my $type = $node.WHAT; - $node.?foo // $type($node.map: { .».foo }) - -You are not allowed to define your own hyper operators, because they -are supposed to have consistent semantics derivable entirely from -the modified scalar operator. If you're looking for a mathematical -vector product, this isn't where you'll find it. A hyperoperator -is one of the ways that you can promise to the optimizer that your -code is parallelizable. (The tree visitation above is allowed to -have side effects, but it is erroneous for the meaning of those side -effects to depend on the order of visitation in any way. Hyper tree -visitation is not required to follow DAG semantics, at least by default.) - -Even in the absence of hardware that can do parallel processing, -hyperoperators may be faster than the corresponding scalar operators -if they can factor out looping overhead to lower-level code, or -can apply loop-unrolling optimizations, or can factor out some or -all of the MMD dispatch overhead, based on the known types of the -operands (and also based on the fact that hyper operators promise -no interaction among the "iterations", whereas the corresponding -scalar operator in a loop cannot make the same promise unless all -the operations within the loop are known to be side-effect free.) - -In particular, infix hyperops on two C or C arrays need -only do a single MMD dispatch to find the correct function to call for -all pairs, and can further bypass any type-checking or type-coercion -entry points to such functions when there are known to be low-level -entry points of the appropriate type. (And similarly for unary C -or C ops.) - -Application-wide analysis of finalizable object types may also enable -such optimizations to be applied to C, C, and such. In the -absence of that, run-time analysis of partial MMD dispatch may save -some MMD searching overhead. Or particular object arrays might even -keep track of their own run-time type purity and cache partial MMD -dispatch tables when they know they're likely to be used in hyperops. - -Beyond all that, "array of scalar" types are known at compile time not to -need recursive hypers, so the operations can be vectorized aggressively. - -Hypers may be applied to hashes as well as to lists. In this case -"dwimminess" says whether to ignore keys that do not exist -in the other hash, while "non-dwimminess" says to use all keys that are -in either hash. That is, - - %foo «+» %bar; - -gives you the intersection of the keys, while - - %foo »+« %bar; - -gives you the union of the keys. Asymmetrical hypers are also useful; -for instance, if you say: - - %outer »+» %inner; - -only the C<%inner> keys that already exist in C<%outer> will occur in the result. -Note, however, that you want - - %outer »+=« %inner; - -in order to pass accumulated statistics up a tree, assuming you want C<%outer> -to have the union of keys. - -Unary hash hypers and binary hypers that have only one hash operand -will apply the hyper operator to just the values but return a new -hash value with the same set of keys as the original hash. - -For any kind of zip or dwimmy hyper operator, any list ending with C<*> -is assumed to be infinitely extensible by taking its final element -and replicating it: - - @array, * - -is short for something like: - - @array[0..^@array], @array[*-1] xx * - -Note that hypers promise that you don't care in what order the processing -happens, only that the resulting structure ends up in a form consistent -with the inputs. There is no promise from the system that the operation -I be parallelized. Effective parallelization requires some means -of partitioning the work without doing more extra work than you save. -This will differ from structure to structure. In particular, infinite -structures cannot be completely processed, and the system is allowed to -balance out the demands of laziness with parallel processing. For instance, -an algorithm that wants to divide a list into two equal sublists will not -work if you have to calculate the length in advance, since you can't always -calculate the length. Various approaches can be taken: handing off batches -to be processed in parallel on demand, or interleaving roundrobin with a -set of N processors, or whatever. In the limit, a simple, non-parallel, -item-by-item lazy implementation is within spec, but unlikely to use multiple -cores efficiently. Outside of performance requirements, if the algorithm -depends on which of these approaches is taken, it is erroneous. - -=head2 Reduction operators - -Any infix operator (except for non-associating operators) -can be surrounded by square brackets in term position to -create a list operator that reduces using that operation: - - [+] 1, 2, 3; # 1 + 2 + 3 = 6 - my @a = (5,6); - [*] @a; # 5 * 6 = 30 - -As with all the metaoperators, space is not allowed inside a metatoken. - -A reduction operator has the same precedence as a list prefix. In fact, -a reduction operator really is a list prefix, and is invoked as one. -Hence, you can implement a reduction operator in one of two ways. Either -you can write an explicit list operator: - - multi prefix:<[+]> (*@args) is default { - my $accum = 0; - while (@args) { - $accum += @args.shift(); - } - return $accum; - } - -or you can let the system autogenerate one for you based on the -corresponding infix operator, probably by priming: - - &prefix:<[*]> ::= &reduce.assuming(&infix:<*>, 1); - &prefix:<[**]> ::= &reducerev.assuming(&infix:<**>); - -If the reduction operator is defined separately from the infix operator, -it must associate the same way as the operator used: - - [-] 4, 3, 2; # 4-3-2 = (4-3)-2 = -1 - [**] 4, 3, 2; # 4**3**2 = 4**(3**2) = 262144 - -For list-associative operator (the ones with X in the precedence table), the -implementation must take into account the listiness of the arguments; that is, -if repeatedly applying a binary version of the operator would produce the -wrong results, then it cannot be implemented that way. For instance: - - [^^] $a, $b, $c; # means ($a ^^ $b ^^ $c), NOT (($a ^^ $b) ^^ $c) - -For chain-associative operators (like C<< < >>), all arguments are taken -together, just as if you had written it out explicitly: - - [<] 1, 3, 5; # 1 < 3 < 5 - -For list infix operators, flattening is not done on the input list, so -that multiple lists may be passed in as comma-separated arguments: - - [X~] (1,2), ; # 1,2 X~ - -If fewer than two arguments are given, a dispatch is still attempted -with whatever arguments are given, and it is up to the receiver of that -dispatch to deal with fewer than two arguments. Note that the default -list operator signature is the most general, so you are allowed to define -different ways to handle the one argument case depending on type: - - multi prefix:<[foo]> (Int $x) { 42 } - multi prefix:<[foo]> (Str $x) { fail "Can't foo a single Str" } - -However, the zero argument case cannot be defined this way, since there -is no type information to dispatch on. Operators that wish to specify an -identity value should do so by specifying a multi variant that takes zero -arguments: - - multi prefix:<[foo]> () { 0 } - -Among the builtin operators, C<[+]()> returns 0 and C<[*]()> returns 1, -for instance. - -By default, if there is one argument, the built-in reduce operators -return that one argument. However, this default doesn't make sense -for operators like C<< < >> that don't return the same type as they -take, so these kinds of operators overload the single-argument case -to return something more meaningful. To be consistent with chaining -semantics, all the comparison operators return C for 1 or 0 arguments. - -You can also make a reduce operator of the comma operator. This is just -the list operator form of the C<< circumfix:<[ ]> >> anonymous array composer: - - [1,2,3] # make new Array: 1,2,3 - [,] 1,2,3 # same thing - -Builtin reduce operators return the following identity values: - - [**]() # 1 (arguably nonsensical) - [*]() # 1 - [/]() # fail (reduce is nonsensical) - [%]() # fail (reduce is nonsensical) - [x]() # fail (reduce is nonsensical) - [xx]() # fail (reduce is nonsensical) - [+&]() # -1 (from +^0, the 2's complement in arbitrary precision) - [+<]() # fail (reduce is nonsensical) - [+>]() # fail (reduce is nonsensical) - [~&]() # fail (sensical but 1's length indeterminate) - [~<]() # fail (reduce is nonsensical) - [~>]() # fail (reduce is nonsensical) - [+]() # 0 - [-]() # 0 - [~]() # '' - [+|]() # 0 - [+^]() # 0 - [~|]() # '' (length indeterminate but 0's default) - [~^]() # '' (length indeterminate but 0's default) - [&]() # all() - [|]() # any() - [^]() # one() - [!==]() # Bool::True (also for 1 arg) - [==]() # Bool::True (also for 1 arg) - [before]() # Bool::True (also for 1 arg) - [after]() # Bool::True (also for 1 arg) - [<]() # Bool::True (also for 1 arg) - [<=]() # Bool::True (also for 1 arg) - [>]() # Bool::True (also for 1 arg) - [>=]() # Bool::True (also for 1 arg) - [~~]() # Bool::True (also for 1 arg) - [!~~]() # Bool::True (also for 1 arg) - [eq]() # Bool::True (also for 1 arg) - [!eq]() # Bool::True (also for 1 arg) - [lt]() # Bool::True (also for 1 arg) - [le]() # Bool::True (also for 1 arg) - [gt]() # Bool::True (also for 1 arg) - [ge]() # Bool::True (also for 1 arg) - [=:=]() # Bool::True (also for 1 arg) - [!=:=]() # Bool::True (also for 1 arg) - [===]() # Bool::True (also for 1 arg) - [!===]() # Bool::True (also for 1 arg) - [eqv]() # Bool::True (also for 1 arg) - [!eqv]() # Bool::True (also for 1 arg) - [&&]() # Bool::True - [||]() # Bool::False - [^^]() # Bool::False - [//]() # Any - [min]() # +Inf - [max]() # -Inf - [=]() # Nil (same for all assignment operators) - [,]() # [] - [Z]() # [] - -User-defined operators may define their own identity values, but -there is no explicit identity property. The value is implicit in the -behavior of the 0-arg reduce, so mathematical code wishing to find -the identity value for an operation can call C -to discover it. - -To call some other non-infix function as a reduce operator, you may -define an alias in infix form. The infix form will parse the right -argument as an item even if the aliased function would have parsed it -as a list: - - &infix: ::= &postcircumfix:<{ }>; - $x = [dehash] $a,'foo','bar'; # $a, not $a - -Alternately, just define your own C<< prefix:<[dehash]> >> routine. - -Note that, because a reduce is a list operator, the argument list is -evaluated in list context. Therefore the following would be incorrect: - - $x = [dehash] %a,'foo','bar'; - -You'd instead have to say one of: - - $x = [dehash] \%a,'foo','bar'; - $x = [dehash] %a,'bar'; - -On the plus side, this works without a star: - - @args = (\%a,'foo','bar'); - $x = [dehash] @args; - -Likewise, from the fact that list context flattens inner arrays and -lists, it follows that a reduced assignment does no special syntactic -dwimmery, and hence only scalar assignments are supported. Therefore - - [=] $x, @y, $z, 0 - [+=] $x, @y, $z, 1 - -are equivalent to - - $x = @y[0] = @y[1] = @y[2] ... @y[*-1] = $z = 0 - $x += @y[0] += @y[1] += @y[2] ... @y[*-1] += $z += 1 - -rather than - - $x = @y = $z = 0; - $x += @y += $z += 1; - -(And, in fact, the latter are already easy to express anyway, -and more obviously nonsensical.) - -Similarly, list-associative operators that have the thunk-izing characteristics of -macros (such as short-circuit operators) lose those macro-like characteristics. -You can say - - [||] a(), b(), c(), d() - -to return the first true result, but the evaluation of the list is controlled -by the semantics of the list, not the semantics of C<||>. The operator still -short-circuits, but only in the sense that it does not need to examine all -the values returned by the list. This is still quite useful for performance, -especially if the list could be infinite. - -Most reduce operators return a simple scalar value, and hence do not care -whether they are evaluated in item or list context. However, as with -other list operators and functions, a reduce operator may return a list -that will automatically be interpolated into list context, so you may -use it on infix operators that operate over lists as well as scalars: - - my ($min, $max) = [minmax] @minmaxpairs; - -A variant of the reduction metaoperator is pretty much guaranteed -to produce a list; to lazily generate all intermediate results along -with the final result, you can backslash the operator: - - say [\+] 1..* # (1, 3, 6, 10, 15, ...) - -The visual picture of a triangle is not accidental. To produce a triangular -list of lists, you can use a "triangular comma": - - [\,] 1..5 - [1], - [1,2], - [1,2,3], - [1,2,3,4], - [1,2,3,4,5] - -If there is ambiguity between a triangular reduce and an infix operator -beginning with backslash, the infix operator is chosen, and an extra backslash -indicates the corresponding triangular reduce. As a consequence, defining an -infix operator beginning with backslash, C<< infix:<\x> >> say, would cause -C<[\x]> to mean the normal reduction of C<< infix:<\x> >>, not the triangular -reduction of C<< infix: >>. To disambiguate, the syntax C<[\[x]]> can be -used to reduce with C<< infix: >>, while C<[\\x]> or C<[\[\x]]> could be -used for triangular reduce with C<< infix:<\x> >>. - -Triangular reductions of chaining operators always consist of one or -more C values followed by 0 or more C values. - -=head2 Cross operators - -The cross metaoperator, C, may be followed by any infix operator. -It applies the modified operator across all groupings of its list -arguments as returned by the ordinary C<< infix: >> operator. -All generated cross operators are of list infix precedence, and are -list associative. - -The string concatenating form is: - - X~ 1,2 # 'a1', 'a2', 'b1', 'b2' - -The C operator desugars to: - - (; 1,2).crosswith(&[~]) - -which in turn means - - (; 1,2).cross.lol.map { .reduce(&[~]) } - -Note that - - X~ 1,2 X+ 3,4 - -could mean something like - - (; 1,2; 3,4).cross.lol.map { .reduce({$^a ~ $^b + $^c}) } - -but it is currently illegal as a non-identical list associative -operator, which is considered non-associative. You can, however, -always use parens to be explicit: - - X~ (1,2 X+ 3,4) - -The list concatenating form, C, when used like this: - - X, 1,2 X, - -produces - - ('a', 1, 'x'), - ('a', 1, 'y'), - ('a', 2, 'x'), - ('a', 2, 'y'), - ('b', 1, 'x'), - ('b', 1, 'y'), - ('b', 2, 'x'), - ('b', 2, 'y') - -The C operator is perhaps more clearly written as C. However, -this list form is common enough to have a shortcut, the ordinary infix -C operator described earlier. - -For the general form, any existing, non-mutating infix operator -may be used. - - 1,2 X* 3,4 # 3,4,6,8 - -(Note that C<< <== >> and C<< ==> >> are considered mutating, as well as -all assignment operators.) - -If the underlying operator is non-associating, so is the cross operator: - - @a Xcmp @b Xcmp @c # ILLEGAL - @a Xeq @b Xeq @c # ok - -In fact, though the C operators are all list associative -syntactically, the underlying operator is always applied with its -own associativity, just as the corresponding reduce operator would do. - -Note that only the first term of an C operator may reasonably be -an infinite list. - -All lists are assumed to be flat; multidimensional lists are -handled by treating the first dimension as the only dimension. - -=head2 Zip operators - -The zip metaoperator, C, may be followed by any infix operator. -It applies the modified operator across all groupings of its list -arguments as returned by the ordinary C<< infix: >> operator. -All generated zip operators are of list infix precedence, and are -list associative. - -The string concatenating form is: - - Z~ 1,2 # 'a1', 'b2' - -The C operator desugars to: - - (; 1,2).zipwith(&[~]) - -which in turn means - - (; 1,2).zip.lol.map: { .reduce(&[~]) } - -Note that - - Z~ 1,2 Z+ 3,4 - -could mean something like - - (; 1,2; 3,4).zip.lol.map: { .reduce({$^a ~ $^b + $^c}) } - -but it is currently illegal as a non-identical list associative -operator, which is considered non-associative. You can, however, -always use parens to be explicit: - - Z~ (1,2 Z+ 3,4) - -[Conjecture: another approach would involve giving C and C metaoperators a -subprecedence within listop precedence corresponding to the original -operator's precedence, so that C and C actually have different -precedences within listop precedence. Then the above would parse as if -you'd said C<< Z~ ( 1,2 Z+ 3,4> ) >>, but the lists would still -parse at list infix precedence, with comma tighter than the zips. -(This would actually be fairly trivial to implement, given how we -represent our precedence as strings.) Also, though it's complicated to -explain, subprecedence within C might be exactly what the naive user expects.] - -The list concatenating form, C, when used like this: - - Z, 1,2 Z, - -produces - - ('a', 1, 'x'), - ('b', 2, 'y') - -The C operator is perhaps more clearly written as C. However, -this list form is common enough to have a shortcut, the ordinary infix -C operator described earlier. - -For the general form, any existing, non-mutating infix operator -may be used. - - 1,2 Z* 3,4 # 3,8 - -(Note that C<< <== >> and C<< ==> >> are considered mutating, as well as -all assignment operators.) - -If the underlying operator is non-associating, so is the cross operator: - - @a Zcmp @b Zcmp @c # ILLEGAL - @a Zeq @b Zeq @c # ok - -In fact, though the C operators are all list associative -syntactically, the underlying operator is always applied with its -own associativity, just as the corresponding reduce operator would do. - -The zip operation terminates when either of its lists terminates. -(Do not use C or C to compare two arrays, for instance, -unless you want to know if one array is a prefix of the other. -Use C<»eq«> or C<»==«> for that. Or better, just use C.) - -Note that, unlike the C operator, all the terms of a C operator -may reasonably be infinite lists, since zipping is lazy. - -All lists are assumed to be flat; multidimensional lists are -handled by treating the first dimension as the only dimension. - -=head2 Sequential operators - -The sequence metaoperator, C, may be followed by any non-fiddly infix operator. -It suppresses any explicit or implicit parallelism, and prevents the optimizer -from reordering the operand evaluations. The 'S' can be thought of as standing -for Sequential, Serial, Synchronous, Short-circuit, Single-thread, and Safe. -Among other things. In particular, we can have: - - a S& b S& c short-circuited AND junction - a S| b S| c short-circuited OR junction - a S^ b S^ c short-circuited XOR junction - a S»op« b single-threaded hyperop - a SX* b single-threaded X* - a SX[*] b single-threaded X* - a S[X*] b single-threaded X* - a S+ b suppress arg reordering by ignorant optimizer - -This metaoperator has the same precedence and associativity as its base operator. -The compiler is free to discard any C metaoperator that is provably redundant, -such as the one in C. The compiler is free to intuit an C on any -operator involving known volatile operands where that does not otherwise -change the semantics of the operator. - -[Conjectural: since metaoperators are notionally applied from inside -to outside, the semantics of serializing and reversing depends on -the order of the metaoperators: - - a SR/ b evaluates b, then a, then does b/a - a RS/ b evaluates a, then b, then does b/a - a RSR/ b evaluates b, then a, then does a/b - -...maybe. Can argue it all the other way too...] - -=head2 Nesting of metaoperators - -Anywhere you may use an ordinary infix operator, you may use the infix operator enclosed in square brackets -with the same meaning. (No whitespace is allowed.) You may therefore use square brackets -within a metatoken to disambiguate sequences that might -otherwise be misinterpreted, or to force a particular order -of application when there are multiple metaoperators in the metatoken: - - @a [X+]= @b - @a X[+=] @b - -Since metatokens may never be disambiguated with internal whitespace, -use of brackets is especially useful when the operator and its -associated metaoperator share characters that would be confusing to the -reader, even if not to the compiler: - - @a >>>>> $b # huh? - @a >>[>]>> $b # oh yeah - -=head2 Turning an infix operator into a noun - -Any infix function may be referred to as a noun either by the normal long -form or a short form using square brackets directly after the C<&> sigil: - - &infix:<+> - &[+] - -This is convenient for function application: - - 1, 1, &[+] ... * # fibonacci sequence - sort &[Rleg], @list # reverse sort as strings - -The C<&[op]> form always refers to a binary function of the operator, -even if it is underlyingly defined as a variadic list-associative operator. - -There is no corresponding form for unary operators, but those may -usually be constructed by applying an operator to C<*>: - - sort -*, @list # sort reversed numerically - -=head2 Turning a binary function into an infix - -By using the noun form of a binary function inside square brackets, -it is possible to turn any function that accepts at least two arguments -into an infix operator. For instance: - - $y [&atan2] $x # same as atan2($y, $x) - -By itself this may seem relatively useless, but note that it allows -composition of normal 2-arg functions with all the infix metaoperators. -Since it is primarily intended for composition with metaoperators, -this form always assumes a binary function, even if the function could -accept more arguments; functions that accept more than 2 arguments do -not thereby accept multiple arguments on the right side. You must use -the normal functional form to pass three or more positional arguments. - -This form of operator is parsed with a precedence of addition. -The next character after C<&> must be either alphabetic or a left parenthesis. -Otherwise a normal infix operator starting with that character will -be assumed. Hence C<[&&]> parses as a form of the C<&&> operator. - -=head1 Declarators - -The list of variable declarators has expanded from C and C -to include: - - my $foo # ordinary lexically scoped variable - our $foo # lexically scoped alias to package variable - has $foo # object attribute - state $foo # persistent lexical (cloned with closures) - -Variable declarators such as C now take a I as their -argument. (The syntax of function signatures is described more fully in L.) - -The parentheses around the signature may be omitted for a -simple declaration that declares a single variable, along with its -associated type, traits and the initializer: - - my Dog $foo is woof = 123; # okay: initializes $foo to 123 - my (Dog $foo is woof = 123); # same thing (with explicit parens) - my :(Dog $foo is woof = 123); # same thing (full Signature form) - -The C declarator can declare either variables or names -as compile-time constants: - - constant $foo = 1; # compile-time constant variable - constant bar = 2; # compile-time constant symbol - -Because it can declare names in "type" space, the C -declarator may not declare using the signature, which would be -ambiguous. - -Each declarator can take an initializer following an equals -sign (which should not be confused with a normal assignment, because -the timing of the initialization depends on the natural lifetime of the -container, which in turn depends on which declarator you use). - - my $foo = 1; # happens at execute time, like normal assignment - our $foo = 1; # happens at INIT time - has $foo = 1; # happens at BUILD time - state $foo = 1; # happens at execute time, but only once - constant $foo = 1; # happens at BEGIN time - -(Note that the semantics of C are different from Perl 5, where the -initialization happens at the same time as a C. To get the same -effect in Perl 6 you'd have to say "C<(our $foo) = 1;>" instead.) - -If you do not initialize a container, it starts out undefined at the -beginning of its natural lifetime. (In other words, you can't use -the old Perl 5 trick of "C" to get a static variable, -because a C variable starts out uninitialized every time through -in Perl 6 rather than retaining its previous value.) Native integer -containers that do not support the concept of undefined should be -initialized to 0 instead. (Native floating-point containers are -by default initialized to C.) Typed object containers start -out containing an undefined type object of the correct type. - -List-context pseudo-assignment is supported for simple declarations but -not for signature defaults: - - my @foo = 1,2,3; # okay: initializes @foo to (1,2,3) - my (@foo = 1,2,3); # wrong: 2 and 3 are not variable names - -When parentheses are omitted, you may use any infix assignment operator -instead of C<=> as the initializer. In that case, the left hand side of -the infix operator will be the variable's prototype object: - - my Dog $fido .= new; # okay: a Dog object - my Dog $fido = Dog.new; # same thing - my Dog $fido = $fido.new; # okay: valid self-reference - my (Dog $fido .= new); # wrong: cannot use .= inside signature - -Note that very few mutating operators make sense on a type object, however, -since type objects are a kind of undefined object. (Those operators with -an identity value are an exception, as noted above.) - -Parentheses must always be used when declaring multiple parameters: - - my $a; # okay - my ($b, $c); # okay - my ($b = 1, $c = 2); # okay - "my" initializers assign at runtime - my $b, $c; # wrong: "Use of undeclared variable: $c" - -Types occurring between the declarator and the signature are distributed into -each variable: - - my Dog ($b, $c); - my (Dog $b, Dog $c); # same thing - -[XXX the following probably belongs in L.] -The syntax for constructing a C object when the parser isn't already -expecting one is: - - :(Dog $a, *@c) - -This might be used like this: - - my $sig = :(Dog $a, *@c); - -Signatures are expected after declarators such as C, C, C, -C, etc. In such declarators the colon may be omitted. But it's -also legal to use it: - - my :($b, $c); # okay - sub foo :($a,$b) {...} # okay - -The C<< -> >> "pointy block" token also introduces a signature, but -in this case you must omit both the colon and the parens. For instance, -if you're defining the "loop variable" of a loop block: - - for @dogpound -> Dog $fido { ... } - -If a signature is assigned to (whether declared or colon form), the -signature is converted to a list of lvalue variables and the ordinary -rules of assignment apply, except that the evaluation of the right -side and the assignment happens at time determined by the declarator. -(With C this is always when an ordinary assignment would happen.) -If the signature is too complicated to convert to an assignment, -a compile-time error occurs. Assignment to a signature makes the -same item/list distinction as ordinary assignment, so - - my $a = foo(); # foo in item context - my ($a) = foo(); # foo in list context - -If a signature is bound to an argument list, then the binding of the -arguments proceeds as if the signature were the formal parameters for -a function, except that, unlike in a function call, the parameters -are bound C by default rather than C. See Binding above. - -Note that C and C are I variable declarators, because -their effects only take place at runtime. Therefore, they take an ordinary -lvalue object as their argument. See L for more details. - -There are a number of other declarators that are not variable -declarators. These include both type declarators: - - package Foo - module Foo - class Foo - role Foo - subset Foo - enum Foo - constant Foo - -and code declarators: - - sub foo - method foo - submethod foo - multi foo - proto foo - macro foo - quote qX - regex foo - rule foo - token foo - -These all have their uses and are explained in subsequent Synopses. - -Note that since C is parsed as a type declarator (essentially -declaring a type with a single value), it can actually take a scope -declarator in front: - - my constant companion = 'Fido'; - has constant $.pi = 22/7; - state constant $latch = snapshot(); # careful with this! - -However, the constant declarator is intended to create values the -compiler can inline, so it always evaluates its value at C time. -Thus, while the extra scope declarator may say where the value is -stored and when that storage is initialized, it cannot change the value -of that from instance to instance. In general, if you want something -that doesn't vary over the normal lifetime of a scope declarator, -initialize it to a readonly value using C<::=> rather than declaring -it as a constant. Then each time the scope declarator is used, -it can initialize to a different readonly value: - - state $latch ::= snapshot(); # each clone gets its own value of $latch - -=head1 Argument List Interpolating - -Perl 5 forced interpolation of a function's argument list by use of -the C<&> prefix. That option is no longer available in Perl 6, so -instead the C<|> prefix operator serves as an -interpolator, by casting its operand to a C object -and inserting the capture's parts into the current argument list. -This operator can be used to interpolate an C or C -into the current call, as positional and named arguments respectively. - -Note that the resulting arguments still must comply with the subroutine's -signature, but the presence of C<|> defers that test until run time for -that argument (and for any subsequent arguments): - - my $args = \(@foo, @bar); - push |$args; - -is equivalent to: - - push @foo, @bar; - -However, - - my $args = \(@foo: @bar); - push |$args; - -is instead equivalent to: - - @foo.push(@bar); - -C<|> does not turn its argument into an C, but instead directly -converts its argument into a C: - - my @args = \$x, 1, 2, 3; - say |@args; # say(\$x, 1, 2, 3); - -Because of this, C<|%args> always produces named arguments, and -C<|@args> always produces positional arguments. - -In list context, a C holding an C object does not flatten. Hence - - $bar = @bar; - @foo.push($bar); - -merely pushes a single C object onto C<@foo>. You can -explicitly flatten it in one of these ways: - - @foo.push(@$bar); - @foo.push($bar[]); - @foo.push(|$bar); - -Those three forms work because the slurpy array in C's signature -flattens the C object into a list argument. - -Note that the first two forms also allow you to specify list context on -assignment: - - @$bar = 1,2,3; - $bar[] = 1,2,3; - -For long expressions that need to be cast to an array lvalue, the -second form can keep the "arrayness" of the lvalue close to the -assignment operator: - - $foo.bar.baz.bletch.whatever.attr[] = 1,2,3; - -The empty C<[]> and C<.[]> postfix operators are interpreted as a -zero-dimensional subscript returning the entire array, not as a one-dimensional -null slice returning no elements. Likewise for C<{}> and C<.{}> on hashes, -as well as the C<< <> >>, C<< .<> >>, C<«»>, and C<.«»> constant and -interpolating slice subscripting forms. - -The C<|> operator interpolates lazily for C and C objects. -To get an immediate interpolation like Perl 5 does, add the C list -operator: - - func(|(1..Inf)); # works fine - func(|eager 1..Inf); # never terminates (well, actually...) - -To interpolate a function's return value, you can say: - - push |func(); - -Within such an argument list, function return values are -automatically exploded into their various parts, as if you'd said: - - my $capture = \(func()); - push $$capture: @$capture, %$capture; - -or some such. The C<|> then handles the various zones appropriately -depending on the context. An invocant only makes sense as the first -argument to the outer function call. An invocant inserted anywhere -else just becomes a positional argument at the front of its list, -as if its colon changed back to a comma. - -If you already have a capture variable, you can interpolate all of -its bits at once using the C<< prefix:<|> >> operator: - - my (|$capture) := func(); - push |$capture; - -=head1 Traversing arrays in parallel - -In order to support parallel iteration over multiple arrays, Perl 6 -has a C function that builds a list of C objects from the -elements of two or more arrays. In ordinary list context this behaves -as a list of C and automatically flattens. - - for zip(@names; @codes) -> $name, $zip { - print "Name: $name; Zip code: $zip\n"; - } - -C has an infix synonym, the C operator. - -In an explicitly multidimensional list context, however, the sequences -turn into subarrays, and each element would then have to be unpacked -by the signature: - - for lol(zip(@names; @codes)) -> [$name, $zip] { - print "Name: $name; Zip code: $zip\n"; - } - -By default the C function reads to the end of the shortest list, -but a short list may always be extended arbitrarily by putting C<*> -after the final value, which replicates the final value as many times -as necessary. If instead of supplying a default value for short lists, -you just wish to skip missing entries, use C instead: - - for roundrobin(@queue1; @queue2; @queue3) -> $next { - ... - } - -=head1 Minimal whitespace DWIMmery - -Whitespace is no longer allowed before the opening bracket of an array -or hash subscript, or the opening parenthesis of an argument list. That is: - - @deadbeef[$x] # okay - @a [$b] # WRONG - %monsters{'cookie'} # okay - %people {'john'} # WRONG - saymewant('cookie') # okay - mewant ('cookie') # WRONG - -One of the several useful side-effects of this restriction is that -parentheses are no longer required around the condition of control -constructs: - - if $value eq $target { - print "Bullseye!"; - } - while $i < 10 { $i++ } - -It is, however, still possible to align subscripts and other postfix -operators by explicitly using the I syntax (see L): - - %squirrels{'fluffy'} = Squirrel.new; - %monsters.{'cookie'} = Monster.new; - %beatles\.{'ringo'} = Beatle.new; - %people\ .{'john'} = Person.new; - -Whitespace is in general required between any keyword and any opening -bracket that is I introducing a subscript or function arguments. -Any keyword followed directly by parentheses will be taken as a -function call instead. - - if $a == 1 { say "yes" } # preferred syntax - if ($a == 1) { say "yes" } # P5-ish if construct - if($a,$b,$c) # if function call - -It is possible for C to also invoke a macro call, but if so, it's a -C<< prefix: >> macro rather than a C<< statement_control: >> macro. - -=head1 Sequence points - -Certain operators are guaranteed to provide I. -Sequence points are guaranteed whenever some thunk (a lazy chunk of code) is -conditionally evaluated based on the result of some other evaluation, -so the short-circuit and conditional operators all provide sequence -points. - -Certain other operators guarantee the I of sequence points, -including junctional operators, hyperoperators, and feed operators. -These operators promise the compiler that you consider the bits of -code not to be dependent on each other so that they can operate -in parallel if they like. - -A large number of operators (such as C<+>) are stuck in the middle, -and may exhibit sequential behavior today, but might not tomorrow. -A program that relies on either sequential or parallel behavior for one -of these operators is erroneous. As we get more feedback from people -writing parallelizing optimizers, we reserve the right to classify -various of the unclassified operators into one of the two specified -sets. (We need to give these three sets of operators good names.) - -=head1 Non-declarative metaoperator names - -When a metaoperator is mentioned non-declaratively, such as in -C<&[Rop]>, C<< &infix: >>, or C<< prefix:<[op]>(@list) >>, if the -metaoperator name lookup fails, the operator is automatically generated -just as if the metaoperator had been used in its normal location. - -=head1 AUTHORS - - Luke Palmer - Larry Wall - Darren Duncan - Elizabeth Mattijsen - -=for vim:set expandtab sw=4: diff --git a/S04-control.pod b/S04-control.pod deleted file mode 100644 index e336566f..00000000 --- a/S04-control.pod +++ /dev/null @@ -1,1888 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 4: Blocks and Statements - -=head1 VERSION - - Created: 19 Aug 2004 - - Last Modified: 16 Oct 2015 - Version: 141 - -This document summarizes Apocalypse 4, which covers the block and -statement syntax of Perl. - -=head1 The Relationship of Lexical and Dynamic Scopes - -Control flow is a dynamic feature of all computer programming languages, but -languages differ in the extent to which control flow is attached to -declarative features of the language, which are often known as "static" or -"lexical". We use the phrase "lexical scoping" in its industry-standard -meaning to indicate those blocks that surround the current textual location. -More abstractly, any declarations associated with those textual blocks are -also considered to be part of the lexical scope, and this is where the term -earns the "lexical" part of its name, in the sense that lexical scoping -actually does define the "lexicon" for the current chunk of code, insofar as -the definitions of variables and routines create a local domain-specific -language. - -We also use the term "dynamic scoping" in the standard fashion to indicate -the nested call frames that are created and destroyed every time a function -or method is called. In most interesting programs the dynamic scopes are -nested quite differently from the lexical scopes, so it's important to -distinguish carefully which kind of scoping we're talking about. - -Further compounding the difficulty is that every dynamic scope's outer call -frame is associated with a lexical scope somewhere, so you can't just -consider one kind of scoping or the other in isolation. Many constructs -define a particular interplay of lexical and dynamic features. For -instance, unlike normal lexically scope variables, dynamic variables search -up the dynamic call stack for a variable of a particular name, but at each -"stop" along the way, they are actually looking in the lexical "pad" -associated with that particular dynamic scope's call frame. - -In Perl 6, control flow is designed to do what the user expects most of the -time, but this implies that we must consider the declarative nature of -labels and blocks and combine those with the dynamic nature of the call -stack. For instance, a C statement always returns from the -lexically scoped subroutine that surrounds it. But to do that, it may -eventually have to peel back any number of layers of dynamic call frames -internal to the subroutine's current call frame. The lexical scope supplies -the declared target for the dynamic operation. There does not seem to be a -prevailing term in the industry for this, so we've coined the term -I to refer to these strange operations that perform a dynamic -operation with a lexical target in mind. Lexotic operators in Perl 6 -include: - - return - next - last - redo - goto - -Some of these operators also fall back to a purely dynamic interpretation if -the lexotic interpretation doesn't work. For instance, C with a label -will prefer to exit a loop lexotically, but if there is no loop with an -appropriate label in the lexical context, it will then scan upward -dynamically through the call frames for any loop with the appropriate label, -even though that loop will not be lexically visible. (C without a -label is purely dynamic.) Lexotic and dynamic control flow is implemented -by a system of control exceptions. For the lexotic return of C, the -control exception will contain the identity of the loop scope to be exited -(since the label was already "used up" to discover that identity), but for -the dynamic fallback, the exception will contain only the loop label to be -matched dynamically. See L below. - -The C operator, as a variant of C, directly transfers control to -the first statement of the lexotically enclosed loop. Essentially, the -compiler turns it into a C with an implicitly generated (secret) label -on that first statement. In order to know when that implicit label must be -generated, we restrict C to the current outer lexical scope. It may -not be used dynamically. (If you find yourself wanting the dynamic variant, -please use C with an explicit label instead, so the compiler can know -to pessimize any unrolling of that loop.) - -=head1 The Relationship of Blocks and Declarations - -Every block is a closure. (That is, in the abstract, they're all anonymous -subroutines that take a snapshot of their lexical environment.) How a block -is invoked and how its results are used are matters of context, but closures -all work the same on the inside. - -Blocks are delimited by curlies, or by the beginning and end of the current -compilation unit (either the current file or the current C string). -Unlike in Perl 5, there are (by policy) no implicit blocks around standard -control structures. (You could write a macro that violates this, but resist -the urge.) Variables that mediate between an outer statement and an inner -block (such as loop variables) should generally be declared as formal -parameters to that block. There are three ways to declare formal parameters -to a closure. - - $func = sub ($a, $b) { .print if $a eq $b }; # standard sub declaration - $func = -> $a, $b { .print if $a eq $b }; # a "pointy" block - $func = { .print if $^a eq $^b } # placeholder arguments - -A bare closure (except the block associated with a conditional statement) -without placeholder arguments that uses C<$_> (either explicitly or -implicitly) is treated as though C<$_> were a formal parameter: - - $func = { .print if $_ }; # Same as: $func = <-> $_ { .print if $_ }; - $func("printme"); - -In any case, all formal parameters are the equivalent of C variables -within the block. See S06 for more on function parameters. - -Except for such formal parameter declarations, all lexically scoped -declarations are visible from the point of declaration to the end of the -enclosing block. Period. Lexicals may not "leak" from a block to any other -external scope (at least, not without some explicit aliasing action on the -part of the block, such as exportation of a symbol from a module). The -"point of declaration" is the moment the compiler sees "C", not the -end of the statement as in Perl 5, so - - my $x = $x; - -will no longer see the value of the outer C<$x>; you'll need to say either - - my $x = $OUTER::x; - -or - - my $x = OUTER::<$x>; - -instead. - -If you declare a lexical twice in the same scope, it is the same lexical: - - my $x; - my $x; - -By default the second declaration will get a compiler warning. You may -suppress this by modifying the first declaration with C: - - my proto $x; - ... - while my $x = @x.shift {...} # no warning - while my $x = @x.shift {...} # no warning - -If you've referred to C<$x> prior to the first declaration, and the compiler -tentatively bound it to C<$OUTER::x>, then it's an error to declare it, and -the compiler is required to complain at that point. If such use can't be -detected because it is hidden in an C, then it is erroneous, since the -C compiler might bind to either C<$OUTER::x> or the subsequently -declared "C". - -As in Perl 5, "C" introduces a lexically scoped alias for a -variable in the current package. - -The new C declarator introduces a compile-time constant, either a -variable or named value, which may be initialized with a pseudo-assignment: - - constant $pi of Int = 3; - my Num constant π = atan2(2,2) * 4; - -The initializing expression is evaluated at C time. Constants (and -enums) default to C scoping so they can be accessed from outside the -package. - -There is a new C declarator that introduces a lexically scoped -variable like C does, but with a lifetime that persists for the life of -the closure, so that it keeps its value from the end of one call to the -beginning of the next. Separate clones of the closure get separate state -variables. However, recursive calls to the same clone use the same state -variable. - -Perl 5's "C" function has been renamed to C to better reflect -what it does. There is also a C prefix operator that sets a -hypothetical value. It works exactly like C, except that the value -will be restored only if the current block exits unsuccessfully. (See -Definition of Success below for more.) C and C temporize or -hypotheticalize the value or the variable depending on whether you do -assignment or binding. One other difference from Perl 5 is that the default -is not to undefine a variable. So - - temp $x; - -causes C<$x> to start with its current value. Use - - undefine temp $x; - -to get the Perl 5 behavior. - -Note that temporizations that are undone upon scope exit must be prepared to -be redone if a continuation within that scope is taken. - -=head1 The Relationship of Blocks and Statements - -In the absence of explicit control flow terminating the block early, the -return value of a block is the value of its final statement. This is -defined as the textually last statement of its top-level list of statements; -any statements embedded within those top-level statements are in their own -lower-level list of statements and, while they may be a final statement in -their subscope, they're not considered the final statement of the outer -block in question. - -This is subtly different from Perl 5's behavior, which was to return the -value of the last expression evaluated, even if that expression was just a -conditional. Unlike in Perl 5, if a final statement in Perl 6 is a -conditional that does not execute any of its branches, it doesn't matter -what the value of the conditional is, the value of that conditional -statement is always C<()>. If there are no statements in the block at all, -the result is also C<()>. - -=head1 Statement-ending blocks - -A line ending with a closing brace "C<}>", followed by nothing but -whitespace or comments, will terminate a statement if an end of statement -can occur there. That is, these two statements are equivalent: - - my $x = sub { 3 } - my $x = sub { 3 }; - -Since bracketed expressions consider their insides to be statements, this -works out consistently even where you might expect problems: - - my $x = [ - sub { 3 }, # this comma is not optional - sub { 3 } # the statement inside [] terminates here - ]; - - my $hash = { - 1 => { 2 => 3, 4 => 5 }, # OK - 2 => { 6 => 7, 8 => 9 } # OK, terminates inner statement - }; - -Because subroutine declarations are expressions, not statements, this is now -invalid: - - sub f { 3 } sub g { 3 } # two terms occur in a row - -But these two are valid: - - sub f { 3 }; sub g { 3 }; - sub f { 3 }; sub g { 3 } # the trailing semicolon is optional - -Though certain control statements could conceivably be parsed in a -self-contained way, for visual consistency all statement-terminating blocks -that end in the middle of a line I be terminated by semicolon unless -they are naturally terminated by some other statement terminator: - - while yin() { yang() } say "done"; # ILLEGAL - while yin() { yang() }; say "done"; # okay, explicit semicolon - @yy := [ while yin() { yang() } ]; # okay within outer [...] - while yin() { yang() } ==> sort # okay, ==> separates statements - -=head1 Conditional statements -XX - -The C and C statements work much as they do in Perl 5. However, -you may omit the parentheses on the conditional: - - if $foo == 123 { - ... - } - elsif $foo == 321 { - ... - } - else { - ... - } - -The result of a conditional statement is the result of the block chosen to -execute. If the conditional does not execute any branch, the return value -is C<()>. - -The C statement does not allow an C or C in Perl 6. - -The value of the conditional expression may be optionally bound to a closure -parameter: - - if testa() -> $a { say $a } - elsif testb() -> $b { say $b } - else -> $b { say $b } - -Note that the value being evaluated for truth and subsequently bound is not -necessarily a value of type C. (All normal types in Perl may be -evaluated for truth. In fact, this construct would be relatively useless if -you could bind only boolean values as parameters, since within the closure -you already know whether it evaluated to true or false.) Binding within an -C automatically binds the value tested by the previous C or -C, which, while known to be false, might nevertheless be an -I value of false. (By similar reasoning, an C allows -binding of a false parameter.) - -An explicit placeholder may also be used: - - if blahblah() { return $^it } - -However, use of C<$_> with a conditional or conditionally repeating -statement's block is I considered sufficiently explicit to turn a 0-ary -block into a 1-ary function, so all these methods use the same invocant: - - if .haste { .waste } - while .haste { .waste } - -(Contrast with a non-conditional statement such as: - - for .haste { .waste } - -where each call to the block would bind a new invocant for the C<.waste> -method, each of which is likely different from the original invocant to the -C<.haste> method.) - -Conditional statement modifiers work as in Perl 5. So do the implicit -conditionals implied by short-circuit operators. Note though that the -contents of parens or brackets is parsed as a statement, so you can say: - - @x = 41, (42 if $answer), 43; - -and that is equivalent to: - - @x = 41, ($answer ?? 42 !! Slip), 43 - -(Only a single statement is allowed inside parens or brackets; otherwise -it will be interpreted as a LoL composer. -See L.) - -=head2 The C and C statements - -The C statement is like C but tests for definedness rather than -truth. In addition, it topicalizes on the condition, much like C: - - with "abc".index("a") { .say } # prints 0 - -These may be cascaded: - - with $s.index("a") { "Found a at $_" } - orwith $s.index("b") { "Found b at $_" } - orwith $s.index("c") { "Found c at $_" } - else { "Didn't find a, b or c" } - -You may intermix C-based and C-based clauses. - -As with C, you may use C to check for undefinedness, -but you may not add an C clause: - - without $answer { fail "Got: $_" } - -There are also C and C statement modifiers: - - return 42 with $answer; - .throw without $answer; - -=head1 Loop statements - -Looping statement modifiers are the same as in Perl 5 except that, for ease -of writing list comprehensions, a looping statement modifier is allowed to -contain a single conditional statement modifier: - - @evens = ($_ * 2 if .odd for 0..100); - -Loop modifiers C, C, and C also work much as in Perl 5. -However, the labeled forms can use method call syntax: C, etc. -The C<.next> and C<.last> methods take an optional argument giving the final -value of that loop iteration. So the old C syntax is still -allowed but really does something like C underneath. Any -block object can be used, not just labels, so to return a value from this -iteration of the current block you can say: - - &?BLOCK.next($retval); - -[Conjecture: a bare C function could be taught to do the -same, as long as C<$retval> isn't a loop label. Presumably multiple -dispatch could sort this out.] - -With a target object or label, loop modifiers search lexotically for the -scope to modify. Without a target, however, they are purely dynamic, and -choose the innermost dynamic loop, which may well be a C or other -implicitly looping function, including user-defined functions. - -There is no longer a C block. Instead, use a C block within -the body of the loop. See below. - -The value of a loop statement is the list of values from each iteration. -Each iteration's value is returned as a single object, only Cs flatten -into the return list. - -For finer-grained control of which iterations return values, use C -and C. - -=head2 The C and C statements -XX - -The C and C statements work as in Perl 5, except that you may -leave out the parentheses around the conditional: - - while $bar < 100 { - ... - } - -As with conditionals, you may optionally bind the result of the conditional -expression to a parameter of the block: - - while something() -> $thing { - ... - } - - while something() { ... $^thing ... } - -Nothing is ever bound implicitly, however, and many conditionals would -simply bind C or C in an uninteresting fashion. This mechanism -is really only good for objects that know how to return a boolean value and -still remain themselves. In general, for most iterated solutions you should -consider using a C loop instead (see below). In particular, we now -generally use C to iterate filehandles. - -=head2 The C statement -XXXXX - -Unlike in Perl 5, applying a statement modifier to a C block is -specifically disallowed: - - do { - ... - } while $x < 10; # ILLEGAL - -Instead, you should write the more Pascal-like C loop: - - repeat { - ... - } while $x < 10; - -or equivalently: - - repeat { - ... - } until $x >= 10; - -Unlike Perl 5's C loop, this is a real loop block now, so C, -C, and C work as expected. The loop conditional on a C -block is required, so it will be recognized even if you put it on a line by -its own: - - repeat - { - ... - } - while $x < 10; - -However, that's likely to be visually confused with a following C -loop at the best of times, so it's also allowed to put the loop conditional -at the front, with the same meaning. (The C keyword forces the -conditional to be evaluated at the end of the loop, so it's still C's -C semantics.) Therefore, even under GNU style rules, the previous -example may be rewritten into a very clear: - - repeat while $x < 10 - { - ... - } - -or equivalently: - - repeat until $x >= 10 - { - ... - } - -As with an ordinary C, you may optionally bind the result of the -conditional expression to a parameter of the block: - - repeat -> $thing { - ... - } while something(); - -or - - repeat while something() -> $thing { - ... - } - -Since the loop executes once before evaluating the condition, the bound -parameter will be undefined that first time through the loop. - -=head2 The general loop statement -X - -The C statement is the C-style C loop in disguise: - - loop ($i = 0; $i < 10; $i++) { - ... - } - -As in C, the parentheses are required if you supply the 3-part spec; -however, the 3-part loop spec may be entirely omitted to write an infinite -loop. That is, - - loop {...} - -is equivalent to the C-ish idiom: - - loop (;;) {...} - -=head2 The C statement -XXXXX<$*IN>X - -There is no C statement any more. It's always spelled C in -Perl 6, so it always takes a list as an argument: - - for @foo { .print } - -As mentioned earlier, the loop variable is named by passing a parameter to -the closure: - - for @foo -> $item { print $item } - -Multiple parameters may be passed, in which case the list is traversed more -than one element at a time: - - for %hash.kv -> $key, $value { print "$key => $value\n" } - -To process two arrays in parallel use the C function to generate a list -that can be bound to the corresponding number of parameters: - - for zip(@a, @b) -> ($a, $b) { print "[$a, $b]\n" } - for @a Z @b -> ($a, $b) { print "[$a, $b]\n" } # same thing - -The list is evaluated lazily by default, so instead of using a C to -read a file a line at a time as you would in Perl 5: - - while (my $line = ) {...} - -in Perl 6 you should use a C instead: - - for $*IN.lines -> $line {...} - -This has the added benefit of limiting the scope of the C<$line> parameter -to the block it's bound to. (The C's declaration of C<$line> -continues to be visible past the end of the block. Remember, no implicit -block scopes.) It is also possible to write - - while $*IN.get -> $line {...} - -However, this is likely to fail on autochomped filehandles, so use the -C loop instead. - -Note also that Perl 5's special rule causing - - while (<>) {...} - -to automatically assign to C<$_> is not carried over to Perl 6. That should -now be written: - - for lines() {...} - -which is short for - - for lines($*ARGFILES) {...} - -Arguments bound to the formal parameters of a pointy block are by default -readonly within the block. You can declare a parameter read/write by -including the "C" trait. The following treats every other value in -C<@values> as modifiable: - - for @values -> $even is rw, $odd { ... } - -In the case where you want all your parameters to default to C, you may -use the visually suggestive double-ended arrow to indicate that values flow -both ways: - - for @values <-> $even, $odd { ... } - -This is equivalent to - - for @values -> $even is rw, $odd is rw { ... } - -If you rely on C<$_> as the implicit parameter to a block, then C<$_> is -considered read/write by default. That is, the construct: - - for @foo {...} - -is actually short for: - - for @foo <-> $_ {...} - -so you can modify the current list element in that case. - -When used as statement modifiers on implicit blocks (thunks), C and -C privately temporize the current value of C<$_> for the left side of -the statement and restore the original value at loop exit: - - $_ = 42; - .say # 42 - .say for 1,2,3; # 1,2,3 - .say; # 42 - -The previous value of C<$_> is not available within the loop. If you want -it to be available, you must rewrite it as an explicit block using curlies: - - { say OUTER::<$_>, $_ } for 1,2,3; # 421,422,423 - -No temporization is necessary with the explicit form since C<$_> is a formal -parameter to the block. Likewise, temporization is never needed for C<< -statement_control: >> because it always calls a closure. - -=head2 The do-once loop - -In Perl 5, a bare block is deemed to be a do-once loop. In Perl 6, the bare -block is not a do-once. Instead C is the do-once loop (which is -another reason you can't put a statement modifier on it; use C for a -test-at-the-end loop). - -For any statement, prefixing with a C allows you to return the value of -that statement and use it in an expression: - - $x = do if $a { $b } else { $c }; - -This construct only allows you to attach a single statement to the end of an -expression. If you want to continue the expression after the statement, or -if you want to attach multiple statements, you must either use the curly -form or surround the entire expression in brackets of some sort: - - @primesquares = (do $_ if .is-prime for 1..100) »**» 2; - -Since a bare expression may be used as a statement, you may use C on an -expression, but its only effect is to function as an unmatched left -parenthesis, much like the C<$> operator in Haskell. That is, precedence -decisions do not cross a C boundary, and the missing "right paren" is -assumed at the next statement terminator or unmatched bracket. A C is -unnecessary immediately after any opening bracket as the syntax inside -brackets expects a statement, so the above can in fact be written: - - @primesquares = ($_ if .is-prime for 1..100) »**» 2; - -This basically gives us list comprehensions as rvalue expressions: - - (for 1..100 { $_ if .is-prime }).say - -Another consequence of this is that any block just inside a left parenthesis -is immediately called like a bare block, so a multidimensional list -comprehension may be written using a block with multiple parameters fed by a -C modifier: - - @names = (-> $name, $num { "$name.$num" } for 'a'..'zzz' X 1..100); - -or equivalently, using placeholders: - - @names = ({ "$^name.$^num" } for 'a'..'zzz' X 1..100); - -Since C is defined as going in front of a statement, it follows that it -can always be followed by a statement label. This is particularly useful -for the do-once block, since it is officially a loop and can take therefore -loop control statements. - -=head2 Loops at the statementlist level vs the statement level - -In any sequence of statements, only the value of the final statement is -returned, so all prior statements are evaluated in sink context, which is -automatically eager, to force the evaluation of side effects. (Side effects -are the only reason to execute such statements in the first place, and Perl -will, in fact, warn you if you do something that is "useless" in sink -context.) A loop in sink context not only evaluates itself eagerly, but can -optimize away the production of any values from the loop. - -The final statement of a statement list is not a sink context, and can -return any value including a lazy list. However, to support the -expectations of imperative programmers (the vast majority of us, it turns -out), any explicit loop found as the final statement of a statement list is -automatically forced to use sink semantics so that the loop executes to -completion before returning from the block. - -This forced sink context is applied to loops I at the statement list -level, that is, at the top level of a compilation unit, or directly inside a -block. Constructs that parse a single statement or semilist as an argument -are presumed to want the results of that statement, so such constructs -remain lazy even when that statement is a loop. Assuming each of the -following statements is the final statement in a block, "sunk" loops such as -these may be indicated: - - for LIST { ... } - ... if COND for LIST - loop { ... } - ... while COND - while COND { ... } - repeat until COND { ... } - -but lazy loops can be indicated by putting the loop in parens or brackets: - - (... if COND for LIST) # lazy list comprehension - [for LIST { ... }] - (loop { ... }) - -or by use of either a statement prefix or a phaser in statement form: - - lazy for LIST { ... } - ENTER for LIST { ... } - -Note that the corresponding block forms put the loop into a statement list, -so these loops are evaluated in sink context: - - lazy { for LIST { ... } } # futile use of 'lazy' here - ENTER { for LIST { ... } } - -It doesn't matter that there is only one statement there; what matters is -that a sequence of statements is expected there by the grammar. - -An eager loop may likewise be indicated by using the C statement -prefix: - - eager for LIST { ... } - eager ... if COND for LIST - eager loop { ... } - eager ... while COND - eager while COND { ... } - eager repeat until COND { ... } - -It is erroneous to write an eager loop without a loop exit, since that will -chew up all your memory. - -Note that since C is considered a one-time loop, it is always evaluated -eagerly, despite being a statement prefix. This is no great hardship; the -C prefix is better documentation in any case. And surely the verb -"do" ought to imply some degree of getting it done eagerly. - -The C construct is not considered a loop, and just returns normally. - -=head2 Statement-level bare blocks - -Although a bare block occurring as a single statement is no longer a do-once -loop, as with loops when used in a statement list, it still executes -immediately as in Perl 5, as if it were immediately dereferenced with a -C<.()> postfix, so within such a block C refers to the dynamic -scope associated with the lexical scope surrounding the block. - -If you wish to return a closure from a function, you must use an explicit -prefix such as C or C or C<< -> >>. - - sub f1 - { - # lots of stuff ... - { say "I'm a closure." } - } - - my $x1= f1; # fall-off return is result of the say, not the closure. - - sub f2 - { - # lots of stuff ... - return { say "I'm a closure." } - } - - my $x2= f2; # returns a Block object. - -Use of a placeholder parameter in statement-level blocks triggers a syntax -error, because the parameter is not out front where it can be seen. -However, it's not an error when prefixed by a C, or when followed by a -statement modifier: - - # Syntax error: Statement-level placeholder block - { say $^x }; - - # Not a syntax error, though $x doesn't get the argument it wants - do { say $^x }; - - # Not an error: Equivalent to "for 1..10 -> $x { say $x }" - { say $^x } for 1..10; - - # Not an error: Equivalent to "if foo() -> $x { say $x }" - { say $^x } if foo(); - -It's not an error to pass parameters to such a block either: - - { say $^x + $^x }(5); - -But as always, you must use them all: - - # Syntax error: Too many positional parameters passed - { say $^x + $^x }(5,6); - -=head2 The C statement prefix -XX - -A variant of C is C. Like C, it is followed by a statement -or block, and executes it once. Unlike C, it evaluates the statement or -block in sink (void) context; its return value is instead specified by -calling the C list prefix operator one or more times within the scope -(either lexical or dynamic) of the C. The C function's -signature is like that of C; while having the syntax of a list -operator, it merely returns a single item or "argument" (see L for -definition). - -The C function is lexotic if there is a visible outer C, but -falls back to purely dynamic if not. Well, it doesn't really fall back, -since a C knows at compile time whether it is being used lexically or -dynamically. Less obviously, so does a C; if a C lexically -contains any C calls, it is marked as lexotic-only, and it will be -invisible to a dynamic C. If the C contains no C -lexically, it by definition cannot be the lexotic target of any C, so -it can only harvest dynamic C calls. The only remaining difficulty -arises if both the user and a library writer attempt to use dynamic gather -with user-defined callbacks that contain C. So we will say that it is -erroneous for a library writer to mix dynamic gather with callbacks unless -those callbacks are somehow "ungathered" to the outer dynamic scope. -[Conjecture: there should either be an C primitive that does -this, or we should allow labeled C/C for such a situation, and -dynamic C must match the C's label (or lack thereof) exactly. -(Using the term "label" loosely, to include other solutions besides the -label syntax, such as .gather and .take methods on some identity object.)] - -If you take multiple items in a comma list (since it is, after all, a list -operator), they will be wrapped up in a C object for return as the -next argument. No additional context is applied by the C operator, -since all context is lazy in Perl 6. The flattening or slicing of any such -returned list will be dependent on how the C's return iterator is -iterated (with C<.get> vs C<.getarg>). - -The value returned by the C to the C's own context is that same -returned argument (which is ignored when the C is in sink context). -Regardless of the C's immediate context, the object returned is also -added to the list of values being gathered, which is returned by the -C as a lazy list (that is, an iterator, really), with each argument -element of that list corresponding to one C. - -Any sublists in the returned list are normally flattened when bound into flat -context. When bound into a slice context, however, the sublist objects -keep their identity as discrete sublists. The -eventual binding context thus determines whether to throw away or keep the -groupings resulting from each individual C call. Most list contexts -are flat rather than sliced, so the boundaries between individual C -calls usually disappear. (FLAT is an acronym meaning Flat Lists Are -Typical. :) - -Because C evaluates its block or statement in sink context, this -typically causes the C function to be evaluated in sink context. -However, a C function that is not in sink context gathers its return -objects I and also returns them unchanged. This makes it easy -to keep track of what you last "took": - - my @squished = gather for @list { - state $previous = take $_; - next if $_ === $previous; - $previous = take $_; - } - -The C function essentially has two contexts simultaneously, the -context in which the C is operating, and the context in which the -C is operating. These need not be identical contexts, since they may -bind or coerce the resulting lists differently: - - my @y; - my @x = gather for 1..2 { # flat context for list of lists - my ($y) := \(take $_, $_ * 10); # binding forces item context - push @y, $y; - } - # @x contains 4 Ints: 1,10,2,20 flattened by list assignment to @x - # @y contains 2 Lists: $(1,10),$(2,20) sliced by binding to positional $y - -Likewise, we can just remember the gather's result list by binding and -later coercing it: - - my ($c) := \(gather for 1..2 { - take $_, $_ * 10; - }); - # $c.flat produces 1,10,2,20 -- flatten fully into a list of Ints. - # $c.lol produces LoL.new($(1,10),$(2,20)) -- list of Lists, a 2-D list. - # $c.item produces $((1,10),(2,20)) -- a list of Lists, as an item. - -Note that the C itself is in sink context in this example because the -C loop is in the sink context provided inside the gather. - -A C is not considered a loop, but it is easy to combine with a loop -statement as in the examples above. - -The C operation may be defined internally using resumable control -exceptions, or dynamic variables, or pigeons carrying clay tablets. The -choice any particular implementation makes is specifically I part of -the definition of Perl 6, and you should not rely on it in portable code. - -=head2 Other C-like forms -X - -Other similar forms, where a keyword is followed by code to be controlled by -it, may also take bare statements, including C, C, C, -C, C, and C. These constructs establish a dynamic scope -without necessarily establishing a lexical scope. (You can always establish -a lexical scope explicitly by using the block form of argument.) As -statement introducers, all these keywords must be followed by whitespace. -(You can say something like C, but then you are calling the -C function using function call syntax instead, and since Perl does -not supply such a function, it will be assumed to be a user-defined -function.) For purposes of flow control, none of these forms are considered -loops, but they may easily be applied to a normal loop. - -Note that any construct in the statement_prefix category defines special -syntax. If followed by a block it does not parse as a list operator or even -as a prefix unary; it will never look for any additional expression -following the block. In particular, - - foo( try {...}, 2, 3 ) - -calls the C function with three arguments. And - - do {...} + 1 - -add 1 to the result of the do block. On the other hand, if a -statement_prefix is followed by a non-block statement, all nested blockless -statement_prefixes will terminate at the same statement ending: - - do do do foo(); bar 43; - -is parsed as: - - do { do { do { foo(); }}}; bar(43); - -=head1 Switch statements -XXXXX - -A switch statement is a means of topicalizing, so the switch keyword is the -English topicalizer, C. The keyword for individual cases is C: - - given EXPR { - when EXPR { ... } - when EXPR { ... } - default { ... } - } - -The current topic is always aliased to the special variable C<$_>. The -C block is just one way to set the current topic. A C loop is -another convenient form (assuming one of its loop variables is bound to -C<$_>). However, since every block that doesn't explicitly take a C<$_> -parameter or declare C<$_> will get an implicit C<$_>, you can set that -and use the C and C keywords in it: - - sub seek-the-answer() { - $_ = (^100).pick; - when 42 { say "The answer!" } - default { say "A number" } - } - -So switching behavior is actually caused by the C statements in the -block, not by the nature of the block itself. A C statement implicitly -does a "smart match" between the current topic (C<$_>) and the argument of -the C. If the smart match succeeds, C's associated block is -executed, and the innermost surrounding block is automatically broken out of. -(If that is not the block you wish to leave, you must use the C -method (or some other control exception such as C or C) to be -more specific.) The value of the inner block is returned as the value of -the outer block. - -If the smart match fails, control proceeds to the next statement normally, -which may or may not be a C statement. Since C statements are -presumed to be executed in order like normal statements, it's not required -that all the statements in a switch block be C statements (though it -helps the optimizer to have a sequence of contiguous C statements, -because then it can arrange to jump directly to the first appropriate test -that might possibly match.) - -The default case: - - default {...} - -is exactly equivalent to - - when * {...} - -Because C statements are executed in order, the default must come -last. You don't have to use an explicit default--you can just fall off the -last C into ordinary code. But use of a C block is good -documentation. - -If you use a C loop with a parameter named C<$_> (either explicitly or -implicitly), that parameter can function as the topic of any C -statements within the loop. - -You can explicitly break out of a C block (and its surrounding -block) early using the C verb. More precisely, it first scans -outward (lexically) for the innermost containing C block. If that -C block is itself directly inside of a C block, the scan -also skips over that, so you can do nesting such as: - - when * > 2 { - when 4 { 'four!' } - default { 'huge' } - } - default { - 'little' - } - -The surrounding frame is then left, returning the value provided to C. -Breaking out of a block with C is also considered a successful return -for the purposes of C and C. - -The implicit break of a normal C block works the same way, returning -the value of the entire block (normally from its last statement) via an -implicit C. - -You can explicitly leave a C block and go to the next statement -following the C by using C. (Note that, unlike C's idea of -"falling through", subsequent C conditions are evaluated. To jump -into the next C block without testing its condition, you must use a -C. But generally that means you should refactor instead.) - -If you have a switch that is the main block of a C loop that uses C<$_> -as its loop variable, and you break out of the switch either implicitly or -explicitly (that is, the switch "succeeds"), control merely goes to the end -of that block, and thence on to the next iteration of the loop. You must -use C (or some more violent control exception such as C) to -break out of the entire loop early. Of course, an explicit C might be -clearer than a C if you really want to go directly to the next -iteration. On the other hand, C can take an optional argument -giving the value for that iteration of the loop. As with the C<.leave> -method, there is also a C<.succeed> method to break from a labelled block -functioning as a switch: - - OUTER.succeed($retval) - -There is a C statement modifier, but it does not have any breakout -semantics; it is merely a smartmatch against the current topic. That is, - - doit() when 42; - -is exactly equivalent to - - doit() if $_ ~~ 42; - -This is particularly useful for list comprehensions: - - @lucky = ($_ when /7/ for 1..100); - -=head1 Exception handlers -X - -Unlike many other languages, Perl 6 specifies exception handlers by placing -a C block I that block that is having its exceptions handled. - -The Perl 6 equivalent to Perl 5's C is C. (Perl 6's -C function only evaluates strings, not blocks, and does not catch -exceptions.) A C block by default has a C block that handles all -fatal exceptions by ignoring them. If you define a C block within -the C, it replaces the default C. It also makes the C -keyword redundant, because any block can function as a C block if you -put a C block within it. To prevent lazy lists from leaking out -unexpectedly, the inside of a C is always considered an eager context, -unless the C itself is in a sink context, in which case the inside of -C is also in sink context. - -Additionally, the C block or statement implicitly enforces a C context such that failures are immediately thrown as exceptions. -(See below.) - -An exception handler is just a switch statement on an implicit topic that -happens to be the current exception to be dealt with. Inside the C -block, the exception in question is bound to C<$_>. Because of smart -matching, ordinary C statements are sufficiently powerful to pattern -match the current exception against classes or patterns or numbers without -any special syntax for exception handlers. If none of the cases in the -C handles the exception, the exception will be rethrown. To ignore -all unhandled exceptions, use an empty C case. (In other words, -there is an implicit C<.die> just inside the end of the C block. -Handled exceptions break out past this implicit rethrow.) Hence, C -is unlike all other switch statements in that it treats code inside a -C block differently from code that's after all the C blocks -but not in a C block. - -More specifically, when you write: - - CATCH { - when Mumble {...} - default {...} - } - -you're really calling into a I that works -something like this: - - -> *@! { - my @handled = (); - my @unhandled = (); - my @*undead = (); - - for @! { - # note, fails current iteration, continues with loop - SIMPLECATCH { push @*undead, $_; push @unhandled, OUTER::<$_>; } - - .handled = True; - when Mumble {...} - default {...} - .handled = False; - - push @unhandled, $_; - - KEEP { push @handled, $_ if .handled } - } - - push @unhandled, @*undead; - - # no point in setting their $! if we're gonna blow past - set_outer_caller's_bang(@handled) unless @unhandled; - - @unhandled; - } - -Whenever an exception occurs during the execution of a handler, it is pushed -onto the end of the C<@*undead> array for later processing by an outer -handler. If there are any unhandled C<@!> exceptions, or if any exceptions -were caught by the inner SIMPLECATCH (which does nothing but runs its push -code, which should not produce any exceptions), then the CATCH block returns -them to the exception thrower. - -The exception thrower looks up the call stack for a catch lambda that -returns () to indicate all exceptions are handled, and then it is happy, and -unwinds the stack to that point. If any exceptions are returned as not -handled, the exception thrower keeps looking for a higher dynamic scope for -a spot to unwind to. Note that any C in the catch lambda eventually -rethrows outside the lambda as a new exception, but not until the current -exception handler has a chance to handle all exceptions that came in via -C<@!>. - -Resumable exceptions may or may not leave normally depending on the -implementation. If continuations are used, the C<.resume> call will simply -goto the continuation in question, and the lambda's callframe is abandoned. -Resumable exceptions may also be implemented by simply marking the current -exception as "resumed", in which case the original exception thrower simply -returns to the code that threw the resumable exception, rather than -unwinding before returning. This could be done by pushing the resumed -exception onto the unhandled list, and then the thrower checking to see if -there is only a single resumed exception in the "unhandled" list. The -unhandled list is a dynamic variable so that it's easy for .resume to -manipulate it. - -A C block sees the lexical scope in which it was defined, but its -caller is the dynamic location that threw the exception. That is, the stack -is not unwound until some exception handler chooses to unwind it by -"handling" the exception in question. So logically, if the C block -throws its own exception, you would expect the C block to catch its -own exception recursively forever. However, a C must not behave that -way, so we say that a C block never attempts to handle any exception -thrown within its own dynamic scope. (Otherwise any C would cause an -infinite loop.) Instead we treasure them up and rethrow them to a handler -further up. - -Unlike C, the presence of a C block does not imply C -semantics for failures; you may, however, use either an explicit C -block around the C or an explicit C to guarantee that -failures are thrown eagerly rather than lazily. - -=head1 Control Exceptions - -All abnormal control flow is, in the general case, handled by the exception -mechanism (which is likely to be optimized away in specific cases.) Here -"abnormal" means any transfer of control outward that is not just falling -off the end of a block. A C, for example, is considered a form of -abnormal control flow, since it can jump out of multiple levels of closures -to the end of the scope of the current subroutine definition. Loop commands -like C are abnormal, but looping because you hit the end of the block -is not. The implicit break (what C does explicitly) of a C -block is abnormal. - -A C block handles only "bad" exceptions, and lets control exceptions -pass unhindered. Control exceptions may be caught with a C block. -Generally you don't need to worry about this unless you're defining a -control construct. You may have one C block and one C -block, since some user-defined constructs may wish to supply an implicit -C block to your closure, but let you define your own C -block. - -A C always exits from the lexically surrounding sub or method -definition (that is, from a function officially declared with the C, -C, or C keywords). Pointy blocks and bare closures are -transparent to C, in that the C statement still means -C<&?ROUTINE.leave> from the C that existed in dynamic scope when -the closure was cloned. - -It is illegal to return from the closure if that C no longer owns a -call frame in the current call stack. - -To return a value (to the dynamical caller) from any pointy block or bare -closure, you either just let the block return the value of its final -expression, or you can use C, which comes in both function and method -forms. The function (or listop) form always exits from the innermost block, -returning its arguments as the final value of the block exactly as C -does. The method form will leave any block in the dynamic scope that can be -named as an object and that responds to the C<.leave> method. - -Hence, the C function: - - leave(1,2,3) - -is really just short for: - - &?BLOCK.leave(1,2,3) - -To return from your immediate caller, you can say: - - caller.leave(1,2,3) - -Further call frames up the caller stack may be located by use of the -C function: - - callframe({ .labels.any eq 'LINE' }).leave(1,2,3); - -By default the innermost call frame matching the selection criteria will be -exited. This can be a bit cumbersome, so in the particular case of labels, -the label that is already visible in the current lexical scope is considered -a kind of pseudo object specifying a potential dynamic context. If instead -of the above you say: - - LINE.leave(1,2,3) - -it was always exit from your lexically scoped C loop, even if some -inner dynamic scope you can't see happens to also have that label. (In -other words, it's lexotic.) If the C label is visible but you aren't -actually in a dynamic scope controlled by that label, an exception is -thrown. (If the C is not visible, it would have been caught earlier -at compile time since C would likely be a bareword.) - -In theory, any user-defined control construct can catch any control -exception it likes. However, there have to be some culturally enforced -standards on which constructs capture which exceptions. Much like C -may only return from an "official" subroutine or method, a loop exit like -C should be caught by the construct the user expects it to be caught -by. (Always assuming the user expects the right thing, of course...) In -particular, if the user labels a loop with a specific label, and calls a -loop control from within the lexical scope of that loop, and if that call -mentions the outer loop's label, then that outer loop is the one that must -be controlled. In other words, it first tries this form: - - LINE.leave(1,2,3) - -If there is no such lexically scoped outer loop in the current subroutine, -then a fallback search is made outward through the dynamic scopes in the -same way Perl 5 does. (The difference between Perl 5 and Perl 6 in this -respect arises only because Perl 5 didn't have user-defined control -structures, hence the sub's lexical scope was I the innermost -dynamic scope, so the preference to the lexical scope in the current sub was -implicit. For Perl 6 we have to make this preference for lexotic behavior -explicit.) - -Warnings are produced in Perl 6 by throwing a resumable control exception to -the outermost scope, which by default prints the warning and resumes the -exception by extracting a resume continuation from the exception, which must -be supplied by the C function (or equivalent). Exceptions are not -resumable in Perl 6 unless the exception object does the C role. -(Note that fatal exception types can do the C role even if thrown -via C--when uncaught they just hit the outermost fatal handler -instead of the outermost warning handler, so some inner scope has to -explicitly treat them as warnings and resume them.) - -Since warnings are processed using the standard control exception mechanism, -they may be intercepted and either suppressed or fatalized anywhere within -the dynamic scope by supplying a suitable C block. This dynamic -control is orthogonal to any lexically scoped warning controls, which merely -decide whether to call C in the first place. - -As with calls to C, the warning control exception is an abstraction -that the compiler is free to optimize away (along with the associated -continuation) when the compiler or runtime can determine that the semantics -would be preserved by merely printing out the error and going on. Since all -exception handlers run in the dynamic scope of the throw, that reduces to -simply returning from the C function most of the time. See previous -section for discussion of ways to return from catch lambdas. The control -lambda is logically separate from the catch lambda, though an implementation -is allowed to combine them if it is careful to retain separate semantics for -catch and control exceptions. - -One additional level of control is the notion of I. If, -instead of throwing a warning directly, the program calls C with a -resumable exception, the throwing of the warning is delayed until first use -(or the caller's policy) requires it to be thrown. If the warning exception -supports the C<.resume_value> method, that will be the value of the failure -after it has resumed. Otherwise the value will be the null string. Numeric -and string conversions use these lazy warnings to allow (but not require) -failsoft semantics. - -=head1 The goto statement -X - -In addition to C, C, and C, Perl 6 also supports C. -As with ordinary loop controls, the label is searched for first lexically -within the current subroutine, then dynamically outside of it. Unlike with -loop controls, however, scanning a scope includes a scan of any lexical -scopes included within the current candidate scope. As in Perl 5, it is -possible to C into a lexical scope, but only for lexical scopes that -require no special initialization of parameters. (Initialization of -ordinary variables does not count--presumably the presence of a label will -prevent code-movement optimizations past the label.) So, for instance, it's -always possible to C into the next case of a C or into either -the "then" or "else" branch of a conditional. You may not go into a -C or a C, though, because that would bypass a formal parameter -binding (not to mention list generation in the case of C). (Note: the -implicit default binding of an outer C<$_> to an inner C<$_> can be emulated -for a bare block, so that doesn't fall under the prohibition on bypassing -formal binding.) - -Because it is possible to go to a label that is after the operation, and -because Perl 6 does one-pass parsing, any C to a label that has not -been yet declared (or is declared outside the outward lexical scope of the -C) must enclose the label in quotes. - -=head1 Exceptions - -As in Perl 5, many built-in functions simply return an undefined value when -you ask for a value out of range, or the function fails somehow. Perl 6 has -C objects, known as "unthrown exceptions" (though really a -C merely contains an unthrown exception), which know whether they -have been handled or not. C<$!> is a convenient link to the last failure, -and only ever contains one exception, the most recent. - -[Conjecture: all unhandled exceptions within a routine could be stored in -C<@!>, with the most recent first. C<$!> would then be sugar for C<@![0]>. -(Or we use push semantics and C<$!> means C<@![*-1]>.) This might be more -robust than merely making C<@!> a parameter to CATCH. However, the new -semantics of autothrowing when sink eats a Failure means we won't have many -unthrown exceptions waiting around to be handled at the end of the block -anymore. We should probably at least issue warnings, though, if the GC -eventually collects a failure that was never handled. We can't really rely -on end-of-routine cleanup to deal with failures that are returned as normal -data, unless we go with the overhead of a lexical C<@!> variable.] - -If you test a C for C<.defined> or C<.Bool>, the C marks -itself as I; the exception acts as a relatively harmless undefined -value thereafter. Any other use of the C object to extract a -normal value will throw its associated exception immediately. (The -C may, however, be stored in any container whose type allows the -C role to be mixed in.) The C<.handled> method returns C on -failures that have not been handled. It returns C for handled -exceptions and for all non-C objects. (That is, it is a C -method, not a C method. Only C objects need to store the -actual status however; other types just return C.) - -The C<.handled> method is C, so you may mark an exception as handled by -assigning C to it. Note however that - - $!.handled = 1; - -marks only the last exception as handled. To mark them all as handled you -must access them individually via the implicit loop of a CATCH block. - -A bare C/C takes C<$!> as the default argument specifying the -exception to be thrown or propagated outward to the caller's C<$!>. - -You can cause built-ins to automatically throw exceptions on failure using - - use fatal; - -The C function responds to the caller's C state. It either -returns an unthrown exception, or throws the exception. Before you get too -happy about this pragma, note that Perl 6 contains various parallel -processing primitives that will tend to get blown up prematurely by thrown -exceptions. Unthrown exceptions are meant to provide a failsoft mechanism -in which failures can be treated as data and dealt with one by one, without -aborting execution of what may be perfectly valid parallel computations. If -you I deal with the failures as data, then sink context will -automatically throw any unhandled C that you try to discard. - -In any case, the overriding design principle here is that no unhandled -exception is ever dropped on the floor, but propagated outward until it is -handled. If no explicit handler handles it, the implicit outermost -exception handler will eventually decide to abort and print all unhandled -exceptions passed in as its current C<@!> list. - -It is possible to fail with a resumable exception, such as a warning. If -the failure throws its exception and the exception resumes, the thrower by -default returns the null string (C<''>) to whatever caused the failure to -throw its exception. This may be overridden by attaching a C<.resume_value> -to the warning. Hence numeric coercions such as C<+"42foo"> can be forced -to return C<42> after issuing a warning. - -=head1 Phasers - -A C block is just a trait of the closure containing it, and is -automatically called at the appropriate moment. These auto-called blocks -are known as I, since they generally mark the transition from one -phase of computing to another. For instance, a C block is called at -the end of compiling a compilation unit. Other kinds of phasers can be -installed as well; these are automatically called at various times as -appropriate, and some of them respond to various control exceptions and exit -values. Phasers marked with a C<*> can be used for their return value. - - BEGIN {...}* at compile time, ASAP, only ever runs once - CHECK {...}* at compile time, ALAP, only ever runs once - LINK {...}* at link time, ALAP, only ever runs once - INIT {...}* at run time, ASAP, only ever runs once - END {...} at run time, ALAP, only ever runs once - - ENTER {...}* at every block entry time, repeats on loop blocks. - LEAVE {...} at every block exit time (even stack unwinds from exceptions) - KEEP {...} at every successful block exit, part of LEAVE queue - UNDO {...} at every unsuccessful block exit, part of LEAVE queue - - FIRST {...}* at loop initialization time, before any ENTER - NEXT {...} at loop continuation time, before any LEAVE - LAST {...} at loop termination time, after any LEAVE - - PRE {...} assert precondition at every block entry, before ENTER - POST {...} assert postcondition at every block exit, after LEAVE - - CATCH {...} catch exceptions, before LEAVE - CONTROL {...} catch control exceptions, before LEAVE - - COMPOSE {...} when a role is composed into a class - -Some of the statement prefixes also behave a little bit like phasers, but -they run in-line with the executable code, so they are spelled in lowercase. -They parse the same as phasers: - - do {...}* run a block or statement as a term - once {...}* run only once, suppressing additional evaluations - gather {...}* start a co-routine thread - eager {...}* evaluate statement eagerly - lazy {...}* defer actual evaluation till value is fetched - sink {...}* evaluate eagerly but throw results away - try {...}* evaluate and trap exceptions (implies 'use fatal') - quietly {...}* evaluate and suppress warnings - start {...}* start computation of a promised result - -Constructs marked with a C<*> have a run-time value, and if evaluated -earlier than their surrounding expression, they simply save their result for -use in the expression later when the rest of the expression is evaluated: - - my $compiletime = BEGIN { now }; - our $temphandle = ENTER { maketemp() }; - -As with other statement prefixes, these value-producing constructs may be -placed in front of either a block or a statement: - - my $compiletime = BEGIN now; - our $temphandle = ENTER maketemp(); - -In fact, most of these phasers will take either a block or a thunk (known as -a I in the vernacular). The statement form can be particularly -useful to expose a lexically scoped declaration to the surrounding lexical -scope without "trapping" it inside a block. - -Hence these declare the same variables with the same scope as the preceding -example, but run the statements as a whole at the indicated time: - - BEGIN my $compiletime = now; - ENTER our $temphandle = maketemp(); - -(Note, however, that the value of a variable calculated at compile time may -not persist under run-time cloning of any surrounding closure.) - -Most of the non-value-producing phasers may also be so used: - - END say my $accumulator; - -Note, however, that - - END say my $accumulator = 0; - -sets the variable to 0 at C time, since that is when the "my" -declaration is actually executed. Only argumentless phasers may use the -statement form. This means that C and C always require a -block, since they take an argument that sets C<$_> to the current topic, so -that the innards are able to behave as a switch statement. (If bare -statements were allowed, the temporary binding of C<$_> would leak out past -the end of the C or C, with unpredictable and quite possibly -dire consequences. Exception handlers are supposed to reduce uncertainty, -not increase it.) - -Code that is generated at run time can still fire off C and C -phasers, though of course those phasers can't do things that would require -travel back in time. You need a wormhole for that. - -The compiler is free to ignore C phasers compiled at run time since -they're too late for the application-wide linking decisions. - -Some of these phasers also have corresponding traits that can be set on -variables. These have the advantage of passing the variable in question -into the closure as its topic: - - our $h will enter { .rememberit() } will undo { .forgetit() }; - -Only phasers that can occur multiple times within a block are eligible for -this per-variable form. - -Apart from C and C, which can only occur once, most of these -can occur multiple times within the block. So they aren't really traits, -exactly--they add themselves onto a list stored in the actual trait. So if -you examine the C trait of a block, you'll find that it's really a -list of phasers rather than a single phaser. - -When multiple phasers are scheduled to run at the same moment, the general -tiebreaking principle is that initializing phasers execute in order -declared, while finalizing phasers execute in the opposite order, because -setup and teardown usually want to happen in the opposite order from each -other. When phasers are in different modules, the C and C -phasers are treated as if declared at C time in the using module. (It -is erroneous to depend on this order if the module is used more than once, -however, since the phasers are only installed the first time they're -noticed.) - -The semantics of C and C are not equivalent to each other in the -case of cloned closures. An C only runs once for all copies of a -cloned closure. A C runs separately for each clone, so separate -clones can keep separate state variables: - - our $i = 0; - ... - $func = once { state $x { $x = $i++ }; dostuff($i) }; - -But C automatically applies "once" semantics to any initializer, so -this also works: - - $func = { state $x = $i++; dostuff($i) } - -Each subsequent clone gets an initial state that is one higher than the -previous, and each clone maintains its own state of C<$x>, because that's -what C variables do. - -Even in the absence of closure cloning, C runs before the mainline -code, while C puts off the initialization till the last possible -moment, then runs exactly once, and caches its value for all subsequent -calls (assuming it wasn't called in sink context, in which case the C -is evaluated once only for its side effects). In particular, this means -that C can make use of any parameters passed in on the first call, -whereas C cannot. - -All of these phaser blocks can see any previously declared lexical -variables, even if those variables have not been elaborated yet when the -closure is invoked (in which case the variables evaluate to an undefined -value.) - -Note: Apocalypse 4 confused the notions of C
/C with
-C/C.  These are now separate notions.  C and C
-are used only for their side effects.  C
 and C return boolean
-values which, if false, trigger a runtime exception.  C and C
-are just variants of C, and for execution order are treated as part
-of the queue of C phasers.
-
-It is conjectured that C
 and C submethods in a class could be
-made to run as if they were phasers in any public method of the class.  This
-feature is awaiting further exploration by means of a C extension.
-
-C, C, and C are meaningful only within the lexical scope
-of a loop, and may occur only at the top level of such a loop block.  A
-C executes only if the end of the loop block is reached normally, or
-an explicit C is executed.  In distinction to C phasers, a
-C phaser is not executed if the loop block is exited via any exception
-other than the control exception thrown by C.  In particular, a
-C bypasses evaluation of C phasers.
-
-[Note: the name C used to be associated with C declarations.
-Now it is associated only with loops.  See the C above for C
-semantics.]
-
-Except for C and C phasers, which run while an exception is
-looking for a place to handle it, all block-leaving phasers wait until the
-call stack is actually unwound to run.  Unwinding happens only after some
-exception handler decides to handle the exception that way.  That is, just
-because an exception is thrown past a stack frame does not mean we have
-officially left the block yet, since the exception might be resumable. In
-any case, exception handlers are specified to run within the dynamic scope
-of the failing code, whether or not the exception is resumable.  The stack
-is unwound and the phasers are called only if an exception is not resumed.
-
-So C phasers for a given block are necessarily evaluated after any
-C and C phasers.  This includes the C variants,
-C and C.  C phasers are evaluated after everything else,
-to guarantee that even C phasers can't violate postconditions.
-Likewise C
 phasers fire off before any C or C (though not
-before C, C, C, or C, since those are done at
-compile or process initialization time).
-
-The C block can be defined in one of two ways.  Either the
-corresponding C is defined as a separate phaser, in which case C
-and C share no lexical scope.  Alternately, any C
 phaser may
-define its corresponding C as an embedded phaser block that closes
-over the lexical scope of the C
.
-
-If exit phasers are running as a result of a stack unwind initiated by an
-exception, this information needs to be made available.  In any case, the
-information as to whether the block is being exited successfully or
-unsuccessfully needs to be available to decide whether to run C or
-C blocks (also see L).  How this information
-is made available is implementation dependent.
-
-An exception thrown from an C phaser will abort the C queue,
-but one thrown from a C phaser will not.  The exceptions thrown by
-failing C
 and C phasers cannot be caught by a C in the
-same block, which implies that C phaser are not run if a C
 phaser
-fails.
-
-If a C fails or any kind of C block throws an exception while
-the stack is unwinding, the unwinding continues and collects exceptions to
-be handled.  When the unwinding is completed all new exceptions are thrown
-from that point.
-
-For phasers such as C and C that are run when exiting a scope
-normally, the return value (if any) from that scope is available as the
-current topic within the phaser.
-
-The topic of the block outside a phaser is still available as C<<
-OUTER::<$_> >>.  Whether the return value is modifiable may be a policy of
-the phaser in question.  In particular, the return value should not be
-modified within a C phaser, but a C phaser could be more
-liberal.
-
-Any phaser defined in the lexical scope of a method is a closure that closes
-over C as well as normal lexicals.  (Or equivalently, an
-implementation may simply turn all such phasers into submethods whose primed
-invocant is the current object.)
-
-=head1 Statement parsing
-
-In this statement:
-
-    given EXPR {
-        when EXPR { ... }
-        when EXPR { ... }
-        ...
-    }
-
-parentheses aren't necessary around C because the whitespace between
-C and the block forces the block to be considered a block rather than
-a subscript, provided the block occurs where an infix operator would be
-expected.  This works for all control structures, not just the new ones in
-Perl 6.  A top-level bare block is always considered a statement block if
-there's a term and a space before it:
-
-    if $foo { ... }
-    elsif $bar { ... }
-    else { ... }
-    while $more { ... }
-    for 1..10 { ... }
-
-You can still parenthesize the expression argument for old times' sake, as
-long as there's a space between the closing paren and the opening brace.
-(Otherwise it will be parsed as a hash subscript.)
-
-Note that the parser cannot intuit how many arguments a list operator is
-taking, so if you mean 0 arguments, you must parenthesize the argument list
-to force the block to appear after a term:
-
-    if caller {...}    # WRONG, parsed as caller({...})
-    if caller() {...}  # okay
-    if (caller) {...}  # okay
-
-Note that common idioms work as expected though:
-
-    for map { $^a + 1 }, @list { .say }
-
-Unless you are parsing a statement that expects a block argument, it is
-illegal to use a bare closure where an operator is expected because it will
-be considered to be two terms in row.  (Remove the whitespace if you wish it
-to be a postcircumfix.)
-
-Anywhere a term is expected, a block is taken to be a closure definition (an
-anonymous subroutine).  If a closure has arguments, it is always taken as a
-normal closure.  (In addition to standard formal parameters, placeholder
-arguments also count, as do the underscore variables.  Implicit use of C<$_>
-with C<.method> also counts as an argument.)
-
-However, if an argumentless closure is empty, or appears to contain nothing
-but a comma-separated list starting with a pair or a hash (counting a single
-pair or hash as a list of one element), the closure will be immediately
-executed as a hash composer, as if called with C<.()>.
-
-    $hash = { };
-    $hash = { %stuff };
-    $hash = { "a" => 1 };
-    $hash = { "a" => 1, $b, $c, %stuff, @nonsense };
-
-    $code = { %_ };                            # use of %_
-    $code = { "a" => $_ };                     # use of $_
-    $code = { "a" => 1, $b, $c, %stuff, @_ };  # use of @_
-    $code = { ; };
-    $code = { @stuff };
-    $code = { "a", 1 };
-    $code = { "a" => 1, $b, $c ==> print };
-
-If you wish to be less ambiguous, the C list operator will explicitly
-evaluate a list and compose a hash of the returned value, while C or
-C<< -> >> introduces an anonymous subroutine:
-
-    $code = -> { "a" => 1 };
-    $code = sub { "a" => 1 };
-    $hash = hash("a" => 1);
-    $hash = hash("a", 1);
-
-Note that the closure in a C will never be interpreted as a hash, since
-such a closure always takes arguments, and use of placeholders (including
-underscore variables) is taken as evidence of arguments.
-
-If a closure is the right argument of the dot operator, the closure is
-interpreted as a hash subscript.
-
-    $code = {$x};       # closure because term expected
-    if $term{$x}        # subscript because postfix expected
-    if $term {$x}       # expression followed by statement block
-    if $term.{$x}       # valid subscript with dot
-    if $term\  {$x}     # valid subscript with "unspace"
-
-Similar rules apply to array subscripts:
-
-    $array = [$x];      # array composer because term expected
-    if $term[$x]        # subscript because postfix expected
-    if $term [$x]       # syntax error (two terms in a row)
-    if $term.[$x]       # valid subscript with dot
-    if $term\  [$x]     # valid subscript with "unspace"
-
-And to the parentheses delimiting function arguments:
-
-    $scalar = ($x);     # grouping parens because term expected
-    if $term($x)        # function call because operator expected
-    if $term ($x)       # syntax error (two terms in a row)
-    if $term.($x)       # valid function call with explicit dot deref
-    if $term\  .($x)    # valid function call with "unspace" and dot
-
-Outside of any kind of expression brackets, a final closing curly on a line
-(not counting whitespace or comments) always reverts to the precedence of
-semicolon whether or not you put a semicolon after it.  (In the absence of
-an explicit semicolon, the current statement may continue on a subsequent
-line, but only with valid statement continuators such as C that cannot
-be confused with the beginning of a new statement.  Anything else, such as a
-statement modifier (on, say, a C statement) must continue on the same
-line, unless the newline be escaped using the "unspace" construct--see S02.)
-
-Final blocks on statement-level constructs always imply semicolon precedence
-afterwards regardless of the position of the closing curly.  Statement-level
-constructs are distinguished in the grammar by being declared in the
-C category:
-
-    macro statement_control: ($expr, &ifblock) {...}
-    macro statement_control: ($expr, &whileblock) {...}
-    macro statement_control: (&beginblock) {...}
-
-Statement-level constructs may start only where the parser is expecting the
-start of a statement.  To embed a statement in an expression you must use
-something like C or C.
-
-    $x =  do { given $foo { when 1 {2}; when 3 {4} } } + $bar;
-    $x = try { given $foo { when 1 {2}; when 3 {4} } } + $bar;
-
-The existence of a C<< statement_control: >> does not preclude us
-from also defining a C<< prefix: >> that I be used within an
-expression:
-
-    macro prefix: (&beginblock) { beginblock().repr }
-
-Then you can say things like:
-
-    $recompile_by = BEGIN { time } + $expiration_time;
-
-But C<< statement_control: >> hides C<< prefix: >> at the
-start of a statement.  You could also conceivably define a C<< prefix:
->>, but then you may not get what you want when you say:
-
-    die if $foo;
-
-since C<< prefix: >> would hide C<< statement_modifier: >>.
-
-Built-in statement-level keywords require whitespace between the keyword and
-the first argument, as well as before any terminating loop.  In particular,
-a syntax error will be reported for C-isms such as these:
-
-    if(...) {...}
-    while(...) {...}
-    for(...) {...}
-
-=head1 Definition of Success
-
-Hypothetical variables are somewhat transactional--they keep their new
-values only on successful exit of the current block, and otherwise are
-rolled back to their original values.
-
-It is, of course, a failure to leave the block by propagating an error
-exception, though returning a defined value after catching an exception is
-okay.
-
-In the absence of error exception propagation, a successful exit is one that
-returns a defined value or list.  (A defined list may contain undefined
-values.) So any Perl 6 function can say
-
-    fail "message";
-
-and not care about whether the function is being called in item or list
-context.  To return an explicit scalar undef, you can always say
-
-    return Mu;          # like "return undef" in Perl 5
-
-Then in list context, you're returning a list of length 1, which is defined
-(much like in Perl 5).  But generally you should be using C in such a
-case to return an exception object.  In any case, returning an unthrown
-exception is considered failure from the standpoint of C.  Backtracking
-over a closure in a regex is also considered failure of the closure, which
-is how hypothetical variables are managed by regexes.  (And on the flip
-side, use of C within a regex closure initiates backtracking of the
-regex.)
-
-=head1 When is a closure not a closure
-
-Everything is conceptually a closure in Perl 6, but the optimizer is free to
-turn unreferenced closures into mere blocks of code.  It is also free to
-turn referenced closures into mere anonymous subroutines if the block does
-not refer to any external lexicals that should themselves be cloned.  (When
-we say "clone", we mean the way the system takes a snapshot of the routine's
-lexical scope and binds it to the current instance of the routine so that if
-you ever use the current reference to the routine, it gets the current
-snapshot of its world in terms of the lexical symbols that are visible to
-it.)
-
-All remaining blocks are conceptually cloned into closures as soon as the
-lexical scope containing them is entered.  (This may be done lazily as long
-as consistent semantics are preserved, so a block that is never executed and
-never has a reference taken can avoid cloning altogether.  Execution or
-reference taking forces cloning in this case--references are not allowed to
-be lazily cloned, since no guarantee can be made that the scope needed for
-cloning will remain in existence over the life of the reference.)
-
-In particular, package subroutines are a special problem when embedded in a
-changing lexical scope (when they make reference to it).  The binding of
-such a definition to a name within a symbol table counts as taking a
-reference, so at compile time there is an initial binding to the symbol
-table entry in question.  For "global" bindings to symbol tables visible at
-compile time, this binds to the compile-time view of the lexical scopes.
-(At run-time, the initial run-time view of these scopes is copied from the
-compiler's view of them, so that initializations carry over, for instance.)
-At run time, when such a subroutine is cloned, an additional binding is done
-at clone time to the same symbol table entry that the original was bound to.
-(The binding is not restored on exit from the current lexical scope; this
-binding records the I cloning, not the currently in-use cloning, so
-any use of the global reference must take into consideration that it is
-functioning only as a cache of the most recent cloning, not as a surrogate
-for the current lexical scope.)
-
-Matters are more complicated if the package in question is lexically
-defined.  In such cases, the package must be cloned as if it were a sub on
-entry to the corresponding lexical scope.  All runtime instances of a single
-package declaration share the same set of compile-time declared functions,
-however, the runtime instances can have different lexical environments as
-described in the preceding paragraph.  If multiple conflicting definitions
-of a sub exist for the same compile-time package, an error condition exists
-and behavior is not specified for Perl 6.0.
-
-Methods in classes behave functionally like package subroutines, and have
-the same binding behavior if the classes are cloned.  Note that a class
-declaration, even an augment, is fundamentally a compile-time operation;
-composition only happens once and the results are recorded in the prototype
-class.  Runtime typological manipulations are limited to reseating
-C scopes of methods.
-
-Lexical names do not share this problem, since the symbol goes out of scope
-synchronously with its usage.  Unlike global subs, they do not need a
-compile-time binding, but like global subs, they perform a binding to the
-lexical symbol at clone time (again, conceptually at the entry to the outer
-lexical scope, but possibly deferred.)
-
-    sub foo {
-        # conceptual cloning happens to both blocks below
-        my $x = 1;
-        my sub bar { print $x }         # already conceptually cloned, but can be lazily deferred
-        my &baz := { bar(); print $x }; # block is cloned immediately, forcing cloning of bar
-        my $code = &bar;                # this would also force bar to be cloned
-        return &baz;
-    }
-
-In particular, blocks of inline control flow need not be cloned until
-called.  [Note: this is currently a potential problem for user-defined
-constructs, since you have to take references to blocks to pass them to
-whatever is managing the control flow.  Perhaps the laziness can be deferred
-through Cs to binding time, so a slurpy of block refs doesn't clone
-them all prematurely.  On the other hand, this either means the C
-must be smart enough to keep track of the lexical scope it came from so that
-it can pass the info to the cloner, or it means that we need some special
-fat not-cloned-yet references that can carry the info lazily.  Neither
-approach is pretty.]
-
-Some closures produce C objects at compile time that cannot be
-cloned, because they're not attached to any runtime code that can actually
-clone them.  C, C, C, C, and C blocks fall
-into this category.  Therefore you can't reliably refer to run-time
-variables from these closures even if they appear to be in the scope.  (The
-compile-time closure may, in fact, see some kind of permanent copy of the
-variable for some storage classes, but the variable is likely to be
-undefined when the closure is run in any case.)  It's only safe to refer to
-package variables and file-scoped lexicals from such a routine.
-
-On the other hand, it is required that C and C blocks be able
-to see transient variables in their current lexical scope, so their cloning
-status depends at least on the cloning status of the block they're in.
-
-=head1 AUTHORS
-
-    Larry Wall 
-
-=for vim:set expandtab sw=4:
diff --git a/S05-regex.pod b/S05-regex.pod
deleted file mode 100644
index a38a07d8..00000000
--- a/S05-regex.pod
+++ /dev/null
@@ -1,4829 +0,0 @@
-=encoding utf8
-
-=head1 TITLE
-
-Synopsis 5: Regexes and Rules
-
-=head1 VERSION
-
-    Created: 24 Jun 2002
-
-    Last Modified: 6 June 2017
-    Version: 181
-
-This document summarizes Apocalypse 5, which is about the new regex
-syntax.  We now try to call them I rather than "regular
-expressions" because they haven't been regular expressions for a
-long time, and we think the popular term "regex" is in the process of
-becoming a technical term with a precise meaning of: "something you do
-pattern matching with, kinda like a regular expression".  On the other
-hand, one of the purposes of the redesign is to make portions of
-our patterns more amenable to analysis under traditional regular
-expression and parser semantics, and that involves making careful
-distinctions between which parts of our patterns and grammars are
-to be treated as declarative, and which parts as procedural.
-
-In any case, when referring to recursive patterns within a grammar,
-the terms I and I are generally preferred over I.
-
-=head1 Overview
-
-In essence, Perl 6 natively implements Parsing Expression Grammars (PEGs)
-as an extension of regular expression notation.  PEGs require that you
-provide a "pecking order" for ambiguous parses.  Perl 6's pecking order
-is determined by a multi-level tie-breaking test:
-
-    1) Most-derived only/proto hides less-derived of the same name
-    2) Longest token matching: food\s+ beats foo by 2 or more positions
-    3) Longest literal prefix: food\w* beats foo\w* by 1 position
-    4) For a given proto, multis from a more-derived grammar win
-    5) Within a given compilation unit, the earlier alternative or multi wins
-
-Tiebreaker #3 will treat any initial sequence of literals as the longest
-literal prefix.  If there is an alternation embedded in the longest token matching,
-those alternations can extend a literal prefix provided everything was literal up to
-the alternation.  If all of the alternations are totally literal, then the literal
-can also extend beyond the end of the alternation when they rejoin.  Otherwise
-the end of the alternation terminates all longest literal prefixes, even the branches
-that are totally literal.  For example:
-
-    / a [ 1 | 2 ] b /   # longest literals are 'a1b' and 'a2b'
-    / a [ 1 | 2\w ] b / # longest literals are 'a1 and 'a2'
-    / a <[ 1 2 ]> b /   # longest literal is only 'a'
-
-Note that in this case, a character class is not treated the same as an alternation.
-All character classes are considered too generic to include in a longest literal string.
-
-As with longest token matching, longest literal prefixes are transitive
-through subrules.  If a subrule is a protoregex, it is treated just as
-alternation with C<|> is, and follows the same rules about extending
-or terminating the longest literal prefix.
-
-In addition to this pecking order, if any rule chosen under the pecking
-backtracks, the next best rule is chosen.  That is, the pecking order
-determines a candidate list; just because one candidate is chosen does not
-mean the rest are thrown away.  They may, however, be explicitly thrown away
-by an appropriate backtracking control (sometimes called a "cut" operator,
-but Perl 6 has several of them, depending on how much you want to cut).
-
-Also, any rule chosen to execute under #1 may choose to delegate to its ancestors;
-PEG backtracking has no control over this.
-
-=head1 New match result and capture variables
-
-The underlying match object is now available via the C<$/>
-variable, which is implicitly lexically scoped.  All user access to the
-most recent match is through this variable, even when
-it doesn't look like it.  The individual capture variables (such as C<$0>,
-C<$1>, etc.) are just elements of C<$/>.
-
-By the way, unlike in Perl 5, the numbered capture variables now
-start at C<$0> instead of C<$1>.  See below.
-
-In order to detect accidental use of Perl 5's unrelated C<$/>
-variable, Perl 6's C<$/> variable may not be assigned to directly.
-
-    $/ = $x;   # "Unsupported use of $/ variable as input record separator"
-    $/ := $x;  # OK, binding
-    $/ RR= $x; # OK, metaoperator
-    ($/) = $x; # OK, list assignment
-
-=head1 Unchanged syntactic features
-
-The following regex features use the same syntax as in Perl 5:
-
-=over
-
-=item *
-
-Capturing: (...)
-
-=item *
-
-Repetition quantifiers: *, +, and ?
-
-=item *
-
-Alternatives:  |
-
-=item *
-
-Backslash escape:  \
-
-=item *
-
-Minimal matching suffix:   ??,  *?,  +?
-
-=back
-
-While the syntax of C<|> does not change, the default semantics do
-change slightly.  We are attempting to concoct a pleasing mixture
-of declarative and procedural matching so that we can have the
-best of both.  In short, you need not write your own tokener for
-a grammar because Perl will write one for you.  See the section
-below on "Longest-token matching".
-
-=head1 Simplified lexical parsing of patterns
-
-Unlike traditional regular expressions, Perl 6 does not require
-you to memorize an arbitrary list of metacharacters.  Instead it
-classifies characters by a simple rule.  All glyphs (graphemes)
-whose base characters are either the underscore (C<_>) or have
-a Unicode classification beginning with 'L' (i.e. letters) or 'N'
-(i.e. numbers) are always literal (i.e. self-matching) in regexes. They
-must be escaped with a C<\> to make them metasyntactic (in which
-case that single alphanumeric character is itself metasyntactic,
-but any immediately following alphanumeric character is not).
-
-All other glyphs--including whitespace--are exactly the opposite:
-they are always considered metasyntactic (i.e. non-self-matching) and
-must be escaped or quoted to make them literal.  As is traditional,
-they may be individually escaped with C<\>, but in Perl 6 they may
-be also quoted as follows.
-
-Sequences of one or more glyphs of either type (i.e. any glyphs at all)
-may be made literal by placing them inside single quotes.  (Double
-quotes are also allowed, with the same interpolative semantics as
-the current language in which the regex is lexically embedded.)
-Quotes create a quantifiable atom, so while
-
-    moose*
-
-quantifies only the 'e' and matches "mooseee", saying
-
-    'moose'*
-
-quantifies the whole string and would match "moosemoose".
-
-Here is a table that summarizes the distinctions:
-
-                 Alphanumerics        Non-alphanumerics         Mixed
-
- Literal glyphs   a    1    _        \*  \$  \.   \\   \'       K\-9\!
- Metasyntax      \a   \1   \_         *   $   .    \    '      \K-\9!
- Quoted glyphs   'a'  '1'  '_'       '*' '$' '.' '\\' '\''     'K-9!'
-
-In other words, identifier glyphs are literal (or metasyntactic when
-escaped), non-identifier glyphs are metasyntactic (or literal when
-escaped), and single quotes make everything inside them literal.
-
-Note, however, that not all non-identifier glyphs are currently
-meaningful as metasyntax in Perl 6 regexes (e.g. C<\1> C<\_> C<->
-C). It is more accurate to say that all unescaped non-identifier
-glyphs are I metasyntax, and reserved for future use.
-If you use such a sequence, a helpful compile-time error is issued
-indicating that you either need to quote the sequence or define a new
-operator to recognize it.
-
-The semicolon character is specifically reserved as a non-meaningful
-metacharacter; if an unquoted semicolon is seen, the compiler will
-complain that the regex is missing its terminator.
-
-=head1 Modifiers
-
-=over
-
-=item *
-
-The extended syntax (C) is no longer required...it's the default.
-(In fact, it's pretty much mandatory--the only way to get back to
-the old syntax is with the C<:Perl5>/C<:P5> modifier.)
-
-=item *
-
-There are no C or C modifiers (changes to the meta-characters
-replace them - see below).
-
-=item *
-
-There is no C evaluation modifier on substitutions; instead use:
-
-     s/pattern/{ doit() }/
-
-or:
-
-     s[pattern] = doit()
-
-Instead of C say:
-
-     s/pattern/{ EVAL doit() }/
-
-or:
-
-     s[pattern] = doit().EVAL
-
-=item *
-
-Modifiers are now placed as adverbs at the I of a match/substitution:
-
-     m:g:i/\s* (\w*) \s* ,?/;
-
-Every modifier must start with its own colon.  The delimiter must be
-separated from the final modifier by whitespace if it would otherwise be taken
-as an argument to the preceding modifier (which is true if and only if
-the next character is a left parenthesis.)
-
-=item *
-
-The single-character modifiers also have longer versions:
-
-         :i        :ignorecase
-         :m        :ignoremark
-         :g        :global
-         :r        :ratchet
-
-=item *
-
-The C<:i> (or C<:ignorecase>) modifier causes case distinctions to be
-ignored in its lexical scope, but not in its dynamic scope.  That is,
-subrules always use their own case settings.  The amount of case folding
-depends on the current context.  In byte and codepoint mode, level 1 case folding
-is required (as defined in TR18 section 2.4).  In grapheme mode level 2 is
-required.
-
-The C<:ii> (or C<:samecase>) variant may be used on a substitution to change the
-substituted string to the same case pattern as the matched string.  It implies
-the same pattern semantics as C<:i> above, so it is not necessary to
-put both C<:i> and C<:ii>.
-
-If the pattern is matched without the C<:sigspace> modifier, case
-info is carried across on a character by character basis.  If the
-right string is longer than the left one, the case of the final
-character is replicated.  Titlecase is carried across if possible
-regardless of whether the resulting letter is at the beginning of
-a word or not; if there is no titlecase character available, the
-corresponding uppercase character is used.  (This policy can be
-modified within a lexical scope by a language-dependent Unicode
-declaration to substitute titlecase according to the orthographic
-rules of the specified language.)  Characters that carry no case
-information leave their corresponding replacement character unchanged.
-
-If the pattern is matched with C<:sigspace>, then a slightly smarter
-algorithm is used which attempts to determine if there is a uniform
-capitalization policy over each matched word, and applies the same
-policy to each replacement word.  If there doesn't seem to be a uniform
-policy on the left, the policy for each word is carried over word by
-word, with the last pattern word replicated if necessary.  If a word
-does not appear to have a recognizable policy, the replacement word
-is translated character for character as in the non-sigspace case.
-Recognized policies include:
-
-    lc()
-    uc()
-    tc()
-    tclc()
-
-In any case, only the officially matched string part of the pattern
-match counts, so any sort of lookahead or contextual matching is not
-included in the analysis.
-
-=item *
-
-The C<:m> (or C<:ignoremark>) modifier scopes exactly like C<:ignorecase>
-except that it ignores marks (accents and such) instead of case.  It is equivalent
-to taking each grapheme (in both target and pattern), converting
-both to NFD (maximally decomposed) and then comparing the two base
-characters (Unicode non-mark characters) while ignoring any trailing
-mark characters.  The mark characters are ignored only for the purpose
-of determining the truth of the assertion; the actual text matched
-includes all ignored characters, including any that follow the final
-base character.
-
-The C<:mm> (or C<:samemark>) variant may be used on a substitution to change the
-substituted string to the same mark/accent pattern as the matched string.
-It implies the same pattern semantics as C<:m> above, so it is not necessary
-to put both C<:m> and C<:mm>.
-
-Mark info is carried across on a character by character basis.  If
-the right string is longer than the left one, the remaining characters
-are substituted without any modification.  (Note that NFD/NFC distinctions
-are usually immaterial, since Perl encapsulates that in grapheme mode.)
-Under C<:sigspace> the preceding rules are applied word by word.
-
-=item *
-
-The C<:c> (or C<:continue>) modifier causes the pattern to continue
-scanning from the specified position (defaulting to C<($/ ?? $/.to !! 0)>):
-
-     m:c($p)/ pattern /     # start scanning at position $p
-
-Note that this does not automatically anchor the pattern to the starting
-location.  (Use C<:p> for that.)  The pattern you supply to C
-has an implicit C<:c> modifier.
-
-=item *
-
-The C<:p> (or C<:pos>) modifier causes the pattern to try to match only at
-the specified string position:
-
-     m:pos($p)/ pattern /  # match at position $p
-
-If the argument is omitted, it defaults to C<($/ ?? $/.to !! 0)>.  (Unlike in
-Perl 5, the string itself has no clue where its last match ended.)
-All subrule matches are implicitly passed their starting position.
-Likewise, the pattern you supply to a Perl macro's C
-trait has an implicit C<:p> modifier.
-
-Note that
-
-     m:c($p)/pattern/
-
-is roughly equivalent to
-
-     m:p($p)/.*? <( pattern )> /
-
-All of C<:g>, C<:ov>, C<:nth>, and C<:x> are incompatible with C<:p> and
-will fail, recommending use of C<:c> instead.  The C<:ex> modifier is allowed
-but will produce only matches at that position.
-
-=item *
-
-The new C<:s> (C<:sigspace>) modifier causes certain whitespace sequences
-to be considered "significant"; they are replaced by a whitespace
-matching rule, C<< <.ws> >>. Only whitespace sequences immediately following a
-matching construct (atom, quantified atom, or assertion) are eligible.
-Initial whitespace is ignored at the front of
-any regex, to make it easy to write rules that can participate in
-longest-token-matching alternations. Trailing space inside the regex
-delimiters is significant.
-
-That is,
-
-     m:s/ next cmd '='   /
-
-is the same as:
-
-     m/ next <.ws> cmd <.ws> '=' <.ws> /
-
-which is effectively the same as:
-
-     m/ next \s+ cmd \s* '=' \s* /
-
-But in the case of
-
-     m:s{(a|\*) (b|\+)}
-
-or equivalently,
-
-     m { (a|\*) <.ws> (b|\+) }
-
-C<< <.ws> >> can't decide what to do until it sees the data.
-It still does the right thing.  If not, define your own C<< ws >>
-and C<:sigspace> will use that.
-
-Whitespace is ignored not just at the front of any rule that might
-participate in longest-token matching, but in the front of any
-alternative within an explicit alternation as well, for the same
-reason.  If you want to match sigspace before a set of alternatives,
-place your whitespace outside of the brackets containing the alternation.
-
-When you write
-
-    rule TOP { ^  $ }
-
-this is the same as
-
-    token TOP { ^ <.ws>  <.ws> $ <.ws> }
-
-but note that the final C<< <.ws> >> always matches the null string, since C<$> asserts end of string.
-Also, if your C rule does not anchor with C<^>, it might not match initial whitespace.
-
-Specifically, the following constructs turn following whitespace into sigspace:
-
-    any atom or quantified atom
-    $foo @bar
-    'a' "$b"
-    ^ $ ^^ $$
-    (...) [...] <...> as a whole atoms
-    (...)* [...]* <...>* as quantified atoms
-    <( and )>
-    « and » (but don't use « that way!)
-
-and these do not:
-
-    opening ( or [
-    | or ||
-    & or &&
-    ** % or %%
-    :foo declarations, including :my and :sigspace itself
-    {...}
-
-When we say sigspace can follow either an atom or a quantified atom, we
-mean that it can come between an atom and its quantifier:
-
-    ms/  * /      # means / [<.ws>]* /
-
-(If each atom matches whitespace, then it doesn't need to match after the
-quantifier.)
-
-In general you don't need to use C<:sigspace> within grammars because
-the parser rules automatically handle whitespace policy for you.
-In this context, whitespace often includes comments, depending on
-how the grammar chooses to define its whitespace rule.  Although the
-default C<< <.ws> >> subrule recognizes no comment construct, any
-grammar is free to override the rule.  The C<< <.ws> >> rule is not
-intended to mean the same thing everywhere.
-
-It's also possible to pass an argument to C<:sigspace> specifying
-a completely different subrule to apply.  This can be any rule, it
-doesn't have to match whitespace.  When discussing this modifier, it is
-important to distinguish the significant whitespace in the pattern from
-the "whitespace" being matched, so we'll call the pattern's whitespace
-I, and generally reserve I to indicate whatever
-C<< <.ws> >> matches in the current grammar. The correspondence
-between sigspace and whitespace is primarily metaphorical, which is
-why the correspondence is both useful and (potentially) confusing.
-
-The C<:ss> (or C<:samespace>) variant may be used on substitutions to
-do smart space mapping in addition to smart space matching.  (That is,
-C<:ss> implies C<:s>.)  For each sigspace-induced call to C<<  >>
-on the left, the matched whitespace is copied over to the corresponding
-slot on the right, as represented by a single whitespace character
-in the replacement string wherever space replacement is desired.
-If there are more whitespace slots on the right than the left, those
-righthand characters remain themselves.  If there are not enough
-whitespace slots on the right to map all the available whitespace
-slots from the match, the algorithm tries to minimize information
-loss by randomly splicing "common" whitespace characters out of the
-list of whitespace.  From least valuable to most, the pecking order is:
-
-    spaces
-    tabs
-    all other horizontal whitespace, including Unicode
-    newlines (including crlf as a unit)
-    all other vertical whitespace, including Unicode
-
-The primary intent of these rules is to minimize format disruption
-when substitution happens across line boundaries and such.  There is,
-of course, no guarantee that the result will be exactly what a human would
-do.
-
-The C<:s> modifier is considered sufficiently important that
-match variants are defined for them:
-
-    ms/match some words/                        # same as m:sigspace
-    ss/match some words/replace those words/    # same as s:samespace
-
-Note that C is defined in terms of C<:ss>, so:
-
-    $_ = "a b\nc\td";
-    ss/b c d/x y z/;
-
-ends up with a value of "C".
-
-=item *
-
-New modifiers specify Unicode level:
-
-     m:bytes  / .**2 /       # match two bytes
-     m:codes  / .**2 /       # match two codepoints
-     m:graphs / .**2 /       # match two language-independent graphemes
-     m:chars  / .**2 /       # match two characters at current max level
-
-There are corresponding pragmas to default to these levels.  Note that
-the C<:chars> modifier is always redundant because dot always matches
-characters at the highest level allowed in scope.  This highest level
-may be identical to one of the other three levels, or it may be more
-specific than C<:graphs> when a particular language's character rules
-are in use.  Note that you may not specify language-dependent character
-processing without specifying I language you're depending on.
-[Conjecture: the C<:chars> modifier could take an argument specifying
-which language's rules to use for this match.]
-
-=item *
-
-The new C<:Perl5>/C<:P5> modifier allows Perl 5 regex syntax to be
-used instead.  (It does not go so far as to allow you to put your
-modifiers at the end.)  For instance,
-
-     m:P5/(?mi)^(?:[a-z]|\d){1,2}(?=\s)/
-
-is equivalent to the Perl 6 syntax:
-
-    m/ :i ^^ [ <[a..z]> || \d ] ** 1..2  /
-
-=item *
-
-Any integer modifier specifies a count. What kind of count is
-determined by the character that follows.
-
-=item *
-
-If followed by an C, it means repetition.  Use C<:x(4)> for the
-general form.  So
-
-     s:4x [ (<.ident>) '=' (\N+) $$] = "$0 => $1";
-
-is the same as:
-
-     s:x(4) [ (<.ident>) '=' (\N+) $$] = "$0 => $1";
-
-which is almost the same as:
-
-     s:c[ (<.ident>) '=' (\N+) $$] = "$0 => $1" for 1..4;
-
-except that the string is unchanged unless all four matches are found.
-However, ranges are allowed, so you can say C<:x(1..4)> to change anywhere
-from one to four matches.
-
-=item *
-
-If the number is followed by an C, C, C, or C
 quote-like operator now also has a method form called -C. Its argument is a list of pairs. You can use anything that -produces a pair list: - - $str.trans( %mapping.pairs ); - -Use the C<.=> form to do a translation in place: - - $str.=trans( %mapping.pairs ); - -(Perl 6 does not support the C form, which was only in C because -they were running out of single letters.) - -=item * - -The two sides of any pair can be strings interpreted as C would: - - $str.=trans( 'A..C' => 'a..c', 'XYZ' => 'xyz' ); - -As a degenerate case, each side can be individual characters: - - $str.=trans( 'A'=>'a', 'B'=>'b', 'C'=>'c' ); - -Whitespace characters are taken literally as characters to be -translated from or to. The C<..> range sequence is the only metasyntax -recognized within a string, though you may of course use backslash -interpolations in double quotes. If the right side is too short, the -final character is replicated out to the length of the left string. -If there is no final character because the right side is the null -string, the result is deletion instead. - -=item * - -Either or both sides of the pair may also be Array objects: - - $str.=trans( ['A'..'C'] => ['a'..'c'], => ); - -The array version is the underlying primitive form: the semantics of -the string form is exactly equivalent to first doing C<..> expansion -and then splitting the string into individual characters and then -using that as an array. - -=item * - -The array version can map one-or-more characters to one-or-more -characters: - - $str.=trans( [' ', '<', '>', '&' ] => - [' ', '<', '>', '&' ]); - -In the case that more than one sequence of input characters matches, -the longest one wins. In the case of two identical sequences the -first in order wins. - -As with the string form, missing righthand elements replicate the -final element, and a null array results in deletion instead. - -=item * - -The recognition done by the string and array forms is very basic. -To achieve greater power, any recognition element of the left side -may be specified by a regex that can do character classes, lookahead, -etc. - - - $str.=trans( [/ \h /, '<', '>', '&' ] => - [' ', '<', '>', '&' ]); - - $str.=trans( / \s+ / => ' ' ); # squash all whitespace to one space - $str.=trans( / <-alpha> / => '' ); # delete all non-alpha - -These submatches are mixed into the overall match in exactly the same way that -they are mixed into parallel alternation in ordinary regex processing, so -longest token rules apply across all the possible matches specified to the -transliteration operator. Once a match is made and transliterated, the parallel -matching resumes at the new position following the end of the previous match, -even if it matched multiple characters. - -=item * - -If the right side of the arrow is a closure, it is evaluated to -determine the replacement value. If the left side was matched by a -regex, the resulting match object is available within the closure. - -=back - -=head1 Substitution - -There are also method forms of C and C: - - $str.match(/pat/); - $str.subst(/pat/, "replacement"); - $str.subst(/pat/, {"replacement"}); - $str.=subst(/pat/, "replacement"); - $str.=subst(/pat/, {"replacement"}); - -The C<.match> and C<.subst> methods support the adverbs of C and -C as named arguments, so you can write - - $str.match(/pat/, :g) - -as an equivalent to - - $str.comb(/pat/, :match) - -There is no syntactic sugar here, so in order to get deferred -evaluation of the replacement you must put it into a closure. The -syntactic sugar is provided only by the quotelike forms. First there -is the standard "triple quote" form: - - s/pattern/replacement/ - -Only non-bracket characters may be used for the "triple quote". The -right side is always evaluated as if it were a double-quoted string -regardless of the quote chosen. - -As with Perl 5, a bracketing form is also supported, but unlike Perl 5, -Perl 6 uses the brackets I around the pattern. The replacement -is then specified as if it were an ordinary item assignment, with ordinary -quoting rules. To pick your own quotes on the right just use one of the C -forms. The substitution above is equivalent to: - - s[pattern] = "replacement" - -or - - s[pattern] = qq[replacement] - -This is not a normal assignment, since the right side is evaluated each -time the substitution matches (much like the pseudo-assignment to declarators -can happen at strange times). It is therefore treated as a "thunk", that is, -it will be called as a chunk of code that creates a dynamic scope but not a -lexical scope. (You can also think of a thunk as a closure that uses the -current lexical scope parasitically.) In fact, it makes no sense at all to say - - s[pattern] = { doit } - -because that would try to substitute a closure into the string. - -Any scalar assignment operator may be used; the substitution macro -knows how to turn - - $target ~~ s:g[pattern] op= expr - -into something like: - - $target.=subst(rx[pattern], { $() op expr }, :g) - -(The actual implementation of C must return a C to make -smartmatch work right. The rewrite above merely returns the changed string.) - -So, for example, you can multiply every dollar amount by 2 with: - - s:g[\$ <( \d+ )>] *= 2 - -(Of course, the optimizer is free to do something faster than an actual -method call.) - -You'll note from the last example that substitutions only happen on -the "official" string result of the match, that is, the portion of -the string between the C<$/.from> and C<$/.to> positions. -(Here we set those explicitly using the C<< <(...)> >> pair; otherwise we -would have had to use lookbehind to match the C<$>.) - -Please note that the C<:ii>/C<:samecase> and C<:mm>/C<:samemark> -switches are really two different modifiers in one, and when the compiler desugars -the quote-like forms it distributes semantics to both the pattern -and the replacement. That is, C<:ii> on the replacement implies a C<:i> on the -pattern, and C<:mm> implies C<:m>. The proper method equivalents to: - - s:ii/foo/bar/ - s:mm/boo/far/ - -are not: - - .subst(/foo/, 'bar', :ii) # WRONG - .subst(/boo/, 'far', :mm) # WRONG - -but rather: - - .subst(rx:i/foo/, 'bar', :ii) # okay - .subst(rx:m/boo/, 'far', :mm) # okay - -It is specifically I required of an implementation that it treat -the regexes as generic with respect to case and mark. Retroactive -recompilation is considered harmful. If an implementation does do lazy -generic case and mark semantics, it is erroneous and non-portable -for a program to depend on it. - -One other difference between the C and C<.subst> forms is that, -while C<.subst> returns the modified string (and cannot, therefore, -be used as a smart matcher), the C form always returns either a -C object to indicate to smartmatch that it was successful, -or a C value to indicate that it was not. - -Likewise, for both C matches and C substitutions, there may -be multiple matches found. These constructs must still continue to -work under smartmatching while returning a list of matches. Fortunately, -C is one of the distinguished types that a matcher may return -to indicate success or failure. So these construct simply return the -list of successful matches, which will be empty (and hence false) if no -matches occurred. - -=head1 Positional matching, fixed width types - -=over - -=item * - -To anchor to a particular position in the general case you can use -the C<< >> assertion to say that the current position -is the same as the position object you supply. You may set the -current match position via the C<:c> and C<:p> modifiers. - -However, please remember that in Perl 6 string positions are generally -I integers, but objects that point to a particular place in -the string regardless of whether you count by bytes or codepoints or -graphemes. If used with an integer, the C assertion will assume -you mean the current lexically scoped Unicode level, on the assumption -that this integer was somehow generated in this same lexical scope. -If this is outside the current string's allowed Unicode abstraction levels, an -exception is thrown. See S02 for more discussion of string positions. - -=item * - -C types are based on fixed-width cells and can therefore -handle integer positions just fine, and treat them as array indices. -In particular, C (also known as C) is just an old-school byte string. -Matches against C types are restricted to ASCII semantics in -the absence of an I modifier asking for the array's values -to be treated as some particular encoding such as UTF-32. (This is -also true for those compact arrays that are considered isomorphic to -C types.) Positions within C types are always integers, -counting one per unit cell of the underlying array. Be aware that -"from" and "to" positions are reported as being between elements. -If matching against a compact array C<@foo>, a final position of 42 -indicates that C<@foo[42]> was the first element I included. - -=back - -=head1 Matching against non-strings - -=over - -=item * - -Anything that can be tied to a string can be matched against a -regex. This feature is particularly useful with input streams: - - my $stream := cat $fh.lines; # tie scalar to filehandle - - # and later... - - $stream ~~ m/pattern/; # match from stream - -=item * - -Any non-compact array of mixed strings or objects can be matched -against a regex as long as you present them as an object with the C -interface, which does not preclude the object having other interfaces -such as C. Normally you'd use C to generate such an object: - - @array.cat ~~ / foo <,> bar * /; - -The special C<< <,> >> subrule matches the boundary between elements. -The C<< >> assertion matches any individual array element. -It is the equivalent of the "dot" metacharacter for the whole element. - -If the array elements are strings, they are concatenated virtually into -a single logical string. If the array elements are tokens or other -such objects, the objects must provide appropriate methods for the -kinds of subrules to match against. It is an assertion failure to match -a string-matching assertion against an object that doesn't provide -a stringified view. However, pure object lists can be parsed as long as -the match (including any subrules) restricts itself to assertions like: - - <.isa(Dog)> - <.does(Bark)> - <.can('scratch')> - -It is permissible to mix objects and strings in an array as long as they're -in different elements. You may not embed objects in strings, however. -Any object may, of course, pretend to be a string element if it likes, -and so a C object may be used as a substring with the same restrictions -as in the main string. - -Please be aware that the warnings on C<.from> and C<.to> returning -opaque objects goes double for matching against an array, where a -particular position reflects both a position within the array and -(potentially) a position within a string of that array. Do not -expect to do math with such values. Nor should you expect to be -able to extract a substr that crosses element boundaries. -[Conjecture: Or should you?] - -=item * - -To match against every element of an array, use a hyper operator: - - @array».match($regex); - -=item * - -To match against any element of the array, it suffices to use ordinary -smartmatching: - - @array ~~ $regex; - -=back - -=head1 When C<$/> is valid - -To provide implementational freedom, the C<$/> variable is not -guaranteed to be defined until the pattern reaches a sequence -point that requires it (such as completing the match, or calling an -embedded closure, or even evaluating a submatch that requires a Perl -expression for its argument). Within regex code, C<$/> is officially -undefined, and references to C<$0> or other capture variables may -be compiled to produce the current value without reference to C<$/>. -Likewise a reference to C<< $ >> does not necessarily mean C<< -$/ >> within the regex proper. During the execution of a match, -the current match state is actually stored in a C<$¢> variable -lexically scoped to an appropriate portion of the match, but that is -not guaranteed to behave the same as the C<$/> object, because C<$/> -is of type C, while the match state is of a type derived from C. - -In any case this is all transparent to the user for simple matches; -and outside of regex code (and inside closures within the regex) -the C<$/> variable is guaranteed to represent the state of the match -at that point. That is, normal Perl code can always depend on C<< -$ >> meaning C<< $/ >>, and C<$0> meaning C<$/[0]>, whether -that code is embedded in a closure within the regex or outside the -regex after the match completes. - -=head1 AUTHORS - - Damian Conway - Allison Randal - Patrick Michaud - Larry Wall - Moritz Lenz - Tobias Leich - -=for vim:set expandtab sw=4: diff --git a/S06-routines.pod b/S06-routines.pod deleted file mode 100644 index e5c31da5..00000000 --- a/S06-routines.pod +++ /dev/null @@ -1,3614 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 6: Subroutines - -=head1 VERSION - - Created: 21 Mar 2003 - - Last Modified: 16 Oct 2015 - Version: 169 - -This document summarizes Apocalypse 6, which covers subroutines and the -new type system. - -=head1 Subroutines and other code objects - -C is the parent type of all keyword-declared code blocks. -All routines are born with undefined values of C<$_>, C<$!>, -and C<$/>, unless the routine declares them otherwise explicitly. -A compilation unit, such as a module file or an C string, is also -considered a routine, or you would not be -able to reference C<$!> or C<$/> in them. - -Non-routine code Cs, -declared with C<< -> >> or with bare curlies, are born only with C<$_>, -which is aliased to its OUTER::<$_> unless bound as a parameter. -A block generally uses the C<$!> and C<$/> defined by the innermost -enclosing routine, unless C<$!> or C<$/> is explicitly declared in -the block. - -A thunk is a piece of code that may not execute immediately, for instance -because it is part of a conditional operator, or a default initialization of -an attribute. It has no scope of its own, so any new variables defined in -a thunk, will leak to the scope that they're in. Note however that -any and all lazy constructs, whether block-based or thunk-based, -such as gather or start or C<< ==> >> should declare their own C<$/> -and C<$!> so that the user's values for those variables cannot be -clobbered asynchronously. - -B (keyword: C) are non-inheritable routines with -parameter lists. - -B (keyword: C) are inheritable routines which always -have an associated object (known as their invocant) and belong to a -particular kind or class. - -B (keyword: C) are non-inheritable methods, or -subroutines masquerading as methods. They have an invocant and belong to -a particular kind or class. - -B (keyword: C) are methods (of a grammar) that perform -pattern matching. Their associated block has a special syntax (see -Synopsis 5). (We also use the term "regex" for anonymous patterns -of the traditional form.) - -B (keyword: C) are regexes that perform low-level -non-backtracking (by default) pattern matching. - -B (keyword: C) are regexes that perform non-backtracking -(by default) pattern matching (and also enable rules to do whitespace -dwimmery). - -B (keyword: C or C) are routines or methods that are -installed such that they will be called as part of the compilation process, -and which can therefore take temporary control of the subsequent -compilation to cheat in any of the ways that a compiler might cheat. - -=head1 Routine modifiers - -B (keyword: C) are routines that can have multiple -variants that share the same name, selected by arity, types, or some -other constraints. - -B (keyword: C) specify the commonalities (such -as parameter names, fixity, and associativity) shared by all multis -of that name in the scope of the C declaration. Abstractly, -the C is a generic wrapper around the dispatch to the Cs. -Each C is instantiated into an actual dispatcher for each scope -that needs a different candidate list. - -B (keyword: C) routines do not share their short names -with other routines. This is the default modifier for all routines, -unless a C of the same name was already in scope. (For subs, -the governing C must have been declared in the same file, so -C declarations from the setting or other modules don't have -this effect unless explicitly imported.) - -A modifier keyword may occur before the routine keyword in a named routine: - - only sub foo {...} - proto sub foo {...} - dispatch sub foo {...} # internal - multi sub foo {...} - - only method bar {...} - proto method bar {...} - dispatch method bar {...} # internal - multi method bar {...} - -If the routine keyword is omitted, it defaults to C. - -Modifier keywords cannot apply to anonymous routines. - -A C is a generic dispatcher, which any given scope with a unique -candidate list will instantiate into a C routine. Hence -a C is never called directly, much like a C can't be -used as an instantiated object. - -When you call any routine (or method, or rule) that may have multiple -candidates, the basic dispatcher is really only calling an "only" -sub or method--but if there are multiple candidates, the "only" that -will be found is really a dispatcher. This instantiated C -is always called first (at least in the abstract--this can often be -optimized away). In essence, a C is dispatched exactly -like an C sub, but the C itself may delegate to any -of the candidates it is "managing". - -It is the C's responsibility to first vet the arguments for all the -candidates; any call that does not successfully bind the C's signature fails outright. -(Its signature is a copy of one belonging to the C from which it was instantiated.) -The C does not necessarily send the original capture to its candidates, however. -Named arguments that bind to positionals in the C sig will become positionals -for all subsequent calls to its managed multis. - -The dispatch then considers its list of managed candidates from the -viewpoint of the caller or object, sorts them into some order, and -dispatches them according to the rules of multiple dispatch as defined -for each of the various dispatchers. In the case of multi subs, the -candidate list is known at compile time. In the case of multi methods, -it may be necessary to generate (or regenerate) the candidate list at -run time, depending on what is known when about the inheritance tree. - -This default dispatch behavior is symbolized within the original -C by a block containing of a single C<*> (that is, a -"whatever"). Hence the typical C will simply have a body -of C<{*}>. - - proto method bar {*} - -(We don't use C<...> for that because it would fail at run time, -and the proto's instantiated C blocks are not stubs, but -are intended to be executed.) - -Other statements may be inserted before and after the C<{*}> -statement to capture control before or after the multi dispatch: - - proto foo ($a,$b) { say "Called with $a $b"; {*}; say "Returning"; } - -(That C is only good for Cs with side effects and no return -value, since it returns the result of C, which might not be what -you want. See below for how to fix that.) - -The syntactic form C<&foo> (without a modifying signature) can never -refer to a C candidate or a generic C. It may only -refer to the single C or C routine that would first -be called by C. Individual Cs may be named by appending -a signature to the noun form: C<&foo:($,$,*@)>. - -We used the term "managed" loosely above to indicate the set of Cs in -question; the "managed set" is more accurately defined as the intersection -of all the Cs in the C's downward scope with all the Cs that -are visible to the caller's upward-looking scope. For ordinary routines -this means looking down lexical scopes and looking up lexical scopes. [This -is more or less how Cs already behave.] - -For methods this means looking down or up the inheritance tree; "managed set" -in this case translates to the intersection of all methods in the C's -class or its subclasses with all C methods visible to the object in its -parent classes, that is, the parent classes of the object's actual type on -whose behalf the method was called. [Note, this is a change from prior -multi method semantics, which restricted multimethods to a single class; -the old semantics is equivalent to defining a C in every class that has -multimethods. The new way gives the user the ability to intermix Cs at -different inheritance levels]. - -Also, the old semantics of C providing the most-default C body -is hereby deprecated. Default Cs should be marked with "C". - -It is still possible to provide default behavior in the C, however, by -using it as a wrapper: - - my proto sub foo (@args) { - do-something-before(@args); - {*} # call into the managed set, then come back - do-something-after(@args); - } - -Note that this returns the value of do-something-after(), not the C. -There are two ways to get around that. Here's one way: - - my proto sub foo (@args) { - ENTER do-something-before(@args); - {*} - LEAVE do-something-after(@args); - } - -Alternately, you can spell out what C<{*}> is actually sugar for, -which would be some dispatcher macro such as: - - my proto sub foo (|cap (@args)) { - do-something-before(@args); - my \retcap = MULTI-DISPATCH-CALLWITH(&?ROUTINE, cap); - do-something-after(@args); - return retcap; - } - -which optimizes (we hope) to an inlined multidispatcher to locate all -the candidates for these arguments (hopefully memoized), create the dynamic -scope of a dispatch, start the dispatch, manage C and C -semantics, and return the result of whichever C succeeded, if any. - -Which is why we have C<{*}> instead. - -Another common variant would be to propagate control to the -outer/higher routine that would have been found if this one didn't -exist: - - my proto method foo { {*}; UNDO nextsame; } # failover to super foo - -Note that, in addition to making Cs work similarly to each other, -the new C semantics greatly simplify top-level dispatchers, which -never have to worry about Cs, because Cs are always in the -second half of the double dispatch (again, just in the abstract, since -the first dispatch can often be optimized away, as if the C were -inlined). So in the abstract, C only ever calls a single -C/C routine, and we know which one it is at compile time. - -This is less of a shift for method dispatch, which already assumed that there -is something like a single proto in each class that redispatches inside -the class. Here the change is that multi-method dispatcher needs to look -more widely for its candidates than the current class. But note that our -semantics were inconsistent before, insofar as regex methods already had to -look for this larger managed set in order to do transitive LTM correctly. -Now the semantics of normal method Cs and regex Cs are nearly -identical, apart from the fact that regex candidate lists naturally have -fancier tiebreaking rules involving longest token matching. - -A C must be generated for every scope that contains one or more C -declaration. This is done by searching backwards and outwards (or up the -inheritance chain for methods) for a C to instantiate. If no such -C is found, a "most generic" C will be generated, something like: - - proto sub foo (*@, *%) {*} - proto method foo (*@, *%) {*} - -Obviously, no named-to-positional remapping can be done in this case. - -[Conjecture: we could instead autogen a more specific signature for -each such autogenerated C once we know its exact candidate -set, such that consistent use of positional parameter names is rewarded -with positional names in the generated signature, which could remap -named parameters.] - -=head2 Named subroutines - -The general syntax for named subroutines is any of: - - my RETTYPE sub NAME ( PARAMS ) TRAITS {...} # lexical only - sub NAME ( PARAMS ) TRAITS {...} # same as "my" - our RETTYPE sub NAME ( PARAMS ) TRAITS {...} # package-scoped - -The return type may also be put inside the parentheses: - - sub NAME (PARAMS --> RETTYPE) {...} - -Unlike in Perl 5, named subroutines are considered expressions, -so this is valid Perl 6: - - my @subs = (sub foo { ... }, sub bar { ... }); - -Another difference is that subroutines default to C scope rather -than C scope. However, subroutine dispatch searches lexical -scopes outward, and subroutines are also allowed to be I -after their use, so you won't notice this much. A subroutine that is -not declared yet may be called using parentheses around the arguments, -in the absence of parentheses, the subroutine call is assumed to take -multiple arguments in the form of a list operator. - -=head2 Anonymous subroutines - -The general syntax for anonymous subroutines is: - - sub ( PARAMS ) TRAITS {...} - -But one can also use the C scope modifier to introduce the return type first: - - anon RETTYPE sub ( PARAMS ) TRAITS {...} - -When an anonymous subroutine will be assigned to a scalar variable, -the variable can be declared with the signature of the routines that -will be assigned to it: - - my $grammar_factory:(Str, int, int --> Grammar); - $grammar_factory = sub (Str $name, int $n, int $x --> Grammar) { ... }; - -Covariance allows a routine (that has a more derived return type than what is -defined in the scalar's signature) to be assigned to that scalar. -Contravariance allows a routine (with parameter types that are less derived -than those in the scalar's signature) to be assigned to that scalar. The -compiler may choose to enforce (by type-checking) such assignments at -compile-time, if possible. Such type annotations are intended to help the -compiler optimize code to the extent such annotations are included and/or to -the extent they aid in type inference. - -The same signature can be used to mark the type of a closure parameter to -another subroutine: - - sub (int $n, &g_fact:(Str, int, int --> Grammar) --> Str) { ... } - -B is the name for a compile-time (C) property. -See L<"Properties and traits">. - - -=head2 Perl5ish subroutine declarations - -You can declare a sub without parameter list, as in Perl 5: - - sub foo {...} - -This is equivalent to one of: - - sub foo () {...} - sub foo (*@_) {...} - sub foo (*%_) {...} - sub foo (*@_, *%_) {...} - -depending on whether either or both of those variables are used in the body of the routine. - -Positional arguments implicitly come in via the C<@_> array, but -unlike in Perl 5 they are C aliases to actual arguments: - - sub say { print qq{"@_[]"\n}; } # args appear in @_ - - sub cap { $_ = uc $_ for @_ } # Error: elements of @_ are read-only - -Also unlike in Perl 5, Perl 6 has true named arguments, which come in -via C<%_> instead of C<@_>. - -If you need to modify the elements of C<@_> or C<%_>, declare the -array or hash explicitly with the C trait: - - sub swap (*@_ is rw, *%_ is rw) { @_[0,1] = @_[1,0]; %_ = "Q:S"; } - -Note: the C container trait is automatically distributed to the -individual elements by the slurpy star even though there is no -actual array or hash passed in. More precisely, the slurpy star -means the declared formal parameter is I considered readonly; only -its elements are. See L below. - -Note also that if the sub's block contains placeholder variables -(such as C<$^foo> or C<$:bar>), those are considered to be formal -parameters already, so in that case C<@_> or C<%_> fill the role of -sopping up unmatched arguments. That is, if those containers are -explicitly mentioned within the body, they are added as slurpy -parameters. This allows you to easily customize your error message -on unrecognized parameters. If they are not mentioned in the body, -they are not added to the signature, and normal dispatch rules will -simply fail if the signature cannot be bound. - -=head2 Blocks - -Raw blocks are also executable code structures in Perl 6. - -Every block defines an object of type C (which C), which may either be -executed immediately or passed on as a C object. How a block is -parsed is context dependent. - -A bare block where an operator is expected terminates the current -expression and will presumably be parsed as a block by the current -statement-level construct, such as an C or C. (If no -statement construct is looking for a block there, it's a syntax error.) -This form of bare block requires leading whitespace because a bare -block where a postfix is expected is treated as a hash subscript. - - -A bare block where a term is expected merely produces a C object. -If the term bare block occurs in a list, it is considered the final -element of that list unless followed immediately by a comma or colon -(intervening C<\h*> or "unspace" is allowed). - -=head2 "Pointy blocks" - -Semantically the arrow operator C<< -> >> is almost a synonym for the -C keyword as used to declare an anonymous subroutine, insofar as -it allows you to declare a signature for a block of code. However, -the parameter list of a pointy block does not require parentheses, -and a pointy block may not be given traits. In most respects, -though, a pointy block is treated more like a bare block than like -an official subroutine. Syntactically, a pointy block may be used -anywhere a bare block could be used: - - my $sq = -> $val { $val**2 }; - say $sq(10); # 100 - - my @list = 1..3; - for @list -> $elem { - say $elem; # prints "1\n2\n3\n" - } - -It also behaves like a block with respect to control exceptions. -If you C from within a pointy block, the block is transparent -to the return; it will return from the innermost enclosing C or -C (et al.), not from the block itself. It is referenced by C<&?BLOCK>, -not C<&?ROUTINE>. - -A normal pointy block's parameters default to C, just like -parameters to a normal sub declaration. However, the double-pointy variant -defaults parameters to C: - - for @list <-> $elem { - $elem++; - } - -This form applies C to all the arguments: - - for @kv <-> $key, $value { - $key ~= ".jpg"; - $value *= 2 if $key ~~ :e; - } - -=head2 Stub declarations - -To predeclare a subroutine without actually defining it, use a "stub block": - - sub foo {...} # Yes, those three dots are part of the actual syntax - -The old Perl 5 form: - - sub foo; - -is a compile-time error in Perl 6 (because it would imply that the body of the -subroutine extends from that statement to the end of the file, as C and -C declarations do). The only allowed use of the semicolon form is to -declare a C
sub--see L below. (And this -form requires the C declarator in front.) - -Redefining a stub subroutine does not produce an error, but redefining -an already-defined subroutine does. If you wish to redefine a defined sub, -you must explicitly use the "C" declarator. (The compiler may -refuse to do this if it has already committed to the previous definition.) - -The C<...> is the "yadayadayada" operator, which is executable but -returns a failure. You can also use C to fail with a warning -(a lazy one, to be issued only if the value is actually used), -or C to always die. These also officially define stub blocks. -Any of these yada operators will be taken as a stub if used as the main -operator of the first statement in the block. (Statement modifiers -are allowed on that statement.) The yada operators differ from their -respective named functions in that they all default to a message -such as: "Unimplemented stub of sub foo was executed". - -It has been argued that C<...> as literal syntax is confusing when -you might also want to use it for metasyntax within a document. -Generally this is not an issue in context; it's never an issue in the -program itself, and the few places where it could be an issue in the -documentation, a comment will serve to clarify the intent, as above. -The rest of the time, it doesn't really matter whether the reader -takes C<...> as literal or not, since the purpose of C<...> is to -indicate that something is missing whichever way you take it. - - -=head2 Globally scoped subroutines - -Subroutines and variables can be declared in the global namespace -(or any package in the global namespace), and are thereafter visible -everywhere in the program via the GLOBAL package (or one of its -subpackages). They may be made directly visible by importation, -but may not otherwise be called with a bare identifier, since subroutine -dispatch only looks in lexical scopes. - -Global subroutines and variables are normally referred to by prefixing -their identifiers with the C<*> twigil, to allow dynamically scoped overrides. - - GLOBAL::<$next_id> = 0; - sub GLOBAL::saith($text) { say "Yea verily, $text" } - - module A { - my $next_id = 2; # hides any global or package $next_id - &*saith($next_id); # print the lexical $next_id; - &*saith($*next_id); # print the dynamic $next_id; - } - -To disallow dynamic overrides, you must access the globals directly: - - GLOBAL::saith($GLOBAL::next_id); - -The fact that this is verbose is construed to be a feature. Alternately, -you may play aliasing tricks like this: - - module B { - import GLOBAL <&saith $next_id>; - saith($next_id); # Unambiguously the global definitions - } - -Despite the fact that subroutine dispatch only looks in lexical scopes, you -can always call a package subroutine directly if there's a lexical alias -to it, as the C declarator does: - - unit module C; - our sub saith($text) { say "Yea verily, $text" } - saith("I do!") # okay - C::saith("I do!") # also okay - -=head2 Dynamically scoped subroutines - -Similarly, you may define dynamically scoped subroutines: - - my sub myfunc ($x) is dynamic { ... } - my sub &*myfunc ($x) { ... } # same thing - -This may then be invoked via the syntax for dynamic variables: - - &*myfunc(42); - -=head2 Lvalue subroutines - -Lvalue subroutines return a "proxy" object that can be assigned to. -It's known as a proxy because the object usually represents the -purpose or outcome of the subroutine call. - -Subroutines are specified as being lvalue using the C trait. - -An lvalue subroutine may return a variable: - - my $lastval; - sub lastval () is rw { return $lastval } - -or the result of some nested call to an lvalue subroutine: - - sub prevval () is rw { return lastval() } - -or a specially tied proxy object, with suitably programmed -C and C methods: - - sub checklastval ($passwd) is rw { - return Proxy.new: - FETCH => method { - return lastval(); - }, - STORE => method ($val) { - die unless check($passwd); - lastval() = $val; - }; - } - -Other methods may be defined for specialized purposes such as temporizing -the value of the proxy. - -=head2 Raw subroutines - -If the subroutine doesn't care whether the returned value is a container or not, -it may declare this with C, to indicate that the return value should -be returned raw, without attempting any decontainerization. This can be useful for -routines that wish to process mixed containers and non-containers without distinction. - -=head2 Operator overloading - -Operators are just subroutines with special names and scoping. -An operator name consists of a grammatical category name followed by -a single colon followed by an operator name specified as if it were -one or more strings. So any of these indicates the same binary addition operator: - - infix:<+> - infix:«+» - infix:<<+>> - infix:['+'] - infix:["+"] - -Use the C<&> sigil just as you would on ordinary subs. - -Unary operators are defined as C or C: - - sub prefix: ($operand) {...} - sub postfix: ($operand) {...} - -Binary operators are defined as C: - - sub infix: ($leftop, $rightop) {...} - -Bracketing operators are defined as C where a term is expected -or C where a postfix is expected. A two-element slice -containing the leading and trailing delimiters is the name of the -operator. - - sub circumfix: ($contents) {...} - sub circumfix:['LEFTDELIM','RIGHTDELIM'] ($contents) {...} - -Contrary to Apocalypse 6, there is no longer any rule about splitting an even -number of characters. You must use a two-element slice. Such names -are canonicalized to a single form within the symbol table, so you -must use the canonical name if you wish to subscript the symbol table -directly (as in C<< PKG::{'infix:<+>'} >>). Otherwise any form will -do. (Symbolic references do not count as direct subscripts since they -go through a parsing process.) The canonical form always uses angle -brackets and a single space between slice elements. The elements -are escaped on brackets, so C<< PKG::circumfix:['<','>'] >> is canonicalized -to C<<< PKG::{'circumfix:<\< \>>'} >>>, and decanonicalizing may always -be done left-to-right. - -Operator names can be any sequence of non-whitespace characters -including Unicode characters. For example: - - sub infix:<(c)> ($text, $owner) { return $text but Copyright($owner) } - method prefix:<±> (Num $x --> Num) { return +$x | -$x } - multi sub postfix: (Int $n) { $n < 2 ?? 1 !! $n*($n-1)! } - - my $document = $text (c) $me; - - my $tolerance = ±7!; - - - -Whitespace may never be part of the name (except as separator -within a C<< <...> >> or C<«...»> slice subscript, as in the example above). - -A null operator name does not define a null or whitespace operator, but -a default matching subrule for that syntactic category, which is useful when -there is no fixed string that can be recognized, such as tokens beginning -with digits. Such an operator I supply an C trait. -The Perl grammar uses a default subrule for the C<:1st>, C<:2nd>, C<:3rd>, -etc. regex modifiers, something like this: - - sub regex_mod_external:<> ($x) is parsed(token { \d+[st|nd|rd|th] }) {...} - -Such default rules are attempted in the order declared. (They always follow -any rules with a known prefix, by the longest-token-first rule.) - -Although the name of an operator can be installed into any package or -lexical namespace, the syntactic effects of an operator declaration are -always lexically scoped. Operators other than the standard ones should -not be installed into the C namespace. Always use exportation to make -non-standard syntax available to other scopes. - -=head1 Calling conventions - -In Perl 6 culture, we distinguish the terms I and -I; a parameter is the formal name that will attach to an -incoming argument during the course of execution, while an argument -is the actual value that will be bound to the formal parameter. -The process of attaching these values (arguments) to their temporary -names (parameters) is known as I. (Some C.S. literature -uses the terms "formal argument" and "actual argument" for these -two concepts, but here we try to avoid using the term "argument" -for formal parameters.) - -Various Perl 6 code objects (either routines or blocks) may be -declared with parameter lists, either explicitly by use of a signature -declaration, or implicitly by use of placeholder variables within the body -of code. (Use of both for the same code block is not allowed.) - -=head1 Signatures - -A signature consists of a list of zero or more parameter declarations, -separated by commas. (These are described below.) Signatures are -usually found inside parentheses (within routine declarations), or -after an arrow C<< -> >> (within block declarations), but other forms -are possible for specialized cases. A signature may also indicate what -the code returns, either generally or specifically. This is indicated -by placing the return specification after a C<< --> >> token. If the -return specification names a type (that is, an indefinite object), -then a successful call to the code must always return a value of -that type. If the return specification returns a definite object, -then that value is always returned from a successful call. (For this -purpose the C value is treated as definite.) An unsuccessful call -may always call C to return a C object regardless of -the return specification. - -Ordinarily, if the return is specified as a type (or is unspecified), -the final statement of the block will be evaluated for its return -value, and this will be the return value of the code block as a whole. -(It must conform to the return type specification, if provided.) -An explicit C may be used instead to evaluate the C's -arguments as the code block's return value, and leave the code block -immediately, short-circuiting the rest of the block's execution. - -If the return specification is a definite immutable value (or C) rather than -a type, then all top-level statements in the code block are evaluated -only for their side effects; in other words, all of the statements are -evaluated in sink context, including the final statement. An explicit -C statement is allowed, but only in argumentless form, to -indicate that execution is to be short-circuited and the I -return value is to be returned. No other value may be returned in -its place. - -If the return specification is definite but not an immutable value, -then it must be a mutable container (variable) of some sort. -The container variable is declared as any other parameter would be, but -no incoming argument will ever be bound to it. It is permitted -to supply a default value, in which case the return variable will -always be initialized with that default value. Like other variables -declared in a signature, a new variable will B be created; any -existing variable will automatically be shadowed. If you want to have -the return variable reference an existing variable, you must resort to -C<< OUTER:: >> hackery. As with value return, all top-level statements -are evaluated in sink context, and only argumentless C is allowed, -indicating that the current contents of the return value should be returned. - -Note that the default return policy assumes functional semantics, with -the result that a loop as the final statement would be evaluated as -a map, which may surprise some people. An implementation is allowed -to warn when it finds such a loop; this warning may be suppressed by -supplying a return specification, which will also determine whether -the final loop statement is evaluated in sink context. - -=head1 Parameters and arguments - -By default, all Scalar parameters are readonly. When a value is passed, it -is simply directly bound to the parameter name. When a scalar is passed, the -value held in the scalar is obtained. It is then assigned into another scalar -container that will, from that point on, be readonly (that is, no further -assignments can be made to it). Implementations may, as an optimization, also -simply bind the value obtained from a passed Scalar if they can prove it is -not Iterable (and therefore elimination of the container would not affect -flattening behavior). - -Array and hash parameters are simply bound "as is". (Conjectural: future -versions of Perl 6 may do static analysis and forbid assignments to array -and hash parameters that can be caught by it. This will, however, only -happen with the appropriate "use" declaration to opt in to that language -version.) - -To allow modification, use the C trait. This requires a mutable -object or container as an argument (or some kind of type object that -can be converted to a mutable object, such as might be returned -by an array or hash that knows how to autovivify new elements). -Otherwise the signature fails to bind, and this candidate routine -cannot be considered for servicing this particular call. (Other multi -candidates, if any, may succeed if they don't require C for this -parameter.) In any case, failure to bind does not by itself cause -an exception to be thrown; that is completely up to the dispatcher. - -To pass-by-copy, use the C trait. An object container will -be cloned whether or not the original is mutable, while an (immutable) -value will be copied into a suitably mutable container. The parameter -may bind to any argument that meets the other typological constraints -of the parameter. - -If you have a readonly scalar parameter C<$ro>, it may never be passed -on to a C scalar parameter of a subcall, since the rw-ness was already -eliminated. A C<$ro> parameter may also not be rebound; trying to do so -results in a compile time error. - -Aliases of C<$ro> are also readonly, whether generated explicitly with C<:=> -or implicitly within a C object (which are themselves immutable). - -Also, C<$ro> may not be returned from an lvalue subroutine or method. - -Parameters may be required or optional. They may be passed by position, -or by name. Individual parameters may confer an item or list context -on their corresponding arguments, but unlike in Perl 5, this is decided -lazily at parameter binding time. - -Arguments destined for required positional parameters must come before -those bound to optional positional parameters. Arguments destined -for named parameters may come before and/or after the positional -parameters. (To avoid confusion it is highly recommended that all -positional parameters be kept contiguous in the call syntax, but -this is not enforced, and custom arg list processors are certainly -possible on those arguments that are bound to a final slurpy or -arglist variable.) - -A signature containing a name collision is considered a compile time -error. A name collision can occur between positional parameters, between -named parameters, or between a positional parameter and a named one. -The sigil is not considered in such a comparison, except in the case of -two positional parameters -- in other words, a signature in which two -or more parameters are identical except for the sigil is still OK (but -you won't be able to pass values by that name). - - :($a, $a) # wrong, two $a - :($a, @a) # OK (but don't do that) - :($a, :a($b)) # wrong, one $a from positional, one $a from named parameter - :($a, :a(@b)) # wrong, same - :(:$a, :@a) # wrong, can only have one named parameter "a" - -=head2 Named arguments - -Named arguments are recognized syntactically at the "comma" level. -Since parameters are identified using identifiers, the recognized -syntaxes are those where the identifier in question is obvious. -You may use either the adverbial form, C<:name($value)>, or the -autoquoted arrow form, C<< name => $value >>. These must occur at -the top "comma" level, and no other forms are taken as named pairs -by default. Pairs intended as positional arguments rather than named -arguments may be indicated by extra parens or by explicitly quoting -the key to suppress autoquoting: - - doit :when,1,2,3; # always a named arg - doit (:when),1,2,3; # always a positional arg - - doit when => 'now',1,2,3; # always a named arg - doit (when => 'now'),1,2,3; # always a positional arg - doit 'when' => 'now',1,2,3; # always a positional arg - -Only bare keys with valid identifier names are recognized as named arguments: - - doit when => 'now'; # always a named arg - doit 'when' => 'now'; # always a positional arg - doit 123 => 'now'; # always a positional arg - doit :123; # always a positional arg - -Going the other way, pairs intended as named arguments that don't look -like pairs must be introduced with the C<|> prefix operator: - - $pair = :when; - doit $pair,1,2,3; # always a positional arg - doit |$pair,1,2,3; # always a named arg - doit |get_pair(),1,2,3; # always a named arg - doit |('when' => 'now'),1,2,3; # always a named arg - -Note the parens are necessary on the last one due to precedence. - -Likewise, if you wish to pass a hash and have its entries treated as -named arguments, you must dereference it with a C<|>: - - %pairs = (:when, :what); - doit %pairs,1,2,3; # always a positional arg - doit |%pairs,1,2,3; # always named args - doit |%(get_pair()),1,2,3; # always a named arg - doit |%('when' => 'now'),1,2,3; # always a named arg - -Variables with a C<:> prefix in rvalue context autogenerate pairs, so you -can also say this: - - $when = 'now'; - doit $when,1,2,3; # always a positional arg of 'now' - doit :$when,1,2,3; # always a named arg of :when - -In other words C<:$when> is shorthand for C<:when($when)>. This works -for any sigil: - - :$what :what($what) - :@what :what(@what) - :%what :what(%what) - :&what :what(&what) - -Ordinary hash notation will just pass the value of the hash entry as a -positional argument regardless of whether it is a pair or not. -To pass both key and value out of hash as a positional pair, use C<:p> -instead: - - doit %hash:p,1,2,3; - doit %hash{'b'}:p,1,2,3; - -The C<:p> stands for "pairs", not "positional"--the C<:p> adverb may be -placed on any C access subscript to make it mean "pairs" instead of "values". -If you want the pair (or pairs) to be interpreted as named arguments, -you may do so by prefixing with the C<< prefix:<|> >> operator: - - doit |(%hash:p),1,2,3; - doit |(%hash{'b'}:p),1,2,3; - -(The parens are required to keep the C<:p> adverb from attaching to C<< prefix:<|> >> operator.) - -C constructors are recognized syntactically at the call level and -put into the named slot of the C structure. Hence they may be -bound to positionals only by name, not as ordinary positional C -objects. Leftover named arguments can be slurped into a slurpy hash. - -Because named and positional arguments can be freely mixed, the -programmer always needs to disambiguate pairs literals from named -arguments with parentheses or quotes: - - # Named argument "a" - push @array, 1, 2, :a; - - # Pair object (a=>'b') - push @array, 1, 2, (:a); - push @array, 1, 2, 'a' => 'b'; - -Perl 6 allows multiple same-named arguments, and records the relative -order of arguments with the same name. When there are more than one -argument, the C<@> sigil in the parameter list causes the arguments -to be appended: - - sub fun (Int :@x) { ... } - fun( x => 1, x => 2 ); # @x := (1, 2) - fun( x => (1, 2), x => (3, 4) ); # @x := (1, 2, 3, 4) - -Other sigils bind only to the I argument with that name: - - sub fun (Int :$x) { ... } - fun( x => 1, x => 2 ); # $x := 2 - fun( x => (1, 2), x => (3, 4) ); # $x := (3, 4) - -This means a hash holding default values must come I known named -parameters, similar to how hash constructors work: - - # Allow "x" and "y" in %defaults to be overridden - f( |%defaults, x => 1, y => 2 ); - -=head2 Invocant parameters - -A method invocant may be specified as the first parameter in the parameter -list, with a colon (rather than a comma) immediately after it: - - method get_name ($self:) {...} - method set_name ($_: $newname) {...} - -The corresponding argument (the invocant) is evaluated in item context -and is passed as the left operand of the method call operator: - - print $obj.get_name(); - $obj.set_name("Sam"); - -The invocant is actually stored as the first positional argument of a C -object. It is special only to the dispatcher, otherwise it's just a normal -positional argument. - -Single-dispatch semantics may also be requested by using the indirect object syntax, with a colon -after the invocant argument. The colon is just a special form of the comma, and has the -same precedence: - - set_name $obj: "Sam"; - $obj.set_name("Sam"); # same as the above - -An invocant is the topic of the corresponding method if that formal -parameter is declared with the name C<$_>. -If you have a call of the form: - - foo(|$capture) - -the compiler must defer the decision on whether to treat it as a method -or function dispatch based on whether the supplied C's first -argument is marked as an invocant. For ordinary calls this can -always be determined at compile time, however. - -=head2 Parameters with type constraints - -Parameters can be constraint to other types than the default simply by -using the type name in from of the parameter: - - sub double(Numeric $x) { 2 * $x } - -If no explicit type constraint is given, it defaults to the type of the -surrounding package for method invocants, and to C everywhere else. - -A bare C<:D>, C<:U> or C<:_> instead of a type constraint limits the default -type to definite objects (aka instances), undefined objects (aka type objects), -or any object, respectively. The default still applies, so in - - class Con { - method man(:U: :D $x) - } - -the signature is equivalent to C<(Con:U: Any:D $x)>. - -=head2 Longname parameters - -A routine marked with C can mark part of its parameters to -be considered in the multi dispatch. These are called I; -see S12 for more about the semantics of multiple dispatch. - -You can choose part of a C's parameters to be its longname, -by putting a double semicolon after the last one: - - multi sub handle_event ($window, $event;; $mode) {...} - multi method set_name ($self: $name;; $nick) {...} - -A parameter list may have at most one double semicolon; parameters -after it are never considered for multiple dispatch (except of course -that they can still "veto" if their number or types mismatch). - -[Conjecture: It might be possible for a routine to advertise multiple -long names, delimited by single semicolons. See S12 for details.] - -If the parameter list for a C contains no semicolons to delimit -the list of important parameters, then all positional parameters are -considered important. If it's a C or C, -an additional implicit unnamed C invocant is added to the -signature list unless the first parameter is explicitly marked with a colon. - - -=head2 Required parameters - -Required parameters are specified at the start of a subroutine's parameter -list: - - sub numcmp ($x, $y) { return $x <=> $y } - -Required parameters may optionally be declared with a trailing C, -though that's already the default for positional parameters: - - sub numcmp ($x!, $y!) { return $x <=> $y } - -Not passing all of the required arguments to a normal subroutine -is a fatal error. Passing a named argument that cannot be bound to a normal -subroutine is also a fatal error. (Methods are different.) - -The number of required parameters a subroutine has can be determined by -calling its C<.arity> method: - - $args_required = &foo.arity; - - -=head2 Optional parameters - -Optional positional parameters are specified after all the required -parameters and each is marked with a C after the parameter: - - sub my_substr ($str, $from?, $len?) {...} - -Alternately, optional fields may be marked by supplying a default value. -The C<=> sign introduces a default value: - - sub my_substr ($str, $from = 0, $len = Inf) {...} - -Default values can be calculated at run-time. They may even use the values of -preceding parameters: - - sub xml_tag ($tag, $endtag = matching_tag($tag) ) {...} - -Arguments that correspond to optional parameters are evaluated in -item context. They can be omitted, passed positionally, or passed by -name: - - my_substr("foobar"); # $from is 0, $len is infinite - my_substr("foobar",1); # $from is 1, $len is infinite - my_substr("foobar",1,3); # $from is 1, $len is 3 - my_substr("foobar",len=>3); # $from is 0, $len is 3 - -Missing optional arguments default to their default values, or to -an undefined value if they have no default. (A supplied argument that is -undefined is not considered to be missing, and hence does not trigger -the default. Use C within the body for that.) - -You may check whether an optional parameter was bound to anything -by calling C. - -=head2 Named parameters - -Named-only parameters follow any required or optional parameters in the -signature. They are marked by a prefix C<:>: - - sub formalize($text, :$case, :$justify) {...} - -This is actually shorthand for: - - sub formalize($text, :case($case), :justify($justify)) {...} - -If the longhand form is used, the label name and variable name can be -different: - - sub formalize($text, :case($required_case), :justify($justification)) {...} - -so that you can use more descriptive internal parameter names without -imposing inconveniently long external labels on named arguments. -Multiple name wrappings may be given; this allows you to give both a -short and a long external name: - - sub globalize (:g(:global($gl))) {...} - -Or equivalently: - - sub globalize (:g(:$global)) {...} - -Arguments that correspond to named parameters are evaluated in item -context. They can only be passed by name, so it doesn't matter what -order you pass them in: - - $formal = formalize($title, case=>'upper'); - $formal = formalize($title, justify=>'left'); - $formal = formalize($title, :justify, :case); - -See S02 for the correspondence between adverbial form and arrow notation. - -While named and position arguments may be intermixed, it is suggested -that you keep all the positionals in one place for clarity unless you -have a good reason not to. This is likely bad style: - - $formal = formalize(:justify<right>, $title, :case<title>, $date); - -Named parameters are optional unless marked with a following C<!>. -Default values for optional named parameters are defined in the same -way as for positional parameters, but may depend only on existing -values, including the values of parameters that have already been -bound. Named optional parameters default to C<Nil> (that is, they -set the default of the container) if they have -no default. Named required parameters fail unless an argument pair -of that name is supplied. - -Bindings logically happen in declaration order, not call order, so -any default may reliably depend on formal parameters to its left in -the signature. - -=head2 List parameters - -List parameters capture a variable length list of data. They're used -in subroutines like C<print>, where the number of arguments needs to be -flexible. They're also called "variadic parameters", because they take a -I<variable> number of arguments. But generally we call them "slurpy" -parameters because they slurp up arguments. - -Slurpy parameters follow any required or optional parameters. They are -marked by a C<*> before the parameter: - - sub duplicate($n, *%flag, *@data) {...} - -Named arguments are bound to the slurpy hash (C<*%flag> -in the above example). Such arguments are evaluated in item context. -Any remaining variadic arguments at the end of the argument list -are bound to the slurpy array (C<*@data> above) and are evaluated -in list context. - -For example: - - duplicate(3, reverse => 1, collate => 0, 2, 3, 5, 7, 11, 14); - duplicate(3, :reverse, :!collate, 2, 3, 5, 7, 11, 14); # same - - # The @data parameter receives [2, 3, 5, 7, 11, 14] - # The %flag parameter receives { reverse => 1, collate => 0 } - -Slurpy scalar parameters capture what would otherwise be the first -elements of the variadic array: - - sub head(*$head, *@tail) { return $head } - sub neck(*$head, *$neck, *@tail) { return $neck } - sub tail(*$head, *@tail) { return @tail } - - head(1, 2, 3, 4, 5); # $head parameter receives 1 - # @tail parameter receives [2, 3, 4, 5] - - neck(1, 2, 3, 4, 5); # $head parameter receives 1 - # $neck parameter receives 2 - # @tail parameter receives [3, 4, 5] - -Slurpy scalars still impose list context on their arguments. - -Single slurpy parameters are treated lazily -- the list is only flattened -into an array when individual elements are actually accessed: - - @fromtwo = tail(1..Inf); # @fromtwo contains a lazy [2..Inf] - -[Conjecture: However, if you use two or more slurpy arrays in a -signature, the list is instead evaluated in hyper context, and will -be asked to split itself into the number of lists corresponding to -the number of slurpies so declared. A non-hyperable list will return -failure for this splitting operation, so the signature should only bind -on parallelizable list operations. Likewise a list that is "too short to -split" fails to bind, so a separate signature may match empty lists, -and perhaps singletons, if we define "too short" that way.] - -You can't bind to the name of a slurpy parameter: the name is just there -so you can refer to it within the body. - - sub foo(*%flag, *@data) {...} - - foo(:flag{ a => 1 }, :data[ 1, 2, 3 ]); - # %flag has elements (flag => (a => 1)) and (data => [1,2,3]) - # @data has nothing - -[Conjecture: a future Perl 6 version will allow typed slurpy parameters, which -will validate the types of the passed arguments.] - -=head2 Slurpy block - -It's also possible to declare a slurpy block: C<*&block>. It slurps -up any nameless block, specified by C<{...}>, at either the current positional -location or the end of the syntactic list. Put it first if you want the -option of putting a block either first or last in the arguments. Put it -last if you want to force it to come in as the last argument. - -=head2 Argument list binding - -The underlying C<Capture> object may be bound to a single -name marked with a C<|>. - - sub bar ($a,$b,$c,:$mice) { say $mice } - sub foo (|args) { say args.perl; &bar.nextwith(|args); } - -This prints: - - foo 1,2,3,:mice<blind>; # says "\(1,2,3,:mice<blind>)" then "blind" - -As demonstrated above, the capture may be interpolated into another -call's arguments. (The C<|> prefix is described below.) -Use of C<nextwith> allows the routine to be called without introducing -an official C<CALLER> frame. For more see "Wrapping" below. - -The C<|> parameter takes a snapshot of the current binding state, but -does not consume any arguments from it. -It is allowed to have more parameters within the signature: - - sub compare (|args, Num $x, Num $y --> Bool) { ... } - -For all normal declarative purposes (invocants and multiple dispatch -types, for instance), capture parameters are ignored. - - method addto (|args, $self: @x) { trace(args); $self += [+] @x } - -The extra signature is not required for non-C<multi>s since there can -only be one candidate, but for multiple dispatch the extra signature -is required at least for its types, or the declaration would not know -what signature to match against. - - multi foo (|args, Int, Bool?, *@, *%)) { reallyintfoo(args) } - multi foo (|args, Str, Bool?, *@, *%)) { reallystrfoo(args) } - -=head2 Term binding - -When you bind an argument to a sigiled variable, it enforces the contract -of that sigil, but sometimes you don't want that. It is possible to bind -an argument to a simple name instead, which represents that argument in -its rawest form, with no commitment to structure or mutability. - - sub foo (\x, \y) { x = y; } # might or might not succeed - -A C<\> parameter effectively declares a new term in the language for -the rest of the current scope, so when you use that term, it is not -parsed as a list operator, so it will not look for any subsequent -arguments. - - sub foo (\x) { x 42; } # syntax error; two terms in a row - -Raw parameters make it relatively easy to program in a "sigilless" style, -if you desire: - - sub say-sins (\angles) { - for angles -> \𝜃 { say sin 𝜃 } - } - -or - - my \𝑖 = some-integer; say 𝑖 + 2; - -Note how C<𝑖> would be misinterpreted if it treated C<+ 2> as an argument, but -since it's a simple term, it doesn't. - -The term does act like a function call in one way, however. Since it returns a -raw value, whether it flattens or not depends on the context in which it is eventually used. -You can use C<< prefix:<|> >> to force flattening into an outer argument list, if -needed. - -It is possible to alias to a non-identifier by using the C<term> syntactic category: - - my \term:<∞> = Inf; - -We sometimes call these "sigilless variables", but they differ from -normal variables in one significant way. Unlike a variable binding, a -term binding is fixed for the rest of the lexical scope. The term may -only be rebound be re-entering the scope. This is useful to enforce a -programming style known as SSA, Single Static Assignment (really binding), -which, among other benefits, gives the optimizer more guarantees about -which symbols can be considered "temporarily immutable". - -=head2 Flattening argument lists - -The unary C<|> operator casts its argument to a C<Capture> -object, then splices that capture into the argument list -it occurs in. To get the same effect on multiple arguments you -can use the C<< |« >> hyperoperator. - -C<Pair> and C<Hash> become named arguments: - - |(x=>1); # Pair, becomes \(x=>1) - |{x=>1, y=>2}; # Hash, becomes \(x=>1, y=>2) - -Anything else that is C<Iterable> is simply turned into -positional arguments: - - |(1,2,3); # List, becomes \(1,2,3) - |(1..3); # Range, becomes \(1,2,3) - |(1..2, 3); # List, becomes \(1..2,3) - |([x=>1, x=>2]); # List (from an Array), becomes \((x=>1), (x=>2)) - -For example: - - sub foo($x, $y, $z) {...} # expects three scalars - @onetothree = 1..3; # array stores three scalars - - foo(1,2,3); # okay: three args found - foo(@onetothree); # error: only one arg - foo(|@onetothree); # okay: @onetothree flattened to three args - -The C<|> operator flattens lazily -- the array is flattened only if -flattening is actually required within the subroutine. To flatten before -the list is even passed into the subroutine, use the C<flat> list -operator: - - foo(|flat 1,2,3 Z 4,5,6); # zip list flattened before interpolation - foo |(1,2,3 Z 4,5,6).flat # same thing - - -=head2 Multidimensional argument list binding - -Some functions take more than one list of positional and/or named arguments, -that they wish not to be flattened into one list. For instance, C<zip()> wants -to iterate several lists in parallel, while array and hash subscripts want to -process a multidimensional slice. The set of underlying argument lists may be -bound to a single array parameter declared with a double C<**> marker: - - sub foo (**@slice) { ... } - -Note that this is different from - - sub foo (|slice) { ... } - -insofar as C<|slice> is bound to a single argument-list object that -makes no commitment to processing its structure (and maybe doesn't -even know its own structure yet), while C<**@slice> has to create -an array that binds the incoming dimensional lists to the array's -dimensions, and make that commitment visible to the rest of the scope -via the sigil so that constructs expecting multidimensional lists -know that multidimensionality is the intention. - -It is allowed to specify a return type: - - sub foo (**@slice --> Num) { ... } - -The invocant does not participate in multi-dimensional argument lists, -so C<self> is not present in the C<**@slice> below: - - method foo (**@slice) { ... } - -The C<**> marker is just a variant of the C<*> marker that ends up -requesting the arguments at the comma-separated syntax level, rather -than requesting individual elements as the flattening C<*> does. - -=head2 Zero-dimensional argument list - -If you call a function without parens and supply no arguments, the -argument list becomes a zero-dimensional slice. It differs from -C<\()> in several ways: - - sub foo (**@slice) {...} - foo; # +@slice == 0 - foo(); # +@slice == 1 - - sub bar (|args = \(1,2,3)) {...} - bar; # $args === \(1,2,3) - bar(); # $args === \() - -=head2 One-argument slurpy binding - -If you use a C<+> character to indicate a slurpy parameter, then it is -assumed that the rest of the positional arguments are intended to be iterated -with "single argument" semantics. That is, we will take whatever is passed -in and iterate the top level of that. If the top level is a comma list, -then it works just as a C<**> slurpy. If the top level is a single argument, -then that will be iterated. - - sub foo (+args) {...} - foo; # +args == 0 - foo(); # +args == 0 - foo((1,2),3,4) # +args == 3 - foo((1,2)) # +args == 2 - foo($(1,2)) # +args == 1 - foo((1,2).item) # +args == 1 - foo([1,2],3,4) # +args == 3 - foo([1,2]) # +args == 2 - foo($[1,2]) # +args == 1 - foo([1,2].item) # +args == 1 - -Basically, this slurpy doesn't care whether the list you hand it was made -by syntactic commas or by some other means. The other slurpies treat -syntactic commas as dominant even when there aren't any! - -=head2 Feed operators - -The variadic list of a subroutine call can be passed in separately from -the normal argument list, by using either of the I<feed> operators: -C<< <== >> or C<< ==> >>. Syntactically, feed operators expect to find a -statement on either end. Any statement can occur on the source end; -however not all statements are suitable for use on the sink end of a feed. - -Each operator expects to find a call to a variadic receiver on its -"sharp" end, and a list of values on its "blunt" end: - - grep { $_ % 2 } <== @data; - - @data ==> grep { $_ % 2 }; - -It binds the (potentially lazy) list from the blunt end to the slurpy -parameter(s) of the receiver on the sharp end. In the case of a receiver -that is a variadic function, the feed is received as part of its slurpy list. -So both of the calls above are equivalent to: - - grep { $_ % 2 }, @data; - -Note that all such feeds (and indeed all lazy argument lists) supply -an implicit promise that the code producing the lists may execute -in parallel with the code receiving the lists. (Feeds, hyperops, -and junctions all have this promise of parallelizability in common, -but differ in interface. Code which violates these promises is -erroneous, and will produce undefined results when parallelized.) - -However, feeds go a bit further than ordinary lazy lists in enforcing -the parallel discipline: they explicitly treat the blunt end as a -cloned closure that starts a subthread (presumably cooperative). The only variables shared -by the inner scope with the outer scope are those lexical variables -declared in the outer scope that are visible at the time the closure is -cloned and the subthread spawned. Use of such shared variables will -automatically be subject to transactional protection (and associated -overhead). Package variables are not cloned unless predeclared -as lexical names with C<our>. Variables declared within the blunt -end are not visible outside, and in fact it is illegal to declare a -lexical on the blunt end that is not enclosed in curlies somehow. - -Because feeds are defined as lazy pipes, a chain of feeds may not begin -and end with the same array without some kind of eager sequence point. -That is, this isn't guaranteed to work: - - @data <== grep { $_ % 2 } <== @data; - -either of these do: - - @data <== grep { $_ % 2 } <== eager @data; - @data <== eager grep { $_ % 2 } <== @data; - -Conjecture: if the cloning process eagerly duplicates C<@data>, it could -be forced to work. Not clear if this is desirable, since ordinary clones -just clone the container, not the value. - -Leftward feeds are a convenient way of explicitly indicating the typical -right-to-left flow of data through a chain of operations: - - @oddsquares = map { $_**2 }, sort grep { $_ % 2 }, @nums; - - # perhaps more clearly written as... - - @oddsquares = do { - map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums; - } - -Rightward feeds are a convenient way of reversing the normal data flow in a -chain of operations, to make it read left-to-right: - - @oddsquares = do { - @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 }; - } - -Note that something like the C<do> is necessary because feeds operate -at the statement level. Parens would also work, since a statement is -expected inside: - - @oddsquares = ( - @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 }; - ); - -But as described below, you can also just write: - - @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> @oddsquares; - -If the operand on the sharp end of a feed is not a call to a variadic -operation, it must be something else that can be interpreted as a list -receiver, or a scalar expression that can be evaluated to produce an -object that does the C<KitchenSink> role, such as an C<IO> object. -Such an object provides C<.clear> and C<.push> methods that will -be called as appropriate to send data. (Note that an C<IO> object -used as a sink will force eager evaluation on its pipeline, so the -next statement is guaranteed not to run till the file is closed. -In contrast, an C<Array> object used as a sink turns into a lazy -array.) - -Any non-variadic object (such as an C<Array> or C<IO> object) used as a filter -between two feeds is treated specially as a I<tap> that merely captures -data I<en passant>. You can safely install such a tap in an extended pipeline -without changing the semantics. An C<IO> object used as a tap does not -force eager evaluation since the eagerness is controlled instead by the -downstream feed. - -Any prefix list operator is considered a variadic operation, so ordinarily -a list operator adds any feed input to the end of its list. -But sometimes you want to interpolate elsewhere, so any contextualizer -with C<*> as an argument may be used to indicate the target of a -feed without the use of a temporary array: - - foo() ==> say @(*), " is what I meant"; - bar() ==> @(*).baz(); - -Likewise, an C<Array> used as a tap may be distinguished from an C<Array> used -as a translation function: - - numbers() ==> @array ==> bar() # tap - numbers() ==> @array[@(*)] ==> bar() # translation - -To append multiple sources to the next sink, double the angle: - - my $sink; - 0..* ==> $sink; - 'a'..* ==>> $sink; - pidigits() ==>> $sink; - - # outputs "(0, 'a', 3)\n"... - for $sink.zip { .perl.say } - -Each such append adds another slice element to the sink. - -You may use a variable (or variable declaration) as a receiver, in -which case the list value is bound as the "todo" of the variable. -(The append form binds addition todos to the receiver's todo list.) -Do not think of it as an assignment, nor as an ordinary binding. -Think of it as iterator creation. In the case of a scalar variable, -that variable contains the newly created iterator itself. In the case -of an array, the new iterator is installed as the method for extending -the array. As with assignment, the old todo list is clobbered; use the -append form to avoid that and get push semantics. In any case, feeding -an array always flattens. You must use the scalar form to preserve -slice information. - -In general you can simply think of a receiver array as representing -the results of the chain, so you can equivalently write any of: - - my @oddsquares <== map { $_**2 } <== sort <== grep { $_ % 2 } <== @nums; - - my @oddsquares - <== map { $_**2 } - <== sort - <== grep { $_ % 2 } - <== @nums; - - @nums ==> grep { $_ % 2 } ==> sort ==> map { $_**2 } ==> my @oddsquares; - - @nums - ==> grep { $_ % 2 } - ==> sort - ==> map { $_**2 } - ==> my @oddsquares; - -Since the feed iterator is bound into the final variable, the variable -can be just as lazy as the feed that is producing the values. - -When feeds are bound to arrays with "push" semantics, you can have -a receiver for multiple feeds: - - my @foo; - 0..2 ==> @foo; - 'a'..'c' ==>> @foo; - say @foo; # 0,1,2,'a','b','c' - -Note how the feeds are concatenated in C<@foo> so that C<@foo> -is a list of 6 elements. This is the default behavior. However, -sometimes you want to capture the outputs as a list of two iterators, -namely the two iterators that represent the two input feeds. You can -get at those two iterators by using a scalar instead, which -will preserve the slice structure, which can be fed to any operation -that knows how to deal with a list of values as a slice, such as C<zip>: - - 0..* ==> $foo; - 'a'..* ==>> $foo; - pidigits() ==>> $foo; - - for $foo.zip { .say } - - [0,'a',3] - [1,'b',1] - [2,'c',4] - [3,'d',1] - [4,'e',5] - [5,'f',9] - ... - -Here C<$foo> is a list of three lists, so - - $foo.zip - -is equivalent to - - my (@a,@b,@c) := |$foo; - zip(@a; @b; @c) - -A named receiver array is useful when you wish to feed into an -expression that is not an ordinary list operator, and you wish to be -clear where the feed's destination is supposed to be: - - picklist() ==> my @baz; - my @foo = @bar[@baz]; - -Various contexts may or may not be expecting multi-dimensional slices -or feeds. By default, ordinary arrays are flattened in slurpy context, that is, they -have "list" semantics. If you say - - zip(0..2; 'a'..'c') ==> my @tmp; - for @tmp { .say } - -then you get 0,1,2,'a','b','c'. If you have a multidimensional array, you -can ask for flattening semantics explicitly with C<flat>: - - zip(0..2; 'a'..'c') ==> my $tmp; - for $tmp.flat { .say } - -As we saw earlier, "zip" produces an interleaved result by taking one element -from each list in turn, so - - zip(0..2; 'a'..'c') ==> my $tmp; - for $tmp.zip { .say } - -produces 0,'a',1,'b',2,'c'. - -If you want the zip's result as a list of subarrays, then you need to put -the zip itself into a "chunky" C<LoL> context instead: - - zip(0..2; 'a'..'c') ==> my $tmp; - for $tmp.zip.lol { .say } - -This produces two values on each line. But usually you want the flat -form so you can just bind it directly to a signature: - - for $tmp.zip -> $i, $a { say "$i: $a" } - -Otherwise you'd have to say this: - - for $tmp.zip.lol -> [$i, $a] { say "$i: $a" } - -Note that with the current definition, the order of feeds is preserved -left to right in general regardless of the position of the receiver. - -So - - ('a'..*; 0..*) ==> $feed; - for $feed.zip <== @foo) -> $a, $i, $x { ... } - -is the same as - - 'a'..* ==> $feed; - 0..* ==>> $feed; - for $feed.zip <== @foo) -> $a, $i, $x { ... } - -which is the same as - - for zip('a'..*; 0..*; @foo) -> $a, $i, $x { ... } - -Also note that these come out to be identical for ordinary arrays: - - @foo.zip - @foo.cat - -=head2 Closure parameters - -Parameters declared with the C<&> sigil take blocks, closures, or -subroutines as their arguments. Closure parameters can be required, -optional, named, or slurpy. - - sub limited_grep (Int $count, &block, *@list) {...} - - # and later... - - @first_three = limited_grep 3, {$_<10}, @data; - -(The comma is required after the closure.) - -Within the subroutine, the closure parameter can be used like any other -lexically scoped subroutine: - - sub limited_grep (Int $count, &block, *@list) { - ... - if block($nextelem) {...} - ... - } - -The closure parameter can have its own signature in a type specification written -with C<:(...)>: - - sub limited_Dog_grep ($count, &block:(Dog), *@list) {...} - -and even a return type: - - sub limited_Dog_grep ($count, &block:(Dog --> Bool), *@list) {...} - -When an argument is passed to a closure parameter that has this kind of -signature, the argument must be a C<Code> object with a compatible -parameter list and return type. - -=head2 En passant type capture - -Unlike normal parameters, type parameters often come in piggybacked -on the actual value as "kind", and you'd like a way to capture both -the value and its kind at once. (A "kind" is a storage type, that is, a class or type that -an object is allowed to be. An object is not officially allowed -to take on a constrained or contravariant type.) A type variable -can be used anywhere a type name can, but instead of asserting that -the value must conform to a particular type, it captures the -actual "kind" of the object and also declares a package/type name -by which you can refer to that kind later in the signature or body. -In addition, it captures the nominal typing of any associated nominal -type. -For instance, if you wanted to match any two Dogs as long as they -were of the same kind, you can say: - - sub matchedset (Dog ::T $fido, T $spot) {...} - -This actually turns into something more like - - sub matchedset (Dog ::T $fido, Dog $spot where T) {...} - -Note that C<::T> is not required to contain C<Dog>, only -a type that is compatible with C<Dog>. Note also that the nominal -type, C<Dog>, is also included in the meaning of C<T>, along -with the notion that the actual type must match the storage -type of C<$fido>. - -The C<::> quasi-sigil is short for "subset" in much the same way that C<&> is -short for "sub". Just as C<&> can be used to name any kind of code, -so too C<::> can be used to name any kind of type. Both of them insert -a bare identifier into the symbol table, though they fill different syntactic -spots. - -Note that it is not required to capture the object associated with the -class unless you want it. The sub above could be written as - - sub matchedset (Dog ::T, T) {...} - -if we're not interested in C<$fido> or C<$spot>. Or just - - sub matchedset (::T, T) {...} - -if we don't care about anything but the matching. Note here that -the second parameter may be more derived than the first. If you -need them to be identical, you must say something like - - sub matchedset (::T, $ where { $_.WHAT === T } - -=head2 Unpacking array parameters - -Instead of specifying an array parameter as an array: - - sub quicksort (@data, $reverse?, $inplace?) { - my $pivot := shift @data; - ... - } - -it may be broken up into components in the signature, by -specifying the parameter as if it were an anonymous array of -parameters: - - sub quicksort ([$pivot, *@data], $reverse?, $inplace?) { - ... - } - -This subroutine still expects an array as its first argument, just like -the first version. - -=head2 Unpacking a single list argument - -To match the first element of the slurpy list, use a "slurpy" scalar: - - sub quicksort (:$reverse, :$inplace, *$pivot, *@data) - -=head2 Unpacking tree node parameters - -You can unpack hash values and tree nodes in various dwimmy ways by enclosing the bindings -of child nodes and attributes in parentheses following the declaration of -the node itself: - - sub traverse ( BinTree $top ( $left, $right ) ) { - traverse($left); - traverse($right); - } - -In this, C<$left> and C<$right> are automatically bound to the left -and right nodes of the tree. If C<$top> is an ordinary object, it binds -the C<$top.left> and C<$top.right> attributes. If it's a hash, -it binds C<< $top<left> >> and C<< $top<right> >>. If C<BinTree> is a -signature type and $top is a C<Capture> (argument list) object, the child types -of the signature are applied to the actual arguments in the argument -list object. (Signature types have the benefit that you can view -them inside-out as constructors with positional arguments, such that -the transformations can be reversible.) - -However, the full power of signatures can be applied to pattern match -just about any argument or set of arguments, even though in some cases -the reverse transformation is not derivable. For instance, to bind to -an array of children named C<.kids> or C<< .<kids> >>, use something -like: - - proto traverse ($) {*} - multi traverse ( NAry $top ( :kids [$eldest, *@siblings] ) ) { - traverse($eldest); - traverse(:kids(@siblings)); # (binds @siblings to $top) - } - multi traverse ( $leaf ) {...} - -The second candidate is called only if the parameter cannot be bound to -both C<$top> and to the "kids" parsing subparameter. - -Likewise, to bind to a hash element of the node and then bind to -keys in that hash by name: - - sub traverse ( AttrNode $top ( :%attr{ :$vocalic, :$tense } ) ) { - say "Has {+%attr} attributes, of which"; - say "vocalic = $vocalic"; - say "tense = $tense"; - } - -You may omit the top variable if you prefix the parentheses with a colon -to indicate a signature. Otherwise you must at least put the sigil of -the variable, or we can't correctly differentiate: - - my Dog ($fido, $spot) := twodogs(); # list of two dogs - my Dog $ ($fido, $spot) := twodogs(); # one twodog object - my Dog :($fido, $spot) := twodogs(); # one twodog object - -Sub signatures can be matched directly within regexes by using C<:(...)> -notation. - - push @a, "foo"; - push @a, \(1,2,3); - push @a, "bar"; - ... - my ($i, $j, $k); - @a ~~ rx/ - <,> # match initial elem boundary - :(Int $i,Int $j,Int? $k) # match lists with 2 or 3 ints - <,> # match final elem boundary - /; - say "i = $<i>"; - say "j = $<j>"; - say "k = $<k>" if defined $<k>; - -If you want a parameter bound into C<$/>, you have to say C<< $<i> >> -within the signature. Otherwise it will try to bind an external C<$i> -instead, and fail if no such variable is declared. - -Note that unlike a sub declaration, a regex-embedded signature has no -associated "returns" syntactic slot, so you have to use C<< --> >> -within the signature to specify the C<of> type of the signature, or match as -an arglist: - - :(Num, Num --> Coord) - :(\Coord(Num, Num)) - -A consequence of the latter form is that you can match the type of -an object with C<:(\Dog)> without actually breaking it into its components. -Note, however, that it's not equivalent to say - - :(--> Dog) - -which would be equivalent to - - :(\Dog()) - -that is, match a nullary function of type C<Dog>. Nor is it equivalent to - - :(Dog) - -which would be equivalent to - - :(\Any(Dog)) - -and match a function taking a single parameter of type Dog. - -Note also that bare C<\(1,2,3)> is never legal in a regex since the -first (escaped) paren would try to match literally. - -=head2 Attributive parameters - -If a submethod's parameter is declared with a C<.> or C<!> after the -sigil (like an attribute): - - submethod initialize($.name, $!age) {} - -then the argument is bound directly to the object's attribute of the -same name. This avoids the frequent need to write code like: - - submethod initialize($name, $age) { - $.name = $name; - $!age = $age; - } - -The initialization of attributes requires special care to preserve -encapsulation; therefore the default for attributive parameters is -value semantics, that is, as if specified with C<is copy>. Hence, -the submethod above is really more like: - - submethod initialize($name is copy, $age is copy) { - $.name := $name; # or maybe = here, since it's a parent's attr - $!age := $age; # or maybe only $! parameters work really - } - -If you wish to allow the user to initialize an attribute by reference, -you may either write your own initializer submethod explicitly, or -simply mark the attributes you want to work that way with C<is raw>: - - has $!age is raw; # BUILD will automatically use binding, not copy - -To rename an attribute parameter you can use the explicit pair form: - - submethod initialize(:moniker($.name), :youth($!age)) {} - -The C<:$name> shortcut may be combined with the C<$.name> shortcut, -but the twigil is ignored for the parameter name, so - - submethod initialize(:$.name, :$!age) {} - -is the same as: - - submethod initialize(:name($.name), :age($!age)) {} - -Note that C<$!age> actually refers to the private "C<has>" variable that -can be referred to as either C<$age> or C<$!age>. - -=head2 Placeholder variables - -Even though every bare block is a closure, bare blocks can't have -explicit parameter lists. Instead, they use "placeholder" variables, -marked by a caret (C<^>) or a colon (C<:>) after their sigils. -The caret marks positional placeholders, while the colon marks named -placeholders. - -Using placeholders in a block defines an implicit parameter list. The -signature is the list of distinct positional placeholder names, -sorted in Unicode order, following by the named placeholder names in -any order. So: - - { say "woof" if $:dog; $^y < $^z && $^x != 2 } - -is a shorthand for: - - -> $x,$y,$z,:$dog { say "woof" if $dog; $y < $z && $x != 2 } - -Note that placeholder variables syntactically cannot have type constraints. -Also, it is illegal to use placeholder variables in a block that already -has a signature, because the autogenerated signature would conflict with that. -Positional placeholder names consisting of a single uppercase letter are disallowed, -not because we're mean, but because it helps us catch references to -obsolete Perl 5 variables such as C<$^O>. - -The C<$_> variable functions as a placeholder in a block without any -other placeholders or signature. Any bare block without placeholders -really has a parameter like this: - - -> $_ is raw = OUTER::<$_> { .mumble } - -(However, statement control C<if> notices this and passes no argument, -so C<$_> ends up being bound to the outer C<$_> anyway.) - -A block may also refer to either C<@_> or C<%_> or both, each of -which will be added to generated signature as a normal readonly -slurpy parameter: - - { say $:what; warn "bad option: $_\n" for keys %_; } - -turns into - - -> :$what, *%_ { say $what; warn "bad option: $_\n" for keys %_; } - -If not used, they are not added, and a dispatch with mispatched parameters will fail. - -The use of a P5ish C<@_> in a signatureless sub falls naturally out of this: - - sub sayall { .say for @_ } - -Note that in this case, C<$_> is not treated as a placeholder because -there is already the C<@_> placeholder. And C<@_> is a placeholder -only because the sub has no official signature. Otherwise it would -be illegal (unless explicitly declared). - -Placeholders may also be used in method bodies that have no -formal signature. The invocant is always removed first, so the -first placeholder argument always refers to the first non-invocant -argument. C<@_> will never contain the invocant. The invocant is -always available via C<self>, of course. - -Since the placeholder declares a parameter variable without the twigil, -the twigil is needed only on the first occurrence of the variable within -the block. Subsequent mentions of that variable may omit the twigil. -Within an internal nested block the twigil I<must> be omitted, since -it would wrongly attach to the inner block. - -Note that, unlike in Perl 5, C<@_> may not be used within an inner block to -refer to the outer block's arguments: - - sub say-or-print { - if $SAYIT { - say @_; # WRONG - } - else { - print @_; # WRONG - } - } - -because this desugars to: - - sub say-or-print { - if $SAYIT -> *@_ { - say @_; - } - else -> *@_ { - print @_; - } - } - -Translators of Perl 5 will need to bear this in mind. - -=head1 Properties and traits - -Compile-time properties are called "traits". The -C<is I<NAME> (I<DATA>)> syntax defines traits on containers and -subroutines, as part of their declaration: - - constant $pi is Approximated = 3; # variable $pi has Approximated trait - - my $key is Persistent(:file<.key>); - - sub fib is cached {...} - -The C<will I<NAME> I<BLOCK>> syntax is a synonym for C<is I<NAME> (I<BLOCK>)>: - - my $fh will undo { close $fh }; # Same as: my $fh is undo({ close $fh }); - -The C<but I<NAME> (I<DATA>)> syntax specifies run-time properties on values: - - constant $pi = 3 but Inexact; # value 3 has Inexact property - - sub system { - ... - return $error but False if $error; - return 0 but True; - } - -Properties are predeclared as roles and implemented as mixins--see S12. - -=head2 Subroutine traits - -These traits may be declared on the subroutine as a whole (individual -parameters take other traits). Trait syntax depends on the particular -auxiliary you use, but for C<is>, the subsequent syntax is identical to -adverbial syntax, except that that colon may be omitted or doubled depending -on the degree of ambiguity desired: - - sub x() is ::Foo[...] # definitely a parameterized typename - sub x() is :Foo[...] # definitely a pair with a list - sub x() is Foo[...] # depends on whether Foo is predeclared as type - -=over - -=item C<is signature> - -The signature of a subroutine. Normally declared implicitly, by providing a -parameter list and/or return type. - -=item C<as>/C<is as> - -The C<inner> type constraint that a routine imposes on its return value. - -=item C<of>/C<is of> - -The C<of> type that is the official return type of the routine. Or you -can think of "of" as outer/formal. If there is no inner type, the outer -type also serves as the inner type to constrain the return value. - -=item C<will do> - -The block of code executed when the subroutine is called. Normally declared -implicitly, by providing a block after the subroutine's signature definition. - -=item C<is rw> - -Marks a subroutine as returning an lvalue. - -=item C<is raw> - -Marks a subroutine as returning a raw alias. - -=item C<is parsed> - -Specifies the subrule by which a macro call is parsed. The parse -always starts after the macro's initial token. If the operator has -two parts (circumfix or postcircumfix), the final token is also automatically -matched, and should not be matched by the supplied regex. - -[This trait and the following are likely to be deprecated in favor -of slang macros that are aware of the grammar and category in which -they are installed, and that therefore already know how to parse like -normal grammar rules. The actions of slang macros, however, will be -more targeted toward user-level AST production and manipulation through -use of quasi quoting and unquoting, as well as through direct access to -some as-yet-unspecified high-level, VM-independent AST representation.] - -=item C<is reparsed> - -Also specifies the subrule by which a macro call is parsed, but restarts -the parse before the macro's initial token, usually because you want -to parse using an existing rule that expects to traverse the initial -token. If the operator has two parts (circumfix or postcircumfix), the -final token must also be explicitly matched by the supplied regex. - -=item C<is cached> - -Marks a subroutine as being memoized, or at least memoizable. -In the abstract, this cache is just a hash where incoming argument -C<Capture>s are mapped to return values. If the C<Capture> is found in -the hash, the return value need not be recalculated. If you use -this trait, the compiler will assume two things: - -=over - -=item * - -A given C<Capture> would always calculate the same return value. That is, -there is no state hidden within the dynamic scope of the call. - -=item * - -The cache lookup is likely to be more efficient than recalculating -the value in at least some cases, because either most uncached calls -would be slower (and reduce throughput), or you're trying to avoid a -significant number of pathological cases that are unacceptably slow -(and increase latency). - -=back - -This trait is a suggestion to the compiler that caching is okay. The -compiler is free to choose any kind of caching algorithm (including -non-expiring, random, lru, pseudo-lru, or adaptive algorithms, or -even no caching algorithm at all). The run-time system is free to -choose any kind of maximum cache size depending on the availability -of memory and trends in usage patterns. You may suggest a particular -cache size by passing a numeric argument (representing the maximum number -of unique C<Capture> values allowed), and some of the possible -algorithms may pay attention to it. You may also pass C<*> for the -size to request a non-expiring cache (complete memoization). The -compiler is free to ignore this too. - -The intent of this trait is to specify performance hints without -mandating any exact behavior. Proper use of this trait should not -change semantics of the program; it functions as a kind of "pragma". -This trait will not be extended to reinvent other existing ways of -achieving the same effect. To gain more control, write your own -trait handler to allow the use of a more specific trait, such as -"C<is lru(42)>". Alternately, just use a state hash keyed on the -sub's argument capture to write your own memoization with complete -control from within the subroutine itself, or from within a wrapper -around your subroutine. - -=item C<is tighter>/C<is looser>/C<is equiv> - -Specifies the precedence of an operator relative to an existing -operator. C<tighter> and C<looser> precedence levels default to -being left associative. They define a new precedence level slightly -tighter or looser than the precedence level on which they're based. -Both C<tighter> and C<looser> may be specified, in which case the new -precedence level is generated midway between the specified levels. - -Two different declarations using the same precedence derivation end -up at the same precedence level, as if C<equiv> was specified instead -of C<tighter>/C<looser>, and the second will clone the associativity -of the first. If the second explicitly specifies an associativity -that differs from the first, unexpected parsing conflicts may result. -(See S03.) - -In addition to cloning the precedence level, -C<equiv> also clones other traits, so it specifies -the default associativity to be the same as the operator to which -the new operator is equivalent. The following are the default -equivalents for various syntactic categories if neither C<equiv> nor -C<assoc> is specified. (Many of these have no need of precedence -or associativity because they are parsed specially. Nevertheless, -C<equiv> may be useful for cloning other traits of these operators.) - - category:<prefix> - circumfix:<( )> - dotty:<.> - infix:<+> - infix_circumfix_meta_operator:['»','«'] - infix_postfix_meta_operator:<=> - infix_prefix_meta_operator:<!> - package_declarator:<class> - postcircumfix:<( )> - postfix:<++> - postfix_prefix_meta_operator:['»'] - prefix:<++> - prefix_circumfix_meta_operator:['[',']'] - prefix_postfix_meta_operator:['«'] - q_backslash:<\\> - qq_backslash:<n> - quote_mod:<c> - quote:<q> - regex_assertion:<?> - regex_backslash:<w> - regex_metachar:<.> - regex_mod_internal:<i> - routine_declarator:<sub> - scope_declarator:<my> - sigil:<$> - special_variable:<$!> - statement_control:<if> - statement_mod_cond:<if> - statement_mod_loop:<while> - statement_prefix:<do> - term:<*> - trait_mod:<is> - trait_verb:<of> - twigil:<?> - type_declarator:<subset> - version:<v> - -The existing operator may be specified either as a function object -or as a string argument equivalent to the one that would be used in -the complete function name. In string form the syntactic -category will be assumed to be the same as the new declaration. -Therefore these all have the same effect: - - sub postfix:<!> ($x) is equiv(&postfix:<++>) {...} - sub postfix:<!> ($x) is equiv<++> {...} - sub postfix:<!> ($x) {...} # since equiv<++> is the default - -Prefix operators that are identifiers are handled specially. The -form with one argument defaults to named unary precedence -instead of autoincrement precedence: - - sub prefix:<foo> ($x) {...} - foo 1, 2, 3; # means foo(1), 2, 3 - -Likewise postfix operators that look like method calls are forced to -default to the precedence of method calls. Any prefix operator that -requires multiple arguments defaults to listop precedence, even if it -is not an identifier: - - sub prefix:<☎> ($x,$y) {...} - ☎ 1; # ERROR, too few arguments - ☎ 1, 2; # okay - ☎ 1, 2, 3; # ERROR, too many arguments - -You must use the C<< prefix:<foo> >> form in order to mutate -the grammar to parse as a named unary operator. Normal function -definitions never change the grammar, and when called always parse -as listops, even if defined with a single argument: - - sub foo ($x) {...} # a listop - foo(1), 2, 3; # okay - (foo 1), 2, 3; # okay - foo 1, 2, 3; # ERROR, too many arguments - -Likewise 0-ary functions parse as listops. Use C<< term:<foo> >> -(or a constant or enum declaration) to declare a term that expects -no arguments. - -Because these traits have an immediate declarative effect, it is -illegal to apply them to a C<multi>, or to any post-declared function. -More generally, any such language-bending declaration must follow -the same lexical scoping rules that a macro does. - -=item C<is assoc> - -Specifies the associativity of an operator explicitly. Valid values are: - - Tag Examples Meaning of $a op $b op $c Default equiv - === ======== ========================= ============= - left + - * / x ($a op $b) op $c + - right ** = $a op ($b op $c) ** - non cmp <=> .. ILLEGAL cmp - chain == eq ~~ ($a op $b) and ($b op $c) eqv - list | & ^ Z op($a; $b; $c) | - -Note that operators "C<equiv>" to relationals are automatically considered -chaining operators. When creating a new precedence level, the chaining -is determined by the presence or absence of "C<< is assoc<chain> >>", -and other operators defined at that level are required to be the same. - -Specifying an C<assoc> without an explicit C<equiv> substitutes a default -C<equiv> consistent with the associativity, as shown in the final column above. - -Because this trait has an immediate declarative effect, it is illegal -to apply it to a C<multi>, or to any post-declared function. - -=item C<PRE>/C<POST> - -These phasers declare statements or blocks that are to be unconditionally -executed before/after the subroutine's C<do> block. They must return -a true value, otherwise an exception is thrown. - -When applied to a method, the semantics provide support for the -"Design by Contract" style of OO programming: a precondition of -a particular method is met if all the C<PRE> phasers associated -with that method return true. Otherwise, the precondition is met -if C<all> of the parent classes' preconditions are met (which may -include the preconditions of I<their> parent classes if they fail, -and so on recursively.) - -In contrast, a method's postcondition is met if all the method's C<POST> phasers -return true I<and> all its parents' postconditions are also met recursively. - -C<POST> phasers (and "C<will post>" phaser traits) declared within a C<PRE> -or C<ENTER> block are automatically hoisted outward to be called at the -same time as other C<POST> phasers. This conveniently gives "circum" -semantics by virtue of wrapping the post lexical scope within the pre -lexical scope. That is, the C<POST> closes over its outer scope, even -if that scope is gone by the time the C<POST> is run. - - method push ($new_item) { - ENTER { - my $old_height = self.height; - POST { self.height == $old_height + 1 } - } - - $new_item ==> push @.items; - } - - method pop () { - ENTER { - my $old_height = self.height; - POST { self.height == $old_height - 1 } - } - - return pop @.items; - } - -Note that C<self> is available in phasers defined within methods. - -Class invariants are declared with C<PRE>/C<POST> submethods instead of phasers. - -Module invariants are declared with C<PRE>/C<POST> subs or protos. - -[Conjecture: class and module invariants can applied more selectively -by marking C<PRE>/C<POST> declarations with a C<selective> trait that -stops it from running on internal calls (which might allow temporary -violations of invariants), but enforces the invariants when any routine -of this module is called from "outside" the current module or type, -however that's defined. There could be arguments to this trait that -could refine the concept of what is foreign.] - -=item C<ENTER>/C<LEAVE>/C<KEEP>/C<UNDO>/etc. - -These phasers supply code that is to be conditionally executed before or -after the subroutine's C<do> block (only if used at the outermost level -within the subroutine; technically, these are added to the block traits on the C<do> -block, not the subroutine object). These phasers are generally used only -for their side effects, since most return values will be ignored. (Phasers -that run before normal execution may be used for their values, however.) - -=back - - -=head2 Parameter traits - -The following traits can be applied to many types of parameters. - -=over - -=item C<is readonly> - -Specifies that the parameter cannot be modified (e.g. assigned to, -incremented). It is the default for parameters. On arguments which -are already immutable values it is a no-op at run time; on mutable -containers it may need to create an immutable alias to the mutable object -if the constraint cannot be enforced entirely at compile time. Binding -to a readonly parameter never triggers autovivification. - -=item C<is rw> - -Specifies that the parameter can be modified (assigned to, incremented, -etc). Requires that the corresponding argument is an lvalue or can be -converted to one. Since this option forces an argument to be required, -it cannot coexist with the C<?> mark to make an argument optional. -(It may, however, be used with C<=> indicating a default, but only -if the default expression represents something that is nameable at -compile time and that can bind as an lvalue, such as -C<< CALLER::<$/> >> or C<< OUTER::<$_> >>.) - -When applied to a variadic parameter, the C<rw> trait applies to each -element of the list: - - sub incr (*@vars is rw) { $_++ for @vars } - -(The variadic array as a whole is always modifiable, but such -modifications have no effect on the original argument list.) - -=item C<is raw> - -Specifies that the parameter is passed as a raw alias, an argument -object that has not yet had a context imposed. -In other words, this provides for lazy contextualization even through -function calls. This is important if you wish to pass the parameter -onward to something else that will determine its context later. - -You may modify the argument, but only if argument is already a suitable -lvalue since, unlike C<rw>, no attempt at autovivification is made, -so unsuitable lvalues will throw an exception if you try to modify -them within the body of the routine. That is, if autovivification -happens, it happens at the point of use, not at the point of binding. - -For better visual distinction, such a parameter is declared by -prefixing with a backslash rather than by using C<is raw> directly. -The backslash is also more succinct; the trait is there primarily -for introspection. - -=item C<is copy> - -Specifies that the parameter receives a distinct, read-writable copy of the -original argument. This is commonly known as "pass-by-value". - - sub reprint ($text, $count is copy) { - print $text while $count-- > 0; - } - -Binding to a copy parameter never triggers autovivification. - -=item C<is dynamic> - -Specifies that the parameter is to be treated as an "environmental" -variable, that is, a lexical that is accessible from the dynamic -scope (see S02). - -=item C<as> - -[DEPRECATED] Specifies that the parameter is to be coerced to the given type. - - method link(IO::File:D: $name as Str) { ... } - - sub homedir($path as Str, :$test = <r w x>) { ... } - - -=back - -=head2 Signature Introspection - -A C<Signature> object can be introspected to find out the details of -the parameters it is defined as expected. The C<.params> method will -return a C<List> of C<Parameter> objects, which have the following -readonly properties: - - name The name of the lexical variable to bind to, if any - type The main type (the one multi-dispatch sorts by) - constraints Any further type constraints - type_captures List of names the argument type is captured into - readonly True if the parameter has C<is readonly> trait - rw True if the parameter has C<is rw> trait - copy True if the parameter has C<is copy> trait - named True if the parameter is to be passed named - named_names List of names a named parameter can be passed as - capture True if the parameter binds the caller's Capture - raw True if the parameter is too lazy to contextualize - slurpy True if the parameter is slurpy - optional True if the parameter is optional - default A closure returning the default value - invocant True if the parameter is a method invocant - multi_invocant True if the parameter is a multi invocant - signature A nested signature to bind the argument against - -Note that C<constraints> will be something that can be smart-matched -against if it is defined; if there are many constraints it may be a -C<Junction> of some sort, but if there is just one it may be simply -that one thing. - -Further, various things that appear in an original written signature -will have been deconstructed a bit. For example, a signature like: - - :(1) - -Will introspect the same way as: - - :(Int $ where 1) - -And if we have: - - subset Odd of Int where { $^n % 2 }; - sub foo(Odd $x) { ... } - -Then the signature of foo will be equivalent to something like: - - :(Int $x where { $^n % 2 }) - -That is, the refinement type will have been deconstructed into the -part that nominal type that multiple dispatch uses for sorting the -candidates and an additional constraint. - - -=head1 Advanced subroutine features - -=head2 Processing of returned values - -It is a general policy that lvalues should only be returned up the dynamic -call stack if specifically requested. Therefore, by default the returned -arguments are processed to enforce this, both for the implicit return from -the last statement of any block, as well as the explicit return done by -operators such as: - - return - leave - take - -Specifically, this processing involves examining the returned value's -arguments and dereferencing any container that could be used as an lvalue, -replacing it with the container's value. - -To override this processing for a routine, it must be declared C<rw>, or -the form C<return-rw> must be used. - -To override for a C<gather>, use C<gather-rw> instead, or C<take-rw> on the -individual take. - -Since blocks don't generally have traits, you must use C<leave-rw> to pass -an lvalue out of a block. - -=head2 The C<return> function - -The C<return> function notionally throws a control exception that is -caught by the current lexically enclosing C<Routine> to force a return -through the control logic code of any intermediate block constructs. -(That is, it must unwind the stack of dynamic scopes to the proper -lexical scope belonging to this routine.) With normal blocks -(those that are autoexecuted in place because they're known to the -compiler) this unwinding can likely be optimized away to a "goto". -All C<Routine> declarations have an explicit declarator such as C<sub> -or C<method>; bare blocks and "pointy" blocks are never considered -to be routines in that sense. To return from a block, use C<leave> -instead--see below. - -The C<return> function preserves its argument list as a C<Capture> object, and -responds to the left-hand C<Signature> in a binding. This allows named return -values if the caller expects one: - - sub f () { return :x<1> } - sub g ($x) { print $x } - - my $x := |(f); # binds 1 to $x, via a named argument - g(|(f)); # prints 1, via a named argument - -To return a literal C<Pair> object, always put it in an additional set of -parentheses: - - return( (:x<1>), (:y<2>) ); # two positional Pair objects - -Note that the postfix parentheses on the function call don't count as -being "additional". However, as with any function, whitespace after the -C<return> keyword prevents that interpretation and turns it instead -into a list operator: - - return :x<1>, :y<2>; # two named arguments (if caller uses |) - return ( :x<1>, :y<2> ); # two positional Pair objects - -If the function ends with an expression without an explicit C<return>, -that expression is also taken to be a C<Capture>, just as if the expression -were the argument to a C<return> list operator (with whitespace): - - sub f { :x<1> } # named-argument binding (if caller uses |) - sub f { (:x<1>) } # always just one positional Pair object - -On the caller's end, the C<Capture> is interpolated into any new argument list -much like an array would be, that is, as an item in item context, and as a -list in list context. This is the default behavior, but the -caller may use C<< prefix:<|> >> to inline the returned values as part of the -new argument list. The caller may also bind the returned C<Capture> directly. - -A function is called only once at the time the -C<Capture> object is generated, not when it is later bound (which -could happen more than once). - -=head2 The C<callframe> and C<caller> functions - -The C<callframe> function takes a list of matchers and interprets them -as a navigation path from the current call frame to a location in the -call stack, either the current call frame itself or some frame -from which the current frame was called. It returns an object -that describes that particular call frame, or a false value if -there is no such scope. Numeric arguments are interpreted as number -of frames to skip, while non-numeric arguments scan outward for a -frame matching the argument as a smartmatch. - -The current frame is accessed with a null argument list. - - say " file ", callframe().file, - " line ", callframe().line; - -which is equivalent to: - - say " file ", DYNAMIC::<$?FILE>, - " line ", DYNAMIC::<$?LINE>; - -The immediate caller of this frame is accessed by skipping one level: - - say " file ", callframe(1).file, - " line ", callframe(1).line; - -You might think that that must be the current function's caller, -but that's not necessarily so. This might return an outer block in -our own routine, or even some function elsewhere that implements a -control operator on behalf of our block. To get outside your current -routine, see C<caller> below. - -The C<callframe> function may be given arguments -telling it which higher scope to look for. Each argument is processed -in order, left to right. Note that C<Any> and C<0> are no-ops: - - $ctx = callframe(); # currently running frame for &?BLOCK - $ctx = callframe(Any); # currently running frame for &?BLOCK - $ctx = callframe(Any,Any); # currently running frame for &?BLOCK - $ctx = callframe(1); # my frame's caller - $ctx = callframe(2); # my frame's caller's caller - $ctx = callframe(3); # my frame's caller's caller's caller - $ctx = callframe(1,0,1,1); # my frame's caller's caller's caller - $ctx = callframe($i); # $i'th caller - -Note also that negative numbers are allowed as long as you stay within -the existing call stack: - - $ctx = callframe(4,-1); # my frame's caller's caller's caller - -Repeating any smartmatch just matches the same frame again unless you -intersperse a 1 to skip the current level: - - $ctx = callframe(Method); # nearest frame that is method - $ctx = callframe(Method,Method); # nearest frame that is method - $ctx = callframe(Method,1,Method); # 2nd nearest method frame - $ctx = callframe(Method,1,Method,1) # caller of that 2nd nearest method - $ctx = callframe(1,Block); # nearest outer frame that is block - $ctx = callframe(Sub,1,Sub,1,Sub); # 3rd nearest sub frame - $ctx = callframe({ .labels.any eq 'Foo' }); # nearest frame labeled 'Foo' - -Note that this last potentially differs from the answer returned by - - Foo.callframe - -which returns the frame of the innermost C<Foo> block in the lexical scope -rather than the dynamic scope. A call frame also responds to the C<.callframe> -method, so a given frame may be used as the basis for further navigation: - - $ctx = callframe(Method,1,Method); - $ctx = callframe(Method).callframe(1).callframe(Method); # same - -You must supply args to get anywhere else, since C<.callframe> is -the identity operator when called on something that is already -a C<Context>: - - $ctx = callframe; - $ctx = callframe.callframe.callframe.callframe; # same - -The C<caller> function is special-cased to go outward just far enough -to escape from the current routine scope, after first ignoring any -inner blocks that are embedded, or are otherwise pretending to be "inline": - - &caller ::= &callframe.assuming({ !.inline }, 1); - -Note that this is usually the same as C<callframe(&?ROUTINE,1)>, -but not always. A call to a returned closure might not even have -C<&?ROUTINE> in its dynamic scope anymore, but it still has a caller. - -So to find where the current routine was called you can say: - - say " file ", caller.file, - " line ", caller.line; - -which is equivalent to: - - say " file ", CALLER::<$?FILE>, - " line ", CALLER::<$?LINE>; - -Additional arguments to C<caller> are treated as navigational from the -calling frame. One frame out from your current routine is I<not> -guaranteed to be a C<Routine> frame. You must say C<caller(Routine)> -to get to the next-most-inner routine. - -Note that C<caller(Routine).line> is not necessarily going to give you the -line number that your current routine was called from; you're rather -likely to get the line number of the topmost block that is executing -within that outer routine, where that block contains the call to -your routine. - -For either C<callframe> or C<caller>, -the returned CallFrame object supports at least the following methods: - - .callframe - .caller - .leave - .inline - .package - .file - .line - .my - .hints - .args - -The C<.callframe> and C<.caller> methods work the same as the functions -except that they are relative to the frame supplied as invocant. -The C<.leave> method can force an immediate return from the -specified call frame. - -The C<.inline> method says whether this block was entered implicitly -by some surrounding control structure. Any time you invoke a block or -routine explicitly with C<.()> this is false. However, it is defined -to be true for any block entered using dispatcher-level primitives -such as C<.callwith>, C<.callsame>, C<.nextwith>, or C<.nextsame>. - -The C<.my> method provides access to the lexical namespace associated with -the given call frame's current position. It may be used to look -up ordinary lexical variables in that lexical scope. It must not be -used to change any lexical variable that is marked as readonly. - -The C<.hints> method gives access to a snapshot of compiler symbols in -effect at the point of the call when the call was originally compiled. -(For instance, C<caller.hints('&?ROUTINE')> will give you the caller's -routine object.) Such values are always read-only, though in the -case of some (like the caller's routine above) may return a fixed -object that is nevertheless mutable. - -=head2 The C<want> function - -The C<want> function is gone. If you want context specific behavior, -return an object instead that responds accordingly to the various contextual -methods. - -(Conjecture: in future we might want to provide some syntactic sugar that -makes it easier to create such objects. Or maybe a type that takes values -or code references for the various contexts, so that you can write - - return ContextProxy.new: - Int => 3, - item => { @.list.join(', ') }, - list => { ... }, - ; - -or something similar.) - -=head2 The C<leave> function - -As mentioned above, a C<return> call causes the innermost surrounding -subroutine, method, rule, token, regex (as a keyword) or macro -to return. Only declarations with an explicit declarator keyword -(C<sub>, C<submethod>, C<method>, C<macro>, C<regex>, C<token>, and -C<rule>) may be returned from. Statement prefixes such a C<do> and -C<try> do not fall into that category. -You cannot use C<return> to escape directly into the surrounding -context from loops, bare blocks, pointy blocks, or quotelike operators -such as C<rx//>; a C<return> within one of those constructs will -continue searching outward for a "proper" routine to return from. -Nor may you return from property blocks such as C<BEGIN> or C<CATCH> -(though blocks executing within the lexical and dynamic scope of a -routine can of course return from that outer routine, which means -you can always return from a C<CATCH> or a C<FIRST>, but never from -a C<BEGIN> or C<INIT>.) - -To return from blocks that aren't routines, the C<leave> method is used -instead. (It can be taken to mean either "go away from" or "bequeath -to your successor" as appropriate.) The object specifies the scope to exit, -and the method's arguments specify the return value. If the object -is omitted (by use of the function or listop forms), the innermost -block is exited. Otherwise you must use something like C<callframe> -or C<&?BLOCK> or a dynamic variable to specify the scope you -want to exit. A label (such as a loop label) previously seen in -the lexical scope also works as a kind of singleton dynamic object: -it names a statement that is serving both as an outer lexical scope -and as a frame in the current dynamic scope. - -As with C<return>, the arguments are taken to be a C<Capture> holding the -return values. - - leave; # return from innermost block of any kind - callframe(Method).leave; # return from innermost calling method - &?ROUTINE.leave(1,2,3); # Return from current sub. Same as: return 1,2,3 - &?ROUTINE.leave <== 1,2,3; # same thing, force return as feed - OUTER.leave; # Return from OUTER label in lexical scope - &foo.leave: 1,2,3; # Return from innermost surrounding call to &foo - -Note that these are equivalent in terms of control flow: - - COUNT.leave; - last COUNT; - -However, the first form explicitly sets the return value for the -entire loop, while the second implicitly returns all the previous -successful loop iteration values as a list comprehension. (It may, -in fact, be too late to set a return value for the loop if it is -being evaluated lazily!) A C<leave> -from the inner loop block, however, merely specifies the return value for -that iteration: - - for 1..10 { leave $_ * 2 } # 2..20 - -Note that this: - - leave COUNT; - -will always be taken as the function, not the method, so it returns -the C<COUNT> object from the innermost block. The indirect object form -of the method always requires a colon: - - leave COUNT: ; - -=head2 Temporization - -The C<temp> macro temporarily replaces the value of an existing -variable, subroutine, context of a function call, or other object in a given scope: - - { - temp $*foo = 'foo'; # Temporarily replace global $foo - temp &bar := sub {...}; # Temporarily replace sub &bar - ... - } # Old values of $*foo and &bar reinstated at this point - -C<temp> invokes its argument's C<.TEMP> method. The method is expected -to return a C<Callable> object that can later restore the current -value of the object. At the end of the lexical scope in which the -C<temp> was applied, the subroutine returned by the C<.TEMP> method is -executed. - -The default C<.TEMP> method for variables simply creates -a closure that assigns the variable's pre-C<temp> value -back to the variable. - -New kinds of temporization can be created by writing storage classes with -their own C<.TEMP> methods: - - class LoudArray is Array { - method TEMP { - print "Replacing $.WHICH() at {caller.location}\n"; - my $restorer = callsame; - return { - print "Restoring $.WHICH() at {caller.location}\n"; - $restorer(); - }; - } - } - -You can also modify the behaviour of temporized code structures, by -giving them a C<TEMP> block. As with C<.TEMP> methods, this block is -expected to return a closure, which will be executed at the end of -the temporizing scope to restore the subroutine to its pre-C<temp> state: - - my $next = 0; - sub next { - my $curr = $next++; - TEMP {{ $next = $curr }} # TEMP block returns the closure { $next = $curr } - return $curr; - } - - # and later... - - say next(); # prints 0; $next == 1 - say next(); # prints 1; $next == 2 - say next(); # prints 2; $next == 3 - if ($hiccough) { - say temp next(); # prints 3; closes $curr at 3; $next == 4 - say next(); # prints 4; $next == 5 - say next(); # prints 5; $next == 6 - } # $next = 3 - say next(); # prints 3; $next == 4 - say next(); # prints 4; $next == 5 - -Note that C<temp> must be a macro rather than a function because the -temporization must be arranged before the function causes any state -changes, and if it were a normal argument to a normal function, the state -change would be happen before C<temp> got control. - -Hypothetical variables use the same mechanism, except that the restoring -closure is called only on failure. - -Note that dynamic variables may be a better solution than temporized -globals in the face of multithreading. - -=head2 Wrapping - -Every C<Routine> object has a C<.wrap> method. This method expects a -single C<Callable> argument. Within the code, the special C<callsame>, -C<callwith>, C<nextsame> and C<nextwith> functions will invoke the -original routine, but do not introduce an official C<CALLER> frame: - - sub thermo ($t) {...} # set temperature in Celsius, returns old value - - # Add a wrapper to convert from Fahrenheit... - $handle = &thermo.wrap( { callwith( ($^t-32)/1.8 ) } ); - -The C<callwith> function lets you pass your own arguments to the wrapped -function. The C<callsame> function takes no argument; it -implicitly passes the original argument list through unchanged. -The C<callsame> and C<nextsame> functions are really short for: - - callwith( |callframe(Routine).args ) - nextwith( |callframe(Routine).args ) - -The call to C<.wrap> replaces the original C<Routine>'s C<do> property with the C<Callable> -argument, and arranges that any call to C<callsame>, C<callwith>, -C<nextsame> or C<nextwith> invokes the previous version of the -routine. In other words, the call to C<.wrap> has more or less the -same effect as: - - my &old_thermo := &thermo; - &thermo = sub ($t) { old_thermo( ($t-32)/1.8 ) } - -Note that C<&thermo.WHICH> stays the same after the C<.wrap>, -as it does with the equivalent assignment shown since assignment -to a C<Routine> works like a container, changing the contained C<do> -property but not the container itself. - -The call to C<.wrap> returns a unique handle that has a C<restore> method -that will undo the wrapping: - - $handle.restore; - -This does not affect any other wrappings placed to the routine. - -A wrapping can also be restricted to a particular dynamic scope with -temporization: - - # Add a wrapper to convert from Kelvin - # wrapper self-unwraps at end of current scope - temp &thermo.wrap( { callwith($^t + 273.16) } ); - -The entire argument list may be captured by binding to a C<Capture> parameter. -It can then be passed to C<callwith> using that name: - - # Double the return value for &thermo - &thermo.wrap( -> |args { callwith(|args) * 2 } ); - -In this case only the return value is changed. - -The wrapper is not required to call the original routine; it can call another -C<Callable> object by passing the C<Capture> to its C<callwith> method: - - # Transparently redirect all calls to &thermo to &other_thermo - &thermo.wrap( sub (|args) { &other_thermo.callwith(|args) } ); - -or more briefly: - - &thermo.wrap( { &other_thermo.callsame } ); - -Since the method versions of C<callsame>, C<callwith>, C<nextsame>, -and C<nextwith> specify an explicit destination, their semantics do -not change outside of wrappers. However, the corresponding functions -have no explicit destination, so instead they implicitly call the -next-most-likely method or multi-sub; see S12 for details. - -As with any return value, you may capture the returned C<Capture> of C<call> -by binding: - - my |retval := callwith(|args); - ... # postprocessing - return |retval; - -Alternately, you may prevent any return at all by using the variants -C<nextsame> and C<nextwith>. Arguments are passed just as with -C<callsame> and C<callwith>, but a tail call is explicitly enforced; -any code following the call will be unreached, as if a return had -been executed there before calling into the destination routine. - -Within an ordinary method dispatch these functions treat the rest -of the dispatcher's candidate list as the wrapped function, which -generally works out to calling the same method in one of our parent -(or older sibling) classes. Likewise within a multiple dispatch the -current routine may defer to candidates further down the candidate -list. Although not necessarily related by a class hierarchy, such -later candidates are considered more generic and hence likelier -to be able to handle various unforeseen conditions (perhaps). - -Note that all routines are (by default) considered to be candidates -for inlining and constant folding. The optimizer is allowed to start -making these optimizations after the main program's C<LINK> time, -but not before. After any routine is "hard" inlined or constant -folded, it is explicitly retyped as immutable; any attempt to -wrap an immutable routine will result in failure of the wrap call. -An immutable routine is so marked by recasting to type C<HardRoutine>, -a subclass of C<Routine>. - -On the other hand, it is also possible to explicitly mark a routine -as mutable, and then the ability to wrap it must be preserved even -after C<LINK> time. This is done by recasting to C<SoftRoutine>. -Explicitly marking a routine as either mutable or immutable should -be considered permanent. It is still possible to inline soft -routines, but only if the possibility of indirection is detected -inline as well, and provision made (either inline or via external -rewriting) for dealing with any wrappers. - -Hence, any routine marked as soft before C<LINK> time is exempt -from hard inlining or folding. There are several methods of -marking a routine as soft, however no method is provided for marking -routines as hard, since that is the job of the optimizer. -A routine may be marked as soft: - -=over - -=item * - -if it is declared using "our" explicitly - -=item * - -if it is mentioned in the argument list of a C<use soft> pragma, - -=item * - -if its name matches any wildcard pattern (TBD) in a C<use soft>, - -=item * - -if the module or class in which it is defined is mentioned in a C<use soft>, - -=item * - -or if there is a general C<use soft *;> declaration, which basically -turns on AOP for everything at run time. Be aware that this may turn -your optimizer into more of a "pessimizer". - -=back - -For any normal standalone application, any C<use soft> pragma applies -to the entire program in which it participates, provided it is -performed before C<LINK> time. The optimizer may then harden -anything that was not requested to remain soft. - -A plug-in system, such as for a web server, may choose either to allow -individual plug-ins to behave as independent programs by letting the -optimizer harden individual plug-ins independently, or treat all -plug-ins as a part of the same program by softening all plug-ins. -(Similar considerations apply to optimizing classes to closed/final.) - -Note that installing a wrapper before C<LINK> time is specifically -I<not> one of the ways to mark a routine as soft. Such a routine -may still be hardened at C<LINK> time despite being wrapped during -compile time. - -=head2 The C<&?ROUTINE> object - -C<&?ROUTINE> is always an alias for the lexically innermost C<Routine> -(which may be a C<Sub>, C<Method>, or C<Submethod>), so you can specify -recursion on an anonymous sub: - - my $anonfactorial = sub (Int $n) { - return 1 if $n<2; - return $n * &?ROUTINE($n-1); - }; - -You can get the current routine name by calling C<&?ROUTINE.name>. -Outside of any sub declaration, this call returns failure. - -Note that C<&?ROUTINE> refers to the current single sub, even if it is -declared C<multi>. To redispatch to the entire suite under a given short -name, just use the named form to call the C<proto>, since there are no anonymous C<multi>s. - -=head2 The C<&?BLOCK> object - -C<&?BLOCK> is always an alias for the current block, so you can -specify recursion on an anonymous block: - - my $anonfactorial = -> Int $n { $n < 2 - ?? 1 - !! $n * &?BLOCK($n-1) - }; - -C<&?BLOCK.labels> contains a list of all labels of the current block. -This is typically matched by saying - - if &?BLOCK.labels.any eq 'Foo' {...} - -If the innermost lexical block happens to be the main block of a C<Routine>, -then C<&?BLOCK> just returns the C<Block> object, not the C<Routine> object -that contains it. - -[Note: to refer to any C<$?> or C<&?> variable at the time the sub or -block is being compiled, use the C<< COMPILING:: >> pseudopackage.] - -=head2 Priming - -Every C<Callable> object has a C<.assuming> method, which does partial function application, -aka I<priming>. This method does a partial -binding of a set of arguments to a signature and returns a new function -that takes only the remaining arguments. - - &textfrom := &substr.assuming(str=>$text, len=>Inf); - -or equivalently: - - &textfrom := &substr.assuming(:str($text) :len(Inf)); - -or even: - - &textfrom := &substr.assuming :str($text):len(Inf); - -It returns a C<Callable> object that implements the same behaviour -as the original subroutine, but has the values passed to C<.assuming> -already bound to the corresponding parameters: - - $all = textfrom(0); # same as: $all = substr($text,0,Inf); - $some = textfrom(50); # same as: $some = substr($text,50,Inf); - $last = textfrom(-1); # same as: $last = substr($text,-1,Inf); - -Position parameters may also be primed. To skip a position argument, -pass a C<*>, which is handled specially by C<.assuming>. Passing a -C<Nil> causes priming with the default argument supplied with the -parameter at that position in the signature, or the (presumably undefined) default -value for the container associated with the parameter if -the parameter in question has no default. C<Nil> may also be passed -to a named argument to force priming to the default. - -The result of a C<use> statement is a (compile-time) object that also has -a C<.assuming> method, allowing the user to bind parameters in all the -module's subroutines/methods/etc. simultaneously: - - (use IO::Logging).assuming(logfile => ".log"); - -This special form should generally be restricted to named parameters. - -To prime a particular C<multi> variant, it may be necessary to specify the type -for one or more of its parameters to pick out a single function: - - &woof ::= &bark:(Dog).assuming :pitch<low>; - &pine ::= &bark:(Tree).assuming :pitch<yes>; - -=head2 Macros - -Macros are functions or operators that are called by the compiler as -soon as their arguments are parsed (if not sooner). The syntactic -effect of a macro declaration or importation is always lexically -scoped, even if the name of the macro is visible elsewhere. As with -ordinary operators, macros may be classified by their grammatical -category. For a given grammatical category, a default parsing rule or -set of rules is used, but those rules that have not yet been "used" -by the time the macro keyword or token is seen can be replaced by -use of "is parsed" trait. (This means, for instance, that an infix -operator can change the parse rules for its right operand but not -its left operand.) - -In the absence of a signature to the contrary, a macro is called as -if it were a method on the current match object returned from the -grammar rule being reduced; that is, all the current parse information -is available by treating C<self> as if it were a C<$/> object. -[Conjecture: alternate representations may be available if arguments -are declared with particular AST types.] - -Macros may return either a string to be reparsed, or a syntax tree -that needs no further parsing. The textual form is handy, but the -syntax tree form is generally preferred because it allows the parser -and debugger to give better error messages. Textual substitution -on the other hand tends to yield error messages that are opaque to -the user. Syntax trees are also better in general because they are -reversible, so things like syntax highlighters can get back to the -original language and know which parts of the derived program come -from which parts of the user's view of the program. Nevertheless, -it's difficult to return a syntax tree for an unbalanced construct, -and in such cases a textual macro may be a clearer expression of the -evil thing you're trying to do. - -If you call a macro at runtime, the result of the macro is automatically -evaluated again, so the two calls below print the same thing: - - macro f { '1 + 1' } - say f(); # compile-time call to &f - say &f(); # runtime call to &f - -A compile-time call to a macro before its definition is erroneous. - -=head2 Quasiquoting - -In aid of returning syntax tree, Perl provides a "quasiquoting" -mechanism using the quote C<quasi>, followed by a block intended to -represent an AST: - - return quasi { say "foo" }; - -Modifiers to the C<quasi> can modify the operation: - - :ast(MyAst) # Default :ast(AST) - :lang(Ruby) # Default :lang($?PARSER) - :unquote<[: :]> # Default "triple rule" - -Within a quasiquote, variable and function names resolve according -to the lexical scope of the macro definition. Unrecognized symbols raise -errors when the macro is being compiled, I<not> when it's being used. - -Use of a macro argument in a quasiquote without unquoting should provide a -warning, as this is very likely to be an error. - - # Oops; size of the AST of the argument - macro mouse ($arg) { quasi { $arg.elems } } - -To make a symbol resolve to the (partially compiled) scope of the macro -call, use the C<COMPILING::> pseudo-package: - - macro moose () { quasi { $COMPILING::x } } - - moose(); # macro-call-time error - my $x; - moose(); # resolves to 'my $x' - -If you want to mention symbols from the scope of the macro call, use the -import syntax as modifiers to C<quasi>: - - :COMPILING<$x> # $x always refers to $x in caller's scope - :COMPILING # All free variables fallback to caller's scope - -If those symbols do not exist in the scope of the compiling scope, a -compile-time exception is thrown at macro call time. - -Similarly, in the macro body you may either refer to the C<$x> declared in the -scope of the macro call as C<$COMPILING::x>, or bind to them explicitly: - - my $x := $COMPILING::x; - -You may also use an import list to bind multiple symbols into the -macro's lexical scope: - - require COMPILING <$x $y $z>; - -Note that you need to use the run-time C<require> form, not -C<use>, because the macro caller's compile-time is the macro's runtime. - -=head2 Splicing - -Bare AST variables (such as the arguments to the macro) may not be -spliced directly into a quasiquote because they would be taken as -normal bindings. Likewise, program text strings to be inserted need -to be specially marked or they will be bound normally. To insert an -"unquoted" expression of either type within a quasiquote, use the -quasiquote delimiter tripled, typically a bracketing quote of some sort: - - return quasi { say $a + {{{ $ast }}} } - return quasi [ say $a + [[[ $ast ]]] ] - return quasi < say $a + <<< $ast >>> > - return quasi ( say $a + ((( $ast ))) ) - -The delimiters don't have to be bracketing quotes, but the following -is probably to be construed as Bad Style: - - return quasi / say $a + /// $ast /// / - -(Note to implementors: this must not be implemented by finding -the final closing delimiter and preprocessing, or we'll violate our -one-pass parsing rule. Perl 6 parsing rules are parameterized to know -their closing delimiter, so adding the opening delimiter should not -be a hardship. Alternately the opening delimiter can be deduced from -the closing delimiter. Writing a rule that looks for three opening -delimiters in a row should not be a problem. It has to be a special -grammar rule, though, not a fixed token, since we need to be able to -nest code blocks with different delimiters. Likewise when parsing the -inner expression, the inner parser subrule is parameterized to know that -C<}}}> or whatever is its closing delimiter.) - -Unquoted expressions are inserted appropriately depending on the -type of the variable, which may be either a syntax tree or a string. -(Again, syntax tree is preferred.) The case is similar to that of a -macro called from within the quasiquote, insofar as reparsing only -happens with the string version of interpolation, except that such -a reparse happens at macro call time rather than macro definition -time, so its result cannot change the parser's expectations about -what follows the interpolated variable. - -Hence, while the quasiquote itself is being parsed, the syntactic -interpolation of an unquoted expression into the quasiquote always -results in the expectation of an operator following the unquote. -(You must use a call to a submacro if you want to expect something -else.) Of course, the macro definition as a whole can expect -whatever it likes afterwards, according to its syntactic category. -(Generally, a term expects a following postfix or infix operator, -and an operator expects a following term or prefix operator. This -does not matter for textual macros, however, since the reparse of -the text determines subsequent expectations.) - -Quasiquotes default to hygienic lexical scoping, just like closures. -The visibility of lexical variables is limited to the quasi expression -by default. A variable declaration can be made externally visible using -the C<COMPILING::> pseudo-package. Individual variables can be made visible, -or all top-level variable declarations can be exposed using the -C<quasi :COMPILING> form. - -Both examples below will add C<$new_variable> to the lexical scope of -the macro call: - - quasi { my $COMPILING::new_variable; my $private_var; ... } - quasi :COMPILING { my $new_variable; { my $private_var; ... } } - -(Note that C<:COMPILING> has additional effects described in L</Macros>.) - -=head1 Other matters - - -=head2 Anonymous hashes vs blocks - -C<{...}> is always a block. However, if it is completely empty or -consists of a single list, the first element of which is either a hash -or a pair, it is executed immediately to compose a C<Hash> object. - -The standard C<pair> list operator is equivalent to: - - sub pair (*@LIST) { - my @pairs; - for @LIST -> $key, $val { - push @pairs, $key => $val; - } - return @pairs; - } - -or more succinctly (and lazily): - - sub pair (*@LIST) { - gather for @LIST -> $key, $val { - take $key => $val; - } - } - -The standard C<hash> list operator is equivalent to: - - sub hash (*@LIST) { - return { pair @LIST }; - } - -So you may use C<sub> or C<hash> or C<pair> to disambiguate: - - $obj = sub { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list - $obj = { 1, 2, 3, 4, 5, 6 }; # Anonymous sub returning list - $obj = { 1=>2, 3=>4, 5=>6 }; # Anonymous hash - $obj = { 1=>2, 3, 4, 5, 6 }; # Anonymous hash - $obj = hash( 1, 2, 3, 4, 5, 6 ); # Anonymous hash - $obj = hash 1, 2, 3, 4, 5, 6 ; # Anonymous hash - $obj = { pair 1, 2, 3, 4, 5, 6 }; # Anonymous hash - - -=head2 Pairs as lvalues - -Since they are immutable, Pair objects may not be directly assigned: - - (key => $var) = "value"; # ERROR - -However, when binding pairs, names can be used to "match up" lvalues -and rvalues, provided you write the left side as a signature using -C<:(...)> notation: - - :(:who($name), :why($reason)) := (why => $because, who => "me"); - -(Otherwise the parser doesn't know it should parse the insides as a -signature and not as an ordinary expression until it gets to the C<:=>, -and that would be bad. Alternately, the C<my> declarator can also -force treatment of its argument as a signature.) - -=head2 Out-of-scope names - -C<< GLOBAL::<$varname> >> specifies the C<$varname> declared in the C<*> -namespace. Or maybe it's the other way around... - -C<< CALLER::<$varname> >> specifies the C<$varname> visible in -the dynamic scope from which the current block/closure/subroutine -was called, provided that variable carries the "C<dynamic>" -trait. (All variables with a C<*> twigil are automatically marked with the trait. -Likewise certain implicit lexicals (C<$_>, C<$/>, and C<$!>) are so marked.) - -C<< DYNAMIC::<$varname> >> specifies the C<$varname> visible in the -innermost dynamic scope that declares the variable with the "C<is dynamic>" -trait or with a name that has the C<*> twigil. - -C<< MY::<$varname> >> specifies the lexical C<$varname> declared in the current -lexical scope. - -C<< OUR::<$varname> >> specifies the C<$varname> declared in the current -package's namespace. - -C<< COMPILING::<$varname> >> specifies the C<$varname> declared (or about -to be declared) in the lexical scope currently being compiled. - -C<< OUTER::<$varname> >> specifies the C<$varname> declared in the lexical -scope surrounding the current lexical scope (i.e. the scope in which -the current block was defined). - -=head2 Declaring a C<MAIN> subroutine - -Ordinarily a top-level Perl "script" just evaluates its anonymous -mainline code and exits. During the mainline code, the program's -arguments are available in raw form from the C<@*ARGS> array. At the end of -the mainline code, however, a C<MAIN> subroutine will be called with -whatever command-line arguments remain in C<@*ARGS>. This call is -performed if and only if: - -=over - -=item a) - -the compilation unit was directly invoked rather than -by being required by another compilation unit, and - -=item b) - -the compilation unit declares a C<Routine> named "C<MAIN>", and - -=item c) - -the mainline code is not terminated prematurely, such as with an explicit call -to C<exit>, or an uncaught exception. - -=back - -The command line arguments (or what's left of them after mainline -processing) is magically converted into a C<Capture> and passed to -C<MAIN> as its arguments, so switches may be bound as named args and -other arguments to the program may be bound to positional parameters -or the slurpy array: - - sub MAIN ($directory, :$verbose, *%other, *@filenames) { - for @filenames { ... } - } - -Each incoming argument is automatically passed through -the C<val()> function, which will attempt to intuit the types of the -textual arguments such that they may be used in multimethod dispatch. -If C<MAIN> is declared as a set of C<multi> subs, multi dispatch -is performed, and the type information intuited by C<val()> may -be used to distinguish the different signatures: - - multi MAIN (Int $i) {...} # foo 1 - multi MAIN (Rat $i) {...} # foo 1/2 - multi MAIN (Num $i) {...} # foo 1e6 - multi MAIN ($i) {...} # foo bar - -As with module and class declarations, a sub declared -with the C<unit> declarator (and ending in semicolon) is allowed at the outermost file scope if it is the -first such declaration, in which case the rest of the file is the body: - - unit sub MAIN ($directory, :$verbose, *%other, *@filenames); - for @filenames { ... } - -This form is allowed only for simple subs named C<MAIN> that are intended -to be run from the command line. -A C<proto> or C<multi> definition may not be written in semicolon form, -nor may C<MAIN> subs within a module or class be written in semicolon form. (A C<MAIN> routine -is allowed in a module or class, but is not usually invoked unless -the file is run directly (see a above). This corresponds to the -"unless caller" idiom of Perl 5.) In general, you may have only one -semicolon-style declaration that controls the whole file. - -If an attempted dispatch to C<MAIN> fails, the C<USAGE> routine is called. -If there is no C<USAGE> routine, a default message is printed to standard -error. If C<--help> is passed as a command line option to the program, the -usage message is printed to standard output instead. - -This usage message is automatically generated from the signature (or -signatures) of C<MAIN>. This message is generated at compile time, -and hence is available at any later time as C<$?USAGE> (EDIT: variable -renamed to C<$*USAGE> and message is generated on-demand, at runtime). - -Common Unix command-line conventions are mapped onto the capture -as follows: - - Assuming C<-n> is the short name for C<--name>, - On command line... $*ARGS capture gets... - - # Short names - -n :name - -n=value :name<value> - -n="spacey value" :name«'spacey value'» - -n='spacey value' :name«'spacey value'» - -n=val1,'val 2',etc :name«val1 'val 2' etc» - - # Long names - --name :name - --name=value :name<value> - - --name="spacey value" :name«'spacey value'» - --name "spacey value" :name«'spacey value'» - --name='spacey value' :name«'spacey value'» - --name=val1,'val 2',etc :name«val1 'val 2' etc» - -- # end named argument processing - - # Negation - --/name :!name - --/name=value :name<value> but False - --/name="spacey value" :name«'spacey value'» but False - --/name='spacey value' :name«'spacey value'» but False - --/name=val1,'val 2',etc :name«val1 'val 2' etc» but False - - # Native - :name :name - :/name :!name - :name=value :name<value> - :name="spacey value" :name«'spacey value'» - :name='spacey value' :name«'spacey value'» - :name=val1,'val 2',etc :name«val1 'val 2' etc» - -Exact Perl 6 forms are okay if quoted from shell processing: - - ':name<value>' :name<value> - ':name(42)' :name(42) - -For security reasons, only constants are allowed as arguments, however. - -The default C<Capture> mapper pays attention to declaration of C<MAIN>'s -parameters to resolve certain ambiguities. A C<--foo> switch needs to -know whether to treat the next word from the command line as an argument. -(Allowing the spacey form gives the shell room to do various things to -the argument.) The short C<-foo> form never assumes a separate argument, -and you must use C<=>. For the C<--foo> form, if there is a named parameter -corresponding to the switch name, and it is of type C<Bool>, then no argument -is expected. Otherwise an argument is expected. If the parameter is of -a non-slurpy array type, all subsequent words up to the next command-line -switch (or the end of the list) are bound to that parameter. - -As usual, switches are assumed to be first, and everything after -the first non-switch, or any switches after a C<-->, are treated -as positionals or go into the slurpy array (even if they look like -switches). Other policies may easily be introduced by calling C<MAIN> -explicitly. For instance, you can parse your arguments with a grammar -and pass the resulting C<Match> object as a C<Capture> to C<MAIN>: - - @*ARGS ~~ /<MyGrammar::top>/; - MAIN(|$/); - exit; - - sub MAIN ($frompart, $topart, *@rest) { - if $frompart<foo> { ... } - if $topart<bar><baz> { ... } - } - -This will conveniently bind top-level named matches to named -parameters, but still give you access to nested matches through those -parameters, just as any C<Match> object would. Of course, in this example, -there's no particular reason the sub has to be named C<MAIN>. - -To give both a long and a short switch name, you may use the pair -notation to install several names for the same parameter. -If any of the names is a single character, it will be considered a -short switch name, while all other parameters names are considered -as long switch name. So if the previous declaration had been: - - sub MAIN (:f(:$frompart), :t(:$topart), *@rest) - -then you could invoke the program with either C<-f> or C<--frompart> -to specify the first parameter. Likewise you could use either C<-t> -or C<--topart> for the second parameter. - -=head2 Relationship of MAIN routine with lexical setting - -The preceding section describes the use of C<MAIN> in the user's code. -There may also be an implicit C<MAIN> routine supplied by the setting -of the current compilation unit. (The C<-n> and C<-p> command-line -switches are implemented this way.) In this case the user's mainline -code is not automatically executed; instead, execution is controlled -by the setting's C<MAIN> routine. That routine calls C<{YOU_ARE_HERE}> -at the point where the user's code is to be lexically inserted (in -the abstract). A setting may also call C<{YOU_ARE_HERE}> outside of -a C<MAIN> routine, in which case it functions as a normal setting, -and the C<{YOU_ARE_HERE}> merely indicates where the user's code -goes logically. (Or from the compiler's point of view, which the -lexical scope to dump a snapshot of for later use by the compiler -as the setting for a different compilation unit.) In this case the -execution of the user code proceeds as normal. In fact, the C<CORE> -setting ends with a C<{YOU_ARE_HERE}> to dump the C<CORE> lexical -scope as the standard setting. In this sense, C<CORE> functions as -an ordinary prelude. - -If a C<MAIN> routine is declared both in the setting and in the -user's code, the setting's C<MAIN> functions as the actual mainline -entry point. The user's C<MAIN> functions in an embedded fashion; -the setting's invocation of C<{YOU_ARE_HERE}> functions as the main -invocation from the point of view of the user's code, and the -user's C<MAIN> routine will be invoked at the end of each call to -C<{YOU_ARE_HERE}>. - -=head2 Implementation note on autothreading of only subs - -The natural way to implement autothreading for C<multi> subs is to -simply have the junctional signatures (the ones that can accept -C<Mu> or junction as well as C<Any> parameters) match more loosely than -the non-autothreading versions, and let multiple dispatch find the -appropriate sub based on the signature. Those generic routines -then end up redispatching to the more specific ones. - -On the other hand, the natural implementation of C<only> subs is to -call the sub in question directly for efficiency (and maybe even -inline it in some cases). That efficiency is, after all, the main -reason for not just making all subs C<multi>. However, this direct -call conflicts with the desire to allow autothreading. It might -be tempting to simply make everything multi dispatch underneath, -and then say that the C<only> declaration merely means that you get -an error if you redeclare. And maybe that is a valid approach if -the multiple dispatch mechanism is fast enough. - -However, a direct call still needs to bind its arguments to its -parameters correctly, and it has to handle the case of failure to -bind somehow. So it is also possible to implement autothreading -of C<only> subs based on failover from the binding failure. This could -either be a one-shot failover followed by a conversion to a C<multi> call, -or it could failover every time you try to autothread. If we assume -that junctional processing is likely to be fairly heavyweight most of -the time compared to the cost of failing to bind, that tends to argue -for failing over every time. This is also more conducive to inlining, -since it's difficult to rewrite inlined calls. In any case, nowadays -a C<proto> declaration is considered to be a kind of C<only> sub, -and needs to handle autothreading similarly if the signature of -the C<proto> excludes junctions. - -=head2 Introspection - -This section describes the methods implemented by the routine objects -that allow introspection of the inner works of that routine. - -=head3 Routine - -=over - -=item .candidates - -This method returns a (potentially lazy) list of the candidates associated with the current -routine. An "only" routine should return a list with itself as the -single item. - -=item .signature - -This method returns the signature of the current routine. - -=item .cando($capture) - -This method returns a (potentially lazy) list of the candidates that match the given -capture, ordered by goodness of match, with the best match first. - -=item .push($candidate) - -Adds C<$candidate> to the list of candidates for this C<proto>, calling this -method in an C<only> routine should result in a failure. It is also -accepted for C<multi>s declared in the source code to finalize the list -of candidates and also return a failure here. But C<Proto>s created by -calling C<Proto.new()> should be able add candidates at run-time. - -=back - -=head3 Signature - -See section L</Signature Introspection>. - -=head1 AUTHORS - - Damian Conway <damian@conway.org> - Allison Randal <al@shadowed.net> - Larry Wall <larry@wall.org> - Daniel Ruoso <daniel@ruoso.com> - -=for vim:set expandtab sw=4: diff --git a/S07-lists.pod b/S07-lists.pod deleted file mode 100644 index 3dbf120e..00000000 --- a/S07-lists.pod +++ /dev/null @@ -1,352 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 7: Lists and Iteration - -=head1 VERSION - - Created: 07 September 2015 - - Last Modified: 07 September 2015 - Version: 1 - -=head1 Design Overview - -Perl 6 provides a wide array of list-related features, including eager, lazy, -and parallel evaluation of sequences of values, and arrays offering compact -and multi-dimensional storage. Laziness in particular needs careful handling, -so as to provide the power advanced users desire while not creating surprises -for typical language users who have the (reasonable) expectation that an -assignment into an array will have immediate effect. Additionally, it is -important to give the programmer control of when values will and won't be -retained. Finally, all of this needs to be done in a way that provides -the convenience that a Perl is expected to provide, while still having a -model that can be understood through understanding a small number of rules. - -=head2 Sequences vs. Lists - -In Perl 6, we use the term "sequence" to refer to something that can, when -requested, produce a sequence of values. Of note, it can only be asked to -produce them once. We use the term "list" to refer to things that hold (and -so remember) values. There are various concrete types that represent various -kinds of list and sequence with different semantics: - - (1, 2, 3) # a List, the simplest kind of list - [1, 2, 3] # an Array, a list of (assignable) Scalar containers - |(1, 2) # a Slip, a list which flattens into a surrounding List - $*IN.lines # a Seq, a sequence that can be processed serially - (^1000).race # a HyperSeq, a sequence that can be processed in parallel - -=head2 The single argument rule - -The C<@> sigil in Perl indicates "these", while C<$> indicates "the". This -kind of plural/single distinction shows up in various places in the language, -and much convenience in Perl comes from it. Flattening is the idea that an -C<@>-like thing will, in certain contexts, have its values automatically -incorporated into the surrounding list. Traditionally this has been a source -of both great power and great confusion in Perl. Perl 6 has been through a -number of models relating to flattening during its evolution, before settling -on a straightforward one known as the "single argument rule". - -The single argument rule is best understood by considering the number of -iterations that a C<for> loop will do. The thing to iterate over is always -treated as a single argument to the C<for> loop, thus the name of the rule. - - for 1, 2, 3 { } # List of 3 things; 3 iterations - for (1, 2, 3) { } # List of 3 things; 3 iterations - for [1, 2, 3] { } # Array of 3 things (put in Scalars); 3 iterations - for @a, @b { } # List of 2 things; 2 iterations - for (@a,) { } # List of 1 thing; 1 iteration - for (@a) { } # List of @a.elems things; @a.elems iterations - for @a { } # List of @a.elems things; @a.elems iterations - -The first two are equivalent because parentheses do not actually construct a -list, but only group. It is the C<< infix:<,> >> operator that forms a list. -The third also performs three iterations, since in Perl 6 C<[...]> constructs -an C<Array> but does not wrap it into a C<Scalar> container. The fourth will -do two iterations, since the argument is a list of two things; that they both -happen to have the C<@>-sigil does not, alone, lead to any kind of flattening. -The same goes for the fifth; C<< infix:<,> >> will happily form a list of one -thing. - -The single argument rule does respect C<Scalar> containers. Therefore: - - for $(1, 2, 3) { } # List in a Scalar; 1 iteration - for $[1, 2, 3] { } # Array in a Scalar; 1 iteration - for $@a { } # Array in a Scalar; 1 iteration - -The single argument rule is implemented consistently throughout the language. -For example, consider the C<append> method: - - @a.append: 1, 2, 3; # appends 3 values to @a - @a.append: [1, 2, 3]; # appends 3 values to @a - @a.append: @b; # appends @b.elems values to @a - @a.append: @b,; # same, trailing comma doesn't make > 1 argument - @a.append: $(1, 2, 3); # appends 1 value (a List) to @a - @a.append: $[1, 2, 3]; # appends 1 value (an Array) to @a - -Additionally, the list constructor (the C<< infix:<,> >> operator) and the -array composer (the C<[...]> circumfix) follow the rule: - - [1, 2, 3] # Array of 3 elements - [@a, @b] # Array of 2 elements - [@a, 1..10] # Array of 2 elements - [@a] # Array with the elements of @a copied into it - [1..10] # Array with 10 elements - [$@a] # Array with 1 element (@a) - [@a,] # Array with 1 element (@a) - [[1]] # Same as [1] - [[1],] # Array with a single element that is [1] - [$[1]] # Array with a single element that is [1] - -The only one of these that is likely to provide a surprise is C<[[1]]>, but it -is deemed sufficiently rare that it does not warrant an exception to the very -general single argument rule. - -=head1 User-level Types - -=head2 List - -A C<List> is an immutable, potentially infinite, list of values. The simplest -way to form a List is with the C<< infix:<,> >> operator: - - 1, 2, 3 - -A C<List> can be indexed and, provided it is finite, asked for its number of -elements: - - say (1, 2, 3)[1]; # 2 - say (1, 2, 3).elems; # 3 - -As it is immutable, it is not possible to C<push>, C<pop>, C<shift>, -C<unshift>, or C<splice> a C<List>. The C<reverse> and C<rotate> operations -return new C<List>s. - -While a C<List> itself is immutable, it may freely contain mutable things, -including C<Scalar> containers. Thus: - - my $a = 2; - my $b = 4; - ($a, $b)[0]++; - ($a, $b)[1] *= 2; - say $a; # 3 - say $b; # 8 - -Trying to assign to an immutable value in a C<List> is an error, however. - - (1, 2, 3)[0]++; # Dies: Cannot assign to an immutable value - -=head2 Slip - -The C<Slip> type is a subclass of C<List>. A C<Slip> will have its values -incorporated into a surrounding C<List>. - - (1, (2, 3), 4).elems # 3 - (1, slip(2, 3), 4).elems # 4 - -It is possible to coerce a C<List> to a C<Slip>, so the above can also be -written as: - - (1, (2, 3).Slip, 4).elems # 4 - -This is a common way to get flattening in places it will not magically take -place: - - my @a = 1, 2, 3; - my @b = 4, 5; - for @a.Slip, @b.Slip { } # 5 iterations - -It's also a bit verbose, which is why the C<< prefix:<|> >> operator will, -anywhere other than a function call argument list, do a C<Slip> coercion: - - my @a = 1, 2, 3; - my @b = 4, 5; - for |@a, |@b { } # 5 iterations - -It can also be useful in forms such as: - - my @prefixed-values = 0, |@values; - -Where the single argument rule would otherwise make C<@prefixed-values> have -two elements, the zero and C<@values>. - -The C<Slip> type is also respected by C<map>, C<gather>/C<take>, and lazy -loops. It is the way a C<map> can place multiple values into its result -stream: - - my @a = 1, 2; - say @a.map({ $_ xx 2 }).elems; # 2 - say @a.map({ |($_ xx 2) }).elems; # 4 - -=head2 Array - -An C<Array> is a subclass of C<List> that places values assigned to it into -C<Scalar> containers, meaning they can be mutated. It is the default type -that an C<@>-sigil variable gets. - - my @a = 1, 2, 3; - say @a.WHAT; # (Array) - @a[1]++; - say @a; # 1 3 3 - -In the absence of a shape specification, it will grow automatically. - - my @a; - @a[5] = 42; - say @a.elems; # 6 - -An C<Array> supports C<push>, C<pop>, C<shift>, C<unshift>, and C<splice>. - -Assignment to an array is eager by default, and creates a new set of Scalar -containers: - - my @a = 1, 2, 3; - my @b = @a; - @a[1]++; - say @b; # 1, 2, 3 - -Note that the C<[...]> C<Array> constructor is equivalent to creating and -then assigning to an anonymous C<Array>, and so has the same semantics with -regard to eagerness and fresh containers. - -=head2 Seq - -A C<Seq> is a one-shot producer of values. Most list processing operations -return a C<Seq>, as do most synchronous sources of multiple values. - - say (1, 2, 3).map(* + 1).^name; # Seq - say (1, 2 Z 'a', 'b').^name; # Seq - say (1, 1, * + * ... *).^name; # Seq - say $*IN.lines.^name; # Seq - -Since a C<Seq> will not by default remember its values, it can only be -consumed once. For example, if a C<Seq> is stored: - - my \seq = (1, 2, 3).map(* + 1); - -Then only one attempt to iterate it will work; subsequent attempts will die -as the values have already been consumed: - - for seq { .say } # 2\n3\n4\n - for seq { .say } # Dies: This Seq has already been iterated - -This means you can be confident that a loop going over a file's lines: - - for open('data').lines { - .say if /beer/; - } - -Will not be retaining the lines of the file in memory. Additionally, it is -easy to set up processing pipelines that also will not retain all of the -lines in memory: - - my \lines = open('products').lines; - my \beer = lines.grep(/beer/); - my \excited = beer.map(&uc); - .say for excited; - -However, any attempt to re-use C<lines>, C<beer>, or C<excited> will result -in an error. This program is equivalent in performance to: - - .say for open('products').lines.grep(/beer/).map(&uc); - -But provides a chance to name the stages. Note that it's possible to use -C<Scalar> variables instead, but the single argument rule means that the -final loop would have to be: - - .say for |$excited; - -Assigning a C<Seq> to an C<Array> will - so long as the sequence is not -marked lazy - eagerly perform the operation and store the results into -the C<Array>. Therefore, there are no surprises to anyone writing: - - my @lines = open('products').lines; - my @beer = @lines.grep(/beer/); - my @excited = @beer.map(&uc); - .say for @excited; - -Re-using any of these arrays will work out fine. Of course, the memory -behavior of this program is radically different, and it will be slower -due to all of the extra C<Scalar> containers created (resulting in extra -garbage collection) and poor locality of reference (we have to talk about -the same string many times over the programs lifetime). - -Occasionally it can be useful to request that a C<Seq> cache itself. This -can be done by calling the C<cache> method on a C<Seq>, which makes a lazy -C<List> from the C<Seq> and returns it. Subsequent calls to C<cache> will -return the same lazy list. Note that the first call to C<cache> counts as -consuming the C<Seq>, and so it will not work out if any prior iteration -has taken place, and any later attempt to iterate the C<Seq> after calling -C<cache> will also fail. It is only C<.cache> which may be called more than -once. - -A C<Seq> does not do the C<Positional> role like a C<List>. Therefore, -it can not be bound to an C<@>-sigil variable: - - my @lines := $*IN.lines; # Dies - -One consequence of this is that, naively, you could not pass a C<Seq> as an -argument to be bound to an C<@>-sigil parameter: - - sub process(@data) { - } - process($*IN.lines); - -This would be rather too inconvenient. Therefore, the signature binder (which -actually uses C<::=> assignment semantics rather than C<:=>) will spot failure -to bind the <@>-sigil parameter, and then check if the argument does the -C<PositionalBindFailover> role. If it does, then it will call the C<cache> -method on the argument and bind the result of that instead. - -=head2 Iterable - -Both C<Seq> and C<List>, along with various other types in Perl 6, do the -C<Iterable> role. The primary purpose of this role is to promise that an -C<iterator> method is available. The average Perl 6 user will rarely need -to care about the C<iterator> method and what it returns. - -The secondary purpose of C<Iterable> is to mark out things that will -flatten on demand, when the C<flat> method or function is used on them. - - my @a = 1, 2, 3; - my @b = 4, 5; - for flat @a, @b { } # 5 iterations - say [flat @a, @b].elems; # 5 - -Another use of C<flat> is to flatten nested C<List> structure. For example, -the C<Z> (zip) operator produces a C<List> of C<List>: - - say (1, 2 Z 'a', 'b').perl; # ((1, "a"), (2, "b")).Seq - -A C<flat> can be used to flatten these, which is useful in conjunction with -a C<for> loop using a pointy block with multiple parameters: - - for flat 1, 2 Z 'a', 'b' -> $num, $letter { } - -Note that C<flat> respects C<Scalar> containers, and so: - - for flat $(1, 2) { } - -Will only do one iteration. Remember that an C<Array> stores everything in a -C<Scalar> container, and so C<flat> on an C<Array> - short of weird tricks -with binding - will always be the same as iterating over the C<Array> itself. -In fact, the C<flat> method on an C<Array> returns identity. - -=head2 HyperSeq - -=head2 array - -=head1 The Iterator API and Implementation Types - -=head2 The Iterator role - -=head2 The IterationBuffer class - -=head1 Parallelism - -=head1 AUTHORS - - Jonathan Worthington <jnthn@jnthn.net> - -=for vim:set expandtab sw=4: diff --git a/S08-capture.pod b/S08-capture.pod deleted file mode 100644 index c18ab88b..00000000 --- a/S08-capture.pod +++ /dev/null @@ -1,219 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 8: Capture and Argument Lists - -=head1 VERSION - - Created: 20 Sep 2009 - - Last Modified: 16 Oct 2015 - Version: 3 - -=head1 Introduction - -Unlike most programming languages, the data structure that is used to -send the parameters into a routine invocation (be it a method or a -sub) is exposed to the language as a built-in type like any -other. This represents a very important aspect of the Perl 6 runtime -requirements. - -Additionally to the fact that this data structure is visible in the -language type system, it is not assumed that the capture is a native -type, which means that the internal representation of the data is -subject to change. The only thing the runtime can assume is the API -described here. - -Of course the runtime can cheat whenever it knows the capture is -implemented by its own internal data structure for optimization -purposes, but it should allow the use of foreign types when invoking a -routine, as long as the object says true to C<.^does(Capture)>. - -Captures and argument lists are also the basis for the multidimensionality of -lists in Perl 6. Unlike Perl 5, no flattening happens unless it's -explicitly required by the user, which is done by enforcing the list -context. If you use the item context the dimensionality should be -preserved. - -In addition to the list and item context, there's also a special -context, which is, in a simplified way, called "Capture context", but -it actually means "deferred context", in a way that the Capture or -List is kept as-is while they are manipulated in the code. This is -useful to avoid unwanted flattening as well as avoiding the DWIMmy -features that might change the capture's behavior. - -This is the main point of why Captures replace Perl 5 -references; they allow you to send data untouched from one place to -another. The second reason is that as in Perl 6 everything is an -object, there isn't really "pass-by-value" anymore, you're always -sending a reference, Captures simply carry other objects -without enforcing any context on them. - -=head1 Capture or List - -While a C<Capture> is the object that holds the parameters sent to a -routine (positional and named), a C<List> is a more fundamental data -structure that doesn't really differentiate named arguments from -positional arguments. - -A list doesn't enforce any context, so a way that no flattening -or coercion is done. When you examine a list object, it -will include all the listed items, whether they look like named -arguments or positional arguments. For example: - - 1, 2, :a<b> - -The list represented here has 3 positional items. A List -might be statically converted to a Capture if it's clear to the parser -that it's being used as the arguments to a routine call. - -A Capture, on the other hand, is not required to keep the positional -information for the named arguments, for example: - - foo(1,:a<b>,2) - -In the call to the routine foo, there are only two positional -arguments and one named argument, and you won't be able to find "b" -from the C<Positional> interface, but only from the Associative. - -The differentiation from List and Capture is important to keep the -regular use of inline declarations consistent, let's say you do the -following: - - my $a = (0, :a<b>, 2); - say $a[2]; - -If we had Capture and List as the same data structure, you wouldn't -get C<2> as the result of the above code, because there are only two -positional arguments, not three. Using the same example: - - sub foo($p1, $p2, :$a) {...} - foo(|$a); - -In that case, the List is converted into a Capture, and therefore -the pair C<< :a<b> >> is no longer visible as a positional argument, -only as named. - -Note that once you convert a List into a Capture, you won't be able -to get the original List again, because a Capture doesn't hold the -information about the position of named arguments. - -=head1 Multidimensionality - -Probably the most important task of Lists and Captures is to -implement the multidimensionality of lists in Perl 6, this means that -the barrier used to detect the dimensionality of the data structures -by the operators is whatever the item inside it implements List or -Capture. For instance: - - my $a = (1, (2, (3, 4))); - say $a[1]; - -In that case, you'll get C<2, (3, 4)> (or whatever is implemented in -the .Str method of that specific List). - -But, you should be able to: - - say $a[1;0]; - -Which is going to return C<2>, which is almost the same as: - - say $a[1][0]; - -But the first provides a more convenient and optimizeable way of -asking for it. If you want to get the value C<4> from that data -structure you need to: - - say $a[1;1;1]; - -Note that if you assign that list to an array, it will be flattened, -so: - - my @a = 1, (2, (3, 4)); - say @a[3]; - -Would print C<4>, at the same time that trying to ask for -multidimensionality information from that list would result in a -failure: - - say @a[1;1;1]; - -As the element 1 of the array C<@a> is not a Capture or a List, it is -not possible for the C<.[]> operator to traverse it. - -[Conjecture: It is still not clear if the multidimensional access -should be able to get into regular arrays, i.e.: C<[1,[2,[3,[4]]]] ]> - -It is important to realize that it's not the parens that are creating -the List, but the C<< infix:<,> >>. The parens are only required in -order to define a sub-list. - -On the other hand, if you bind a list to a variable, it doesn't -really matter which sigil it uses: - - my @a := (1, (2, (3, 4))); - say @a[1;1;1]; # "4" - say @a[3]; # failure - -Captures and argument lists are seen the same way regarding -multidimensionality, for instance: - - my $a = ((map { $_ * 2 }, 1..5),(map { $_ / 2 }, 1..5)); - say $a[0;0]; # 2 - say $a[1;0]; # 0.5 - -The same way, if each map closure returns more than one item inside -its capture: - - my $a = ((map { $_ * 2, $_ / 2 }, 1..5),(map { $_ / 2, $_ * 2 }, 1..5)); - say $a[0;0;0]; # 2 - say $a[0;0;1]; # 0.5 - say $a[1;0;0]; # 0.5 - say $a[1;0;0]; # 2 - -The flattening process will traverse into Lists and Captures, so: - - 1, (2, (3, 4)) - -will result in: - - 1, 2, 3, 4 - -after flattening, while: - - 1, [2, [3, 4]] - -Would remain as-is. - -=head1 Context deferral - -Also known as "Capture Context", defines how you can defer the context -coercion for a given value. That is a fundamental feature because -something as simple as assigning to a scalar might imply context -coercion that would get you a modified value. - -Capture context is able to preserve the values as-is, -in a way that you can later apply any context and have the same result -as if the context was applied immediately. - -Context deferral is actually the reason why Perl 6 no longer supports -the "wantarray" operator, nor does it provide any substitute. The way -you should implement wantarray-like behavior is by properly overriding -the coercion for each context. The Contextual::Return module is an -implementation of that concept in Perl 5. - -[ The capture sigil does not exist, though left in this document for the time -being pending a suitable replacement mechanism to handle context deferral.] - -In order to use the context deferral in your code, you need to use the -"capture sigil", which can be presented in two forms: - - my ¢a = (1, (2, (3, 4))); - -=head1 AUTHORS - - Daniel Ruoso <daniel@ruoso.com> - -=for vim:set expandtab sw=4: diff --git a/S09-data.pod b/S09-data.pod deleted file mode 100644 index 9abdecd6..00000000 --- a/S09-data.pod +++ /dev/null @@ -1,1329 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 9: Data Structures - -=head1 VERSION - - Created: 13 Sep 2004 - - Last Modified: 16 Oct 2015 - Version: 52 - -=head1 Overview - -This synopsis summarizes the non-existent Apocalypse 9, which -discussed in detail the design of Perl 6 data structures. It was -primarily a discussion of how the existing features of Perl 6 combine -to make it easier for the PDL folks to write numeric Perl. - -=head1 Lazy lists - -All list contexts are lazy by default. They might still flatten -eventually, but only when forced to. You have to use the C<eager> -list operator to get a non-lazy list context, and you have to use the -C<flat> operator to guarantee flattening. However, such context is -generally provided by the eventual destination anyway, so you don't -usually need to be explicit. - -=head1 Sized types - -Sized low-level types are named most generally by appending the number -of bits to a generic low-level type name: - - int1 - int2 - int4 - int8 - int16 - int32 (aka int on 32-bit machines) - int64 (aka int on 64-bit machines) - int128 (aka int on 128-bit machines) - - uint1 (aka bit) - uint2 - uint4 - uint8 (aka byte) - uint16 - uint32 - uint64 - uint128 - - num16 - num32 - num64 (aka num on most architectures) - num128 - - complex16 - complex32 - complex64 (aka complex on most architectures) - complex128 - - rat8 - rat16 - rat32 - rat64 - rat128 - - buf8 aka buf, a "normal" byte buffer - buf16 a uint16 buffer - buf32 a uint32 buffer - buf64 a uint64 buffer - -Complex sizes indicate the size of each C<num> component rather than -the total. This would extend to tensor typenames as well if they're -built-in types. Of course, the typical tensor structure is just -reflected in the dimensions of the array--but the principle still holds -that the name is based on the number of bits of the simple base type. - -The unsized types C<int> and C<num> are based on the architecture's -normal size for C<int> and C<double> in whatever version of C the -run-time system is compiled in. So C<int> -typically means C<int32> or C<int64>, while C<num> usually means -C<num64>, and C<complex> means two of whatever C<num> turns out to be. -For symmetry around the decimal point, native C<rat>s have a numerator -that is twice the size of their denominator, such that a C<rat32> actually -has an C<int64> for its numerator. Custom rational types may -be created by instantiating the C<Rational> role with two types; -if both types used are native types, the resulting type is considered a native type. - -You are, of course, free to use macros or type declarations to -associate additional names, such as "short" or "single". These are -not provided by default. An implementation of Perl is not required -to support 64-bit integer types or 128-bit floating-point types unless -the underlying architecture supports them. 16-bit floating-point is -also considered optional in this sense. - -And yes, an C<int1> can store only -1 or 0. I'm sure someone'll think of -a use for it... - -Note that these are primarily intended to represent storage types; -the compiler is generally free to keep all intermediate results in -wider types in the absence of declarations or explicit casts to the -contrary. Attempts to store an intermediate result in a location -that cannot hold it will generally produce a warning on overflow. -Underflow may also warn depending on the pragmatic context and use -of explicit rounding operators. The default rounding mode from -C<Num> to C<Int> is to truncate the fractional part without warning. -(Note that warnings are by definition resumable exceptions; however, -an exception handler is free to either transform such a warning into -a fatal exception or ignore it completely.) - -An explicit cast to a storage type has the same potential to throw an -exception as the actual attempt to store to such a storage location -would. - -With IEEE floating-point types, we have a bias towards the use -of in-band C<+Inf>, C<-Inf>, and C<NaN> values in preference to -throwing an exception, since this is construed as friendlier to vector -processing and pipelining. Object types such as C<Num> and C<Int> -may store additional information about the nature of the failure, -perhaps as an unthrown exception or warning. - -=head1 Compact structs - -A class whose attributes are all low-level value types can behave as -a struct. (Access from outside the class is still only through -accessors, though, except when the address of a serialized version of -the object is used or generated for interfacing to C-like languages.) -Whether such a class is actually stored compactly is up to the -implementation, but it ought to behave that way, at least to the -extent that it's trivially easy (from the user's perspective) to read -and write to the equivalent C structure. That is, when serialized -or deserialized to the C view, it should look like the C struct, -even if that's not how it's actually represented inside the class. -(This is to be construed as a substitute for at least some of the -current uses of C<pack>/C<unpack>.) Of course, a lazy implementation will -probably find it easiest just to keep the object in its serialized form -all the time. In particular, an array of compact structs must be stored -in their serialized form (see next section). - -For types that exist in the C programming language, the serialized -mapping in memory should follow the same alignment and padding -rules by default. Integers smaller than a byte are packed into a -power-of-two number of bits, so a byte holds four 2-bit integers. -Datum sizes that are not a power of two bits are not supported -unless declared by the user with sufficient information to determine -how to lay them out in memory, possibly with a pack/unpack format -associated with the class, or with the strange elements of the class, -or with the types under which the strange element is declared. - -Note that a compact struct that has no mutators is itself a value type, so except for -performance considerations, it doesn't matter how many representations -of it there are in memory as long as those are consistent. On the other -hand, structs with mutators must behave more like normal mutable objects. - -The packing serialization is performed by coercion to an appropriate -buffer type. The unpacking is performed by coercion of such a buffer -type back to the type of the compact struct. - -=head1 Standard array indexing - -Standard array indices are specified using square brackets. Standard -indices always start at zero in each dimension of the array (see -L<"Multidimensional arrays">), and are always contiguous: - - @dwarves[0] = "Happy"; # The 1st dwarf - @dwarves[6] = "Doc"; # The 7th dwarf - - @seasons[0] = "Spring"; # The 1st season - @seasons[2] = "Autumn"|"Fall"; # The 3rd season - - -=head1 Fixed-size arrays - -A basic array declaration like: - - my @array; - -declares a one-dimensional array of indeterminate length. Such arrays -are autoextending. For many purposes, though, it's useful to define -array types of a particular size and shape that, instead of -autoextending, fail if you try to access outside their -declared dimensionality. Such arrays tend to be faster to allocate and -access as well. (The language must, however, continue to protect you -against overflow--these days, that's not just a reliability issue, but -also a security issue.) - -To declare an array of fixed size, specify its maximum number of elements -in square brackets immediately after its name: - - my @dwarves[7]; # Valid indices are 0..6 - - my @seasons[4]; # Valid indices are 0..3 - -No intervening whitespace is permitted between the name and the size -specification, but "unspace" is allowed: - - my @values[10]; # Okay - my @keys [10]; # Error - my @keys\ [10]; # Okay - -Note that the square brackets are a compile-time declarator, not a run-time -operator, so you can't use the "dotted" form either: - - my @values.[10]; # An indexing, not a fixed-size declaration - my @keys\ .[10]; # Ditto - -Attempting to access an index outside an array's defined range will fail: - - @dwarves[7] = 'Sneaky'; # Fails with "invalid index" exception - -However, it is legal for a range or sequence iterator to extend beyond the end -of an array as long as its min value is a valid subscript; when used as an -rvalue, the range is truncated as necessary to map only valid locations. -(When used as an lvalue, any non-existent subscripts generate WHENCE proxies -that can receive new values and autovivify anything that needs it.) - -It's also possible to explicitly specify a normal autoextending array: - - my @vices[*]; # Length is: "whatever" - # Valid indices are 0..* - -For subscripts containing range or sequence iterators extending beyond the end of -autoextending arrays, the range is truncated to the actual current -size of the array rather than the declared size of that dimension. -It is allowed for such a range to start one after the end, so that - - @array[0..*] - -merely returns C<()> if C<@array> happens to be empty. However, - - @array[1..*] - -would fail because the range's min is too big. - -Note that these rules mean it doesn't matter whether you say - - @array[*] - @array[0 .. *] - @array[0 .. *-1] - -because they all end up meaning the same thing. - -There is no autotruncation on the left end. It's not that -hard to write C<0>, and standard indexes always start there. - -Subscript size declarations may add a named C<:map> argument -supplying a closure, indicating that all index values are to be mapped -through that closure. For example, a subscript may be declared as cyclical: - - my @seasons[4, :map( * % 4 )]; - my @seasons[4, :map{ $_ % 4 }]; # same thing - -In this case, all numeric values are taken modulo 4, and no range truncation can -ever happen. If you say - - @seasons[-4..7] = 'a' .. 'l'; - -then each element is written three times and the array ends up with -C<['i','j','k','l']>. The mapping function is allowed to return -fractional values; the index will be the C<floor> of that value. -(It is still illegal to use a numeric index less that 0.) One could -map indexes logarithmically, for instance, as long as the numbers -aren't so small they produce negative indices. - -Another use might be to map positive numbers to even slots and negative -numbers to odd slots, so you get indices that are symmetric around 0 -(though Perl is not going to track the max-used even and odd slots -for you when the data isn't symmetric). - -=head1 Typed arrays - -The type of value stored in each element of the array (normally C<Any> for unspecified type) -can be explicitly specified too, as an external C<of> type: - - my num @nums; # Each element stores a native number - my @nums of num; # Same - - my Book @library[1_000_000]; # Each element stores a Book object - my @library[1_000_000] of Book; # Same - -Alternatively, the element storage type may be specified as part of the -dimension specifier (much like a subroutine definition): - - my @nums[-->num]; - - my @library[1_000_000 --> Book]; - - -=head1 Compact arrays - -In declarations of the form: - - my bit @bits; - my int @ints; - my num @nums; - my int4 @nybbles; - my buf @buffers; - my complex128 @longdoublecomplex; - my Array @ragged2d; - -the presence of a low-level type tells Perl that it is free to -implement the array with "compact storage", that is, with a chunk -of memory containing contiguous (or as contiguous as practical) -elements of the specified type without any fancy object boxing that -typically applies to undifferentiated scalars. (Perl tries really -hard to make these elements look like objects when you treat them -like objects--this is called autoboxing.) - -Unless explicitly declared to be of fixed size, such -arrays are autoextending just like ordinary Perl arrays -(at the price of occasionally copying the block of data to another -memory location, or using a tree structure). - -A compact array is for most purposes interchangeable with the -corresponding buffer type. For example, apart from the sigil, -these are equivalent declarations: - - my uint8 @buffer; - my buf8 $buffer; - -(Note: If you actually said both of those, you'd still get two -different names, since the sigil is part of the name.) - -So given C<@buffer> you can say - - $piece = substr(@buffer, $beg, $end - $beg); - -and given C<$buffer> you can also say - - @pieces = $buffer[$n ..^ $end]; - -Note that subscripting still pulls the elements out as numbers, -but C<substr()> returns a buffer of the same type. - -For types that exist in the C programming language, the mapping in -memory should follow the same alignment rules, at least in the absence -of any declaration to the contrary. For interfacing to C pointer -types, any buffer type may be used for its memory pointer; note, -however, that the buffer knows its length, while in C that length -typically must be passed as a separate argument, so the C interfacing -code needs to support this whenever possible, lest Perl inherit all -the buffer overrun bugs bequeathed on us by C. Random C pointers -should never be converted to buffers unless the length is also known. -(Any call to strlen() should generally be considered a security hole.) -The size of any buffer type in bytes may be found with the C<.bytes> -method, even if the type of the buffer elements is not C<byte>. -(Strings may be asked for their size in bytes only if they support -a buffer type as their minimum abstraction level, hopefully with a -known encoding. Otherwise you must encode them explicitly from the -higher-level abstraction into some buffer type.) - - -=head1 Multidimensional arrays - -Perl 6 arrays are not restricted to being one-dimensional (that's simply -the default). To declare a multidimensional array, you specify it with a -semicolon-separated list of dimension lengths: - - my int @ints[4;2]; # Valid indices are 0..3 ; 0..1 - - my @calendar[12;31;24]; # Valid indices are 0..11 ; 0..30 ; 0..23 - -Arrays may also be defined with a mixture of fixed and autoextending -dimensions. For example, there are always 12 months in a year and -24 hours in a day, but the number of days in the month can vary: - - my @calendar[12;*;24]; # day-of-month dimension unlimited/ragged - -You can pass a slice (of any dimensionality) for the shape as well: - - @shape = 4, 2; - my int @ints[ ||@shape ]; - -The C<< prefix:<||> >> operator interpolates a list into a semicolon list at -the semicolon level. - -The shape in the declaration merely specifies how the array will -autovivify on first use, but ends up as an attribute of the actual -container object thereby. On the other hand, the shape may be also -supplied entirely by an explicit constructor at run-time: - - my num @nums = Array of num.new(:shape(3;3;3)); - my num @nums .=new():shape(3;3;3); # same thing - -A multidimensional array is indexed by a semicolon list (or "semilist"), which -is really a list of lists in disguise. Each sublist is a slice of one -particular dimension. So: - - @array[0..10; 42; @x] - -is really short for something like: - - @array.postcircumfix:<[ ]>( (0..10), (42), (@x) ); - -The method's internal C<**@slices> parameter turns the subscripts into three -independent lists, which can be read lazily independently of one other. -(Though a subscripter will typically use them left-to-right as it slices each - dimension in turn.) - -Note that: - - @array[@x,@y] - -is always interpreted as a one-dimensional slice in the outermost -dimension, which is the same as: - - @array[@x,@y;] - -or more verbosely: - - @array.postcircumfix:<[ ]>( ((@x,@y)) ); - -To interpolate an array at the semicolon level rather than the comma level, -use the C<< prefix:<||> >> operator: - - @array[||@x] - -which is equivalent to - - @array.postcircumfix:<[ ]>( ((@x[0]), (@x[1]), (@x[2]), etc.) ); - -=head2 Autoextending multidimensional arrays - -Any dimension of the array may be declared as "C<*>", in which case -that dimension will autoextend. Typically this would be used in the -final dimension to make a ragged array functionally equivalent to an -array of arrays: - - my int @ints[42; *]; # Second dimension unlimited/ragged - push(@ints[41], getsomeints()); - -but I<any> dimension of an array may be declared as autoextending: - - my @calendar[12;*;24]; # day-of-month dimension unlimited/ragged - @calendar[1;42;8] = 'meeting' # See you on January 42nd - -It is also possible to specify that an array has an arbitrary number -of dimensions, using a "hyperwhatever" (C<**>) at the end of the -dimensional specification: - - my @grid[**]; # Any number of dimensions - my @spacetime[*;*;*;**]; # Three or more dimensions - my @coordinates[100;100;100;**]; # Three or more dimensions - -Note that C<**> is a shorthand for something that means C<||(* xx *)>, so the extra -dimensions are all of arbitrary size. To specify an arbitrary number -of fixed-size dimensions, write: - - my @coordinates[ ||(100 xx *) ]; - -This syntax is also convenient if you need to define a large number of -consistently sized dimensions: - - my @string_theory[ ||(100 xx 11) ]; # 11-dimensional - -=head1 User-defined array indexing - -Any array may also be given a second set of user-defined indices, which -need not be zero-based, monotonic, or even integers. Whereas standard array -indices always start at zero, user-defined indices may start at any -finite value of any enumerable type. Standard indices are always -contiguous, but user-defined indices need only be distinct and in an -enumerable sequence. - -To define a set of user-defined indices, specify an explicit or -enumerable list of the indices of each dimension (or the name of an -enumerable type) in a set of curly braces immediately after the -array name: - - my @dwarves{ 1..7 }; - my @seasons{ <Spring Summer Autumn Winter> }; - - my enum Months - «:Jan(1) Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec»; - - my @calendar{ Months; 1..31; 9..12,14..17 }; # Business hours only - -Array look-ups via user-defined indices are likewise specified in curly -braces instead of square brackets: - - @dwarves{7} = "Doc"; # The 7th dwarf - - say @calendar{Jan;13;10}; # Jan 13th, 10am - -User-defined indices merely provide a second, non-standard "view" of the -array; the underlying container remains the same. Each user-defined -index in each dimension is mapped one-to-one back to the standard (zero- -based) indices of that dimension. So, given the preceding definitions: - - maps to - @dwarves{1} ------> @dwarves[0] - @dwarves{2} ------> @dwarves[1] - : : - @dwarves{7} ------> @dwarves[6] - -and: - - maps to - @seasons{'Spring'} ------> @seasons[0] - @seasons{'Summer'} ------> @seasons[1] - @seasons{'Autumn'} ------> @seasons[2] - @seasons{'Winter'} ------> @seasons[3] - - @seasons<Spring> ------> @seasons[0] - @seasons<Summer> ------> @seasons[1] - @seasons<Autumn> ------> @seasons[2] - @seasons<Winter> ------> @seasons[3] - -and: - - maps to - @calendar{Jan;1;9} ------> @calendar[0;0;0] - @calendar{Jan;1;10} ------> @calendar[0;0;1] - : : - @calendar{Jan;1;12} ------> @calendar[0;0;3] - @calendar{Jan;1;14} ------> @calendar[0;0;4] - : : - @calendar{Feb;1;9} ------> @calendar[1;0;0] - : : - @calendar{Dec;31;17} ------> @calendar[11;30;7] - -User-defined indices can be open-ended, but only on the upper end (i.e. -just like standard indices). That is, you can specify: - - my @sins{7..*}; # Indices are: 7, 8, 9, etc. - -but not: - - my @virtue{*..6}; - my @celebs{*}; - -These last two are not allowed because there is no first index, and -hence no way to map the infinity of negative user-defined indices back -to the standard zero-based indexing scheme. - -Declaring a set of user-defined indices implicitly declares the array's -standard indices as well (which are still zero-based in each dimension). -Such arrays can be accessed using either notation. The standard indices -provide an easy way of referring to "ordinal" positions, independent of -user-specified indices: - - say "The first sin was @sins[0]"; - # First element, no matter what @sin's user-defined indexes are - -Note that if an array is defined with fixed indices (either standard or -user-defined), any attempt to use an index that wasn't specified in the -definition will fail. For example: - - my @values{2,3,5,7,11}; # Also has standard indices: 0..4 - - say @values[-1]; # Fails (not a valid standard index) - say @values{1}; # Fails (not a valid user-defined index) - - say @values{4}; # Fails (not a valid user-defined index) - - say @values[5]; # Fails (not a valid standard index) - say @values{13}; # Fails (not a valid user-defined index) - -Furthermore, if an array wasn't specified with user-defined indices, -I<any> attempt to index it via C<.{}> will fail: - - my @dwarves[7]; # No user-defined indices; - - say @dwarves{1}; # Fails: can't map .{1} to a standard .[] index - -When C<:k>, C<:kv>, or C<:p> is applied to an array slice, it returns -the kind of indices that were used to produce the slice: - - @arr[0..2]:p # 0=>'one', 1=>'two', 2=>'three' - @arr{1,3,5}:p # 1=>'one', 3=>'two', 5=>'three' - -Adverbs may be applied only to operators, not to terms, so C<:k>, -C<:kv>, and C<:p> may not be applied to a full array. However, you -may apply an adverb to a Zen slice, which can indicate which set of -keys are desired: - - my @arr{1,3,5,7,9} = <one two three four five>; - - say @arr[]:k; # 0, 1, 2, 3, 4 - say @arr{}:k; # 1, 3, 5, 7, 9 - -The C<.keys> method also returns the keys of all existing elements. -For a multidimensional array each key is a list containing one value for -each dimension. - -The C<.shape> method also works on such an array; it returns a -slice of the valid keys for each dimension. The component list -representing an infinite dimension is necessarily represented lazily. -(Note that the C<.shape> method returns the possible keys, but the -cartesian product of the key slice dimensions is not guaranteed to -index existing elements in every case. That is, this is not intended -to reflect current combinations of keys in use (use C<:k> for that). -Note that you have to distinguish these two forms: - - @array[].shape # the integer indices - @array{}.shape # the user-defined indices - -=head1 Inclusive subscripts - -Within any array look-up (whether via C<.[]> or C<.{}>), the "whatever -star" can be used to indicate "all the indices". The meaning of -"all" here depends on the definition of the array. If there are no -pre-specified indices, the star means "all the indices of currently -allocated elements": - - my @data # No pre-specified indices - = 21, 43, 9, 11; # Four elements allocated - say @data[*]; # So same as: say @data[0..3] - - @data[5] = 101; # Now six elements allocated - say @data[*]; # So same as: say @data[0..5] - -If the array is defined with predeclared fixed indices (either standard -or user-defined), the star means "all the defined indices": - - my @results{1,3...99} # Pre-specified indices - = 42, 86, 99, 1; - - say @results[*]; # Same as: say @results[0..49] - say @results{*}; # Same as: say @results{1,3...99} - -You can omit unallocated elements, either by using the C<:v> adverb: - - say @results[*]:v; # Same as: say @results[0..3] - say @results{*}:v; # Same as: say @results{1,3,5,7} - -or by using a "zen slice": - - say @results[]; # Same as: say @results[0..3] - say @results{}; # Same as: say @results{1,3,5,7} - -A "whatever star" can also be used as the starting-point of a range -within a slice, in which case it means "from the first index": - - say @calendar[*..5]; # Same as: say @calendar[0..5] - say @calendar{*..Jun}; # Same as: say @calendar{Jan..Jun} - - say @data[*..3]; # Same as: say @data[0..3] - -As the end-point of a range, a lone "whatever" means "to the maximum -specified index" (if fixed indices were defined): - - say @calendar[5..*]; # Same as: say @calendar[5..11] - say @calendar{Jun..*}; # Same as: say @calendar{Jun..Dec} - -or "to the largest allocated index" (if there are no fixed indices): - - say @data[1..*]; # Same as: say @results[1..5] - -=head1 Negative and differential subscripts - -The "whatever star" behaves differently than described above when -it is treated as a number inside a standard index. In this case -it evaluates to the length of the array. This provides a clean -and consistent way to count back or forwards from the end of an -array: - - @array[*-$N] # $N-th element back from end of array - @array[*+$N] # $N-th element at or after end of array - -More specifically: - - @array[*-2] # Second-last element of the array - @array[*-1] # Last element of the array - @array[+*] # First element after the end of the array - @array[*+0] # First element after the end of the array - @array[*+1] # Second element after the end of the array - - @array[*-3..*-1] # Slice from third-last element to last element - @array[*-3..*] # (Same thing via range truncation) - -(Note that, if a particular array dimension has fixed indices, any -attempt to index elements after the last defined index will fail, -except in the case of range truncation described earlier.) - -Negative subscripts are never allowed for standard subscripts unless -the subscript is declared modular. - -The Perl 6 semantics avoids indexing discontinuities (a source of subtle -runtime errors), and provides ordinal access in both directions at both -ends of the array. - -=head1 Mixing subscripts - -Occasionally it's convenient to be able to mix standard and user-defined -indices in a single look-up. - -Within a C<.[]> indexing operation you can use C<*{$idx}> to -convert a user-defined index C<$idx> to a standard index. That is: - - my @lengths{ Months } = (31,28,31,30,31,30,31,31,30,31,30,31); - - @lengths[ 2 .. *{Oct} ] # Same as: @lengths[ 2 .. 9 ] - -Similarly, within a C<.{}> indexing operation you can use C<*[$idx]> -to convert from standard indices to user-defined: - - @lengths{ *[2] .. Oct } # Same as: @lengths{ Mar .. Oct } - -In other words, when treated as an array within an indexing -operation, C<*> allows you to convert between standard and -user-defined indices, by acting like an array of the indices -of the indexed array. This is especially useful for mixing -standard and user-defined indices within multidimensional -array look-ups: - - # First three business hours of every day in December... - @calendar{Dec; *; *[0..2]} - - # Last three business hours of first three days in July... - @calendar[*{July}; 0..2; *-3..*-1] - -Extending this feature, you can use C<**> within an indexing operation -as if it were a multidimensional array of I<all> the indices of a fixed -number of dimensions of the indexed array: - - # Last three business hours of first three days in July... - @calendar{ July; **[0..2; *-3..*-1] } - - # Same... - @calendar[ **{July; 1..3}; *-3..*-1] - -It is also possible to stack subscript declarations of various -types, including a final normal signature to specify named args -and return type: - - my @array[10]{'a'..'z'}(:$sparse --> MyType); - -[Note: the final signature syntax is merely reserved for now, and -not expected to work until we figure out what it really means, if -it means anything.] - -=head1 PDL support - -An array C<@array> can be tied to a PDL at declaration time: - - my num @array[||@mytensorshape] is PDL; - my @array is PDL(:shape(2;2;2;2)) of int8; - -PDLs are allowed to assume a type of C<num> by default rather than -the usual simple scalar. (And in general, the type info is merely -made available to the "tie" implementation to do with what it will. -Some data structures may ignore the "of" type and just store everything -as general scalars. Too bad...) - -Arrays by default are one dimensional, but may be declared to have any -dimensionality supported by the implementation. You may use arrays -just like scalars -- the main caveat is that you have to use -binding rather than assignment to set one without copying: - - @b := @a[0,2,4 ... *] - -With PDLs in particular, this might alias each of the individual -elements rather than the array as a whole. So modifications to @b -are likely to be reflected back into @a. (But maybe the PDLers will -prefer a different notation for that.) - -The dimensionality of an array may be declared on the variable, but -the actual dimensionality of the array depends on how it was created. -Reconciling these views is a job for the particular array implementation. -It's not necessarily the case that the declared dimensionality must match -the actual dimensionality. It's quite possible that the array variable -is deliberately declared with a different dimensionality to provide a -different "view" on the actual value: - - my int @array[2;2] is Puddle .= new(:shape(4) <== 0,1,2,3); - -Again, reconciling those ideas is up to the implementation, C<Puddle> -in this case. The traits system is flexible enough to pass any -metadata required, including ideas about sparseness, raggedness, -and various forms of non-rectangleness such as triangleness. -The implementation should probably carp about any metadata it doesn't -recognize though. The implementation is certainly free to reject -any object that doesn't conform to the variable's shape requirements. - -=head1 Subscript and slice notation - -A subscript indicates a "slice" of an array. Each dimension of an -array is sliced separately, so a multidimensional slice subscript -may be supplied as a semicolon-separated list of slice sublists. -A three-dimensional slice might look like this: - - @x[0..10; 1,0; 1,*+2...*] - -It is up to the implementation of C<@x> to decide how aggressively -or lazily this subscript is evaluated, and whether the slice entails -copying. (The PDL folks will generally want it to merely produce a -virtual PDL where the new array aliases its values back into the -old one.) - -Of course, a single element can be selected merely by providing a single -index value to each slice list: - - @x[0;1;42] - -=head1 Cascaded subscripting of multidimensional arrays - -For all multidimensional array types, it is expected that cascaded subscripts: - - @x[0][1][42] - @x[0..10][1,0][1,*+2...*] - -will either fail or produce the same results as the equivalent -semicolon subscripts: - - @x[0;1;42] - @x[0..10; 1,0; 1,*+2...*] - -Built-in array types are expected to succeed either way, even if -the cascaded subscript form must be implemented inefficiently by -constructing temporary slice objects for later subscripts to use. -(User-defined types may choose not to support the cascaded form, but -if so, they should fail rather than providing different semantics.) -As a consequence, for built-in types of declared shape, the appropriate -number of cascaded subscripts may always be optimized into the -semicolon form. - -=head1 The semicolon operator - -At the statement level, a semicolon terminates the current expression. -Within any kind of bracketing construct, semicolon notionally separates -the sublists of a multidimensional slice, the interpretation of -which depends on the context. Such a semicolon list treats each of its -sublists separately, deferring the context of the sublist until -it is bound somewhere. The storage of these sublists is hidden in -the inner workings of the list. It does not produce a list of lists -unless the list as a whole is bound into a slice context. - -Single dimensional arrays expect simple slice subscripts, meaning -they will treat a list subscript as a slice in the single dimension of -the array. Multi-dimensional arrays, on the other hand, know how to -handle a multidimensional slice, with one subslice for each dimension. You need not specify -all the dimensions; if you don't, the unspecified dimensions are -"wildcarded". Supposing you have: - - my num @nums[3;3;3]; - -Then - - @nums[0..2] - -is the same as - - @nums[0..2;] - -which is the same as - - @nums[0,1,2;*;*] - -But you should maybe write the last form anyway just for good -documentation, unless you don't actually know how many more dimensions -there are. For that case use C<**>: - - @nums[0,1,2;**] - -If you wanted that C<0..2> range to mean - - @nums[0;1;2] - -it is not good enough to use the C<|> prefix operator, because -that interpolates at the comma level, so: - - @nums[ |(0,1,2) ] - -just means - - @nums[ 0,1,2 ]; - -Instead, to interpolate at the semicolon level, you need to use the C<||> prefix operator: - - @nums[ ||(0..2) ] - -The zero-dimensional slice: - - @x[] - -is assumed to want everything, not nothing. It's particularly handy -because Perl 6 (unlike Perl 5) won't interpolate a bare array without brackets: - - @x = (1,2,3); - say "@x = @x[]"; # prints @x = 1 2 3 - -Lists are lazy in Perl 6, and the slice lists are no exception. -In particular, list generators are not flattened until they -need to be, if ever. So a PDL implementation is free to steal the -values from these generators and "piddle" around with them: - - @nums[$min ..^ $max] - @nums[$min, *+3 ... $max] - @nums[$min, *+3 ... *] - @nums[1,*+2...*] # the odds - @nums[0,*+2...*] # the evens - @nums[1,3...*] # the odds - @nums[0,2...*] # the evens - -=head1 PDL signatures - -To rewrite a Perl 5 PDL definition like this: - - pp_def( - 'inner', - Pars => 'a(n); b(n); [o]c(); ', # the signature, see above - Code => 'double tmp = 0; - loop(n) %{ tmp += $a() * $b(); %} - $c() = tmp;' ); - -you might want to write a macro that parses something vaguely -resembling this: - - role PDL_stuff[::TYPE] { - PDLsub inner (@a[$n], @b[$n] --> @c[]) { - my TYPE $tmp = 0; - for ^$n { - $tmp += @a[$_] * @b[$_]; - } - @c[] = tmp; - } - } - -where that turns into something like this: - - role PDL_stuff[::TYPE] { - multi inner (TYPE @a, TYPE @b --> TYPE) { - my $n = @a.shape[0]; # or maybe $n is just a parameter - assert($n == @b.shape[0]); # and this is already checked by PDL - my TYPE $tmp = 0; - for ^$n { - $tmp += @a[$_] * @b[$_]; - } - return $tmp; - } - } - -Then any class that C<does PDL_stuff[num]> has an C<inner()> function that -can (hopefully) be compiled down to a form useful to the PDL threading -engine. Presumably the macro also stores away the PDL signature -somewhere safe, since the translated code hides that information -down in procedural code. Possibly some of the C<[n]> information can -come back into the signature via C<where> constraints on the types. -This would presumably make multimethod dispatch possible on similarly -typed arrays with differing constraints. - -(The special destruction problems of Perl 5's PDL should go away with -Perl 6's GC approach, as long as PDL's objects are registered with the -run-time system correctly.) - -=head1 Autothreading types - -=head2 Junctions - -A junction is a superposition of data values pretending to be a single -data value. Junctions come in four varieties: - - list op infix op - ======= ======== - any() | - all() & - one() ^ - none() (no "nor" op defined) - -Note that the infix ops are "list-associative", insofar as - - $a | $b | $c - $a & $b & $c - $a ^ $b ^ $c - -mean - - any($a,$b,$c) - all($a,$b,$c) - one($a,$b,$c) - -rather than - - any(any($a,$b),$c) - all(all($a,$b),$c) - one(one($a,$b),$c) - -Some contexts, such as boolean contexts, have special rules for dealing -with junctions. In any item context not expecting a junction of -values, a junction produces automatic parallelization of the algorithm. -In particular, if a junction is used as an argument to any routine -(operator, closure, method, etc.), and the scalar parameter you -are attempting to bind the argument to is inconsistent with the -C<Junction> type, that routine is "autothreaded", meaning the routine -will be called automatically as many times as necessary to process -the individual scalar elements of the junction in parallel. -(C<Each> types are also autothreaded, but are serial and lazy in nature.) - -The results of these separate calls are then recombined into a -single junction of the same species as the junctive argument. -If two or more arguments are junctive, then the argument that is -chosen to be "autothreaded" is: - -=over - -=item * - -the left-most I<all> or I<none> junction (if any), or else - -=item * - -the left-most I<one> or I<any> junction - -=back - -with the tests applied in that order. - -Each of the resulting set of calls is then recursively autothreaded -until no more junctive arguments remain. That is: - - substr("camel", 0|1, 2&3) - - -> all( substr("camel", 0|1, 2), # autothread the conjunctive arg - substr("camel", 0|1, 3) - ) - - -> all( any( substr("camel", 0, 2), # autothread the disjunctive arg - substr("camel", 1, 2), - ), - any( substr("camel", 0, 3), # autothread the disjunctive arg - substr("camel", 1, 3), - ) - ) - - -> all( any( "ca", # evaluate - "am", - ), - any( "cam", - "ame", - ) - - -> ("ca"|"am") & ("cam"|"ame") # recombine results in junctions - -Junctions passed as part of a container do not cause autothreading -unless individually pulled out and used as a scalar. It follows that -junctions passed as members of a "slurpy" array or hash do not cause -autothreading on that parameter. Only individually declared parameters -may autothread. (Note that positional array and hash parameters are -in fact scalar parameters, though, so you could pass a junction of -array or hash objects.) - -The exact semantics of autothreading with respect to control structures -are subject to change over time; it is therefore erroneous to pass -junctions to any control construct that is not implemented via as a -normal single dispatch or function call. In particular, threading junctions -through conditionals correctly could involve continuations, which -are almost but not quite mandated in Perl 6.0.0. Alternately, we -may decide that boolean contexts always collapse the junction by -default, and the exact value that allowed the collapse to "true" -is not available. A variant of that is to say that if you want -autothreading of a control construct, you must assign or bind to -a non-C<Mu> container before the control construct, and that -assignment or binding to any such container results in autothreading -the rest of the dynamic scope. (The performance ramifications of this -are not clear without further experimentation, however.) So for now, -please limit use of junctions to situations where the eventual binding -to a scalar formal parameter is clear. - -=head2 Each - -[This section is considered conjectural.] - -An C<Each> type autothreads like a junction, but does so serially and lazily, -and is used only for its mapping capabilities. The prototypical use -case is where a hyperoperator would parallelize in an unfortunate way: - - @array».say # order not guaranteed - @array.each.say # order guaranteed - -=head1 Parallelized parameters and autothreading - -Within the scope of a C<use autoindex> pragma (or equivalent, such as -C<use PDL> (maybe)), any closure that uses parameters as subscripts -is also a candidate for autothreading. For each such parameter, the -compiler supplies a default value that is a range of all possible -values that subscript can take on (where "possible" is taken to -mean the declared shape of a shaped array, or the actual shape of an -autoextending array). That is, if you have a closure of the form: - - -> $x, $y { @foo[$x;$y] } - -then the compiler adds defaults for you, something like: - - -> $x = @foo.shape[0].range, - $y = @foo.shape[1].range { @foo[$x;$y] } - -where each such range is autoiterated for you. - -In the abstract (and often in the concrete), this puts an implicit -loop around the block of the closure that visits all the possible -subscript values for that dimension (unless the parameter is actually -supplied to the closure, in which case the supplied value is used as -the slice subscript instead). - -This implicit loop is assumed to be parallelizable. - -So to write a typical tensor multiplication: - - Cijkl = Aij * Bkl - -you can simply call a closure with no arguments, allowing the C<autoindex> -pragma to fill in the defaults: - - use autoindex; - -> $i, $j, $k, $l { @c[$i; $j; $k; $l] = @a[$i; $j] * @b[$k; $l] }(); - -or you can use the C<do BLOCK> syntax (see L<S04/"The do-once loop">) to -call that closure, which also implicitly iterates: - - use autoindex; - do -> $i, $j, $k, $l { - @c[$i; $j; $k; $l] = @a[$i; $j] * @b[$k; $l] - } - -or even use placeholder variables instead of a parameter list: - - use autoindex; - do { @c[$^i; $^j; $^k; $^l] = @a[$^i; $^j] * @b[$^k; $^l] }; - -That's almost pretty. - -It is erroneous for an unbound parameter to match multiple existing array -subscripts differently. (Arrays being created don't count.) - -Note that you could pass any of $i, $j, $k or $l explicitly, or prebind -them with a C<.assuming> method, in which only the unbound parameters -autothread. - -If you use an unbound array parameter as a semicolon-list interpolator -(via the C<< prefix:<||> >> operator), it functions as a wildcard list of -subscripts that must match the same everywhere that parameter is used. -For example, - - do -> @wild { @b[ ||@wild.reverse ] = @a[ ||@wild ] }; - -produces an array with the dimensions reversed regardless of the -dimensionality of C<@a>. - -The optimizer is, of course, free to optimize away any implicit loops -that it can figure out how to do more efficiently without changing -the semantics. - -See RFC 207 for more ideas on how to use autothreading (though the syntax -proposed there is rather different). - -=head1 Hashes - -Like arrays, you can specify hashes with multiple dimensions and fixed -sets of keys: - - my num %hash{<a b c d e f>}; # Only valid keys are 'a'..'f' - my num %hash{'a'..'f'}; # Same thing - - my %rainfall{ Months; 1..31 } # Keys: Jan..Dec ; 1..31 - -Unlike arrays, you can also specify a hash dimension via a non- -enumerated type, which then allows all values of that type as keys in -that dimension: - - my num %hash{<a b c d e f>; Str}; # 2nd dimension key may be any string - my num %hash{'a'..'f'; Str}; # Same thing - - my %rainfall{ Months; Int }; # Keys: Jan..Dec ; any integer - -To declare a hash that can take any object as a key rather than -just a string or integer, say something like: - - my %hash{Any}; - my %hash{*}; - -A hash of indeterminate dimensionality is: - - my %hash{**}; - -You can limit the keys to objects of particular types: - - my Fight %hash{Dog; Squirrel where {!.scared}}; - -The standard Hash: - - my %hash; - -is really short for: - - my Mu %hash{Str(Any)}; - -Note that any type used as a key must be intrinsically immutable, -or it has to be able to make a copy that functions as an immutable key, -or it has to have copy-on-write semantics. It is erroneous to change -a key object's value within the hash except by deleting it and reinserting -it. - -The order of hash keys is implementation dependent and arbitrary. -Unless C<%hash> is altered in any way, successive calls to C<.keys>, -C<.kv>, C<.pairs>, C<.values>, or C<.iterator> will iterate over the -elements in the same order. - -=head1 Autosorted hashes - -The default hash iterator is a property called C<.iterator> that can be -user replaced. When the hash itself needs an iterator for C<.pairs>, -C<.keys>, C<.values>, or C<.kv>, it calls C<%hash.iterator()> to -start one. In item context, C<.iterator> returns an iterator object. -In list context, it returns a lazy list fed by the iterator. It must -be possible for a hash to be in more than one iterator at a time, -as long as the iterator state is stored in a lazy list. - -The downside to making a hash autosort via the iterator is that you'd -have to store all the keys in sorted order, and resort it when the -hash changes. Alternately, the entire hash could be tied to an ISAM -implementation (not included (XXX or should it be?)). - -For multidimensional hashes, the key returned by any hash iterator is -a list of keys, the size of which is the number of declared dimensions -of the hash. [XXX but this seems to imply another lookup to find the -value. Perhaps the associated value can also be bundled in somehow.] - -=head1 Autovivification - -Autovivification will only happen if the vivifiable path is bound to -a read-write container. Value extraction (that is, binding to a readonly -or copy container) does not autovivify. - -Note that assignment is treated the same way as binding to a copy container, -so it does not autovivify its right side either. - -Any mention of an expression within a Capture (that is, an argument list) -delays the autovivification decision to binding time. (Binding to a -raw parameter defers the decision even further.) - -This is as opposed to Perl 5, where autovivification could happen -unintentionally, even when the code looks like a non-destructive test: - - # This is Perl 5 code - my %hash; - exists $hash{foo}{bar}; # creates $hash{foo} as an empty hash reference - -In Perl 6 these read-only operations are indeed non-destructive: - - my %hash; - %hash<foo><bar> :exists; # %hash is still empty - -But these bindings I<do> autovivify: - - my %hash; - my $val := %hash<foo><bar>; - - my @array; - my $capture = \@array[0][0]; # $capture is a Capture object - see S02 - my :($obj) := $capture; # @array[0][0] created here - - my @array; - foo(@array[0][0]); - sub foo ($obj is rw) {...} # same thing, basically - - my %hash; - %hash<foo><bar> = "foo"; # duh - -This rule applies to C<Array>, C<Hash>, and any other container type that -chooses to return an autovivifiable type object (see S12) rather than simply -returning C<Failure> when a lookup fails. Note in particular that, since -autovivification is defined in terms of type objects rather than failure, -it still works under "use fatal". - -This table solidifies the intuition that an operation pertaining to some data -structure causes the type object to autovivify to such an object: - - operation autovivifies to - ========= =============== - push, unshift, .[] Array - .{} Hash - -In addition to the above data structures autovivifying, C<++> and C<--> will -cause an C<Int> to appear, C<~=> will create a C<Str> etc; but these are -natural consequences of the operators working on C<Failure>, qualitatively -different from autovivifying containers. - -The type of the type object returned by a non-successful lookup should -be identical to the type that would be returned for a successful lookup. -The only difference is whether it's officially instantiated (defined) yet. -That is, you cannot distinguish them via C<.WHAT> or C<.HOW>, only via -C<.defined>. - -Binding of an autovivifiable type object to a non-writeable container -translates the type object into a similar type object without -its autovivifying closure and puts that new type object into the -container instead (with any pertinent historical diagnostic information -carried over). There is therefore no magical method you can call on -the readonly parameter that can magically autovivify the type object -after the binding. The newly bound variable merely appears to be a -simple uninitialized value. (The original type object retains its -closure in case it is rebound elsewhere to a read-write container.) - -Some implementation notes: Nested autovivifications work by making -nested type objects that depend on each other. In the general case -the containers must produce type objects any time they do not know -how the container will be bound. This includes when interpolated into -any capture that has delayed binding: - - \( 1, 2, %hash<foo><bar> ) # must defer - \%hash<foo><bar> # must defer - -In specific situations however, the compiler can know that a value -can only be bound readonly. For instance, C<< infix:<+> >> is -prototyped such that this can never autovivify: - - %hash<foo><bar> + 42 - -In such a case, the container object need not go through the agony -of calculating an autovivifying closure that will never be called. -On the other hand: - - %hash<foo><bar> += 42 - -binds the left side to a mutable container, so it autovivifies. - -Assignment doesn't look like binding, but consider that it's really -calling some kind of underlying set method on the container, which -must be mutable in order to change its contents. - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - -=for vim:set expandtab sw=4: diff --git a/S10-packages.pod b/S10-packages.pod deleted file mode 100644 index 587ef4dd..00000000 --- a/S10-packages.pod +++ /dev/null @@ -1,251 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 10: Packages - -=head1 VERSION - - Created: 27 Oct 2004 - - Last Modified: 9 Jul 2010 - Version: 13 - -=head1 Overview - -This synopsis summarizes Apocalypse 10, which discusses packages -despite never having been written. - -=head1 Packages - -As in Perl 5, packages are the basis of modules and classes. Unlike in -Perl 5, modules and classes are declared with distinct keywords, -but they're still just packages with extra behaviors. Likewise every -typename has an associated package namespace, even if unused. - -An ordinary package is declared with the C<package> keyword. Unlike in -earlier versions of Perl 5, in Perl 6 it can only be used with a block: - - package Bar {...} # block is in package Bar - -A named package declaration can occur as part of an expression, just like -named subroutine declarations. - -As a special exception, if a braceless C<package> declaration occurs -as the first executable statement in a file, then it's taken to mean that the rest of -the file is Perl 5 code. - - package Foo; # the entire file is Perl 5 - ... - -This form is illegal in a Perl 6 file. If you wish to have a file-scoped package, -either use the brace form or declare it with the C<module> keyword instead. - -Since there are no barewords in Perl 6, package names must be predeclared. -Alternatively, the sigil-like C<::PackageName> syntax may be used to indicate -that the type will be supplied some other way, however this syntax is not valid -in declarative scenarios, especially parameter lists where it has entirely -different semantics. The C<::> prefix does not imply globalness as it does in -Perl 5. (Use C<GLOBAL::> for that.) - -A bare C<package> declarator (without an explicit scope declarator -such as C<my>) declares an C<our> package within the current package -(or module, or class, or role, or...). Use C<GLOBAL::> to declare -a global package name. - -To declare a lexically scoped package, use C<my package>. - -To declare an anonymous package you can use either of - - package {...} - package :: {...} - -All files start out being parsed in the C<GLOBAL> -package, but may switch to some other package scope depending on the first -package-ish declaration. If that first declaration is not a package variant, then -the parsing switches to the "C<main>" package for Perl 5 code. Perl 6 code -stays C<GLOBAL> in that situation. The mainline code is thus in the -C<GLOBAL> namespace unless declared otherwise. - -Package traits are set using C<is>: - - package Foo is bar {...} - -All symbolic links are done with the C<::($expr)> syntax, which is -legal in any variable, package, module, or class name anywhere a -C<::Ident> is legal. The string returned by the expression will be -parsed for C<::> indicating subpackage names. Do not confuse this -with the - - Foo::{$key} - -syntax that lets you do a lookup in a particular symbol table. In this case, -the key is not parsed for C<::>. It's just a hash lookup. - -All package bodies (including module and class bodies) execute at the -normal execution time of the code in which they are embedded. For normal -mainline code, this is the normal flow of execution; if this is too late -to initialize something in the package that you want to be initialized, consider -use of a MAIN subroutine, which is invoked at the end of normal execution. -See L<S06/Declaring a C<MAIN> subroutine>. - -For packages (modules, classes, roles, etc.) defined in separate files -from the mainline code, there can be no mainline code by definition, -but the top-level code in the used module needs to be executed at -some point in case things need initialization. Invocation of this -pseudo-mainline code in the module notionally happens no later than at -the point of the C<use> or C<need> call in the process of compilation, -but the module's code is assumed to be sufficiently uninteresting that -it need be executed only once regardless of how many times the module -is used subsequently in the compilation. (In fact, it might not need -to run at all if the result of some previous compilation's run has -been cached.) - -If it is desired to have code that varies in meaning from run to run, -then you should put such code into an C<INIT> block. (Likewise, you -could put code into a C<CHECK> block that has inconsistent semantics -from compilation to compilation, but that's probably a bad idea.) - -In any case, it is erroneous for any external module to depend -on any knowledge of its user with respect to compilation order or -other dynamic information, since other users may also depend on -this single "first-use" execution and expect consistent semantics. -(Really, all such dynamic dependencies should be passed in at run -time to the routines or methods of your module as normal parameters or -as dynamic variables. For instance, you cannot know at module compile -time whether your caller is going to be using 'fatal' semantics or not. -That is dynamically scoped info.) - -If you wish to have a module that does something extra if invoked -standalone, define a MAIN subroutine, which will be ignored if -the module is merely used/needed elsewhere. - -=head1 Package nesting - -A declaration of any object of the form C<A::B::c> also creates (if needed) -an empty package C<A>, and an empty package C<B> inside of C<A>, in addition to creating -C<c> inside of C<B>. Such empty packages may subsequently be redeclared as any other -package-like object (module, class, etc.), and no redeclaration warning will be issued -for such a redeclaration. If a parent package already exists, no stub package -needs to be created, and no declaration of the form C<A::B::c> has anything -to say about the type of package C<A> or package C<A::B>, since any package variant -can function as a package for the purposes of naming things. - -Apart of package declaration constructs, package names are always searched -for from the innermost lexical scope to outermost. If not defined in any -surrounding lexical scope, the package is searched for from the current -package up through the containing packages to C<GLOBAL>. If it is not found, -a compiler error results. - -As with an initial C<::>, the presence of a C<::> within the name -does not imply globalness (unlike in Perl 5). True globals are always -in the C<GLOBAL::> namespace. - -The C<PROCESS::> namespace, shared by all interpreters within the process, -is notionally outside of C<GLOBAL::>, but package searches do not look -there for anything. (Contextual variable searches do; C<$*PID> will eventually -locate C<$PROCESS::PID> if not hidden by an inner callframe's C<$*PID>.) - -=head1 Autoloading - -A package (or any other similar namespace) can control autoloading. -However, Perl 5's C<AUTOLOAD> is being superseded by MMD autoloaders -that distinguish declaration from definition, but are not restricted -to declaring subs. A run-time declarator multisub is declared as: - - multi CANDO ( MyPackage, $type, $name, *%args) - -which stands in for the declaration of a container object within -another container object; it is called when anyone is searching for -a name in the package (or module, or class), and the name doesn't -already exist in the package. (In particular, C<.can> calls C<CANDO> -when trying to determine if a class supports a particular method.) -The arguments to C<CANDO> include type information on what kind -of object is expected in context, or this may be intuited from the -name requested. In any case, there may be multiple C<CANDO> routines -that are dispatched via MMD: - - multi CANDO ( MyPackage, Item, $name, *%args) - multi CANDO ( MyPackage, Array, $name, *%args) - multi CANDO ( MyPackage, Hash, $name, *%args) - multi CANDO ( MyPackage, Code, $name, *%args) - -The package itself is just passed as the first argument, since it's -the container object. Subsequent arguments identify the desired type -of the inner container and the "name" or "key" by which the object is -to be looked up in the outer container. Such a name does not include -its container name, unlike Perl 5's magical C<$AUTOLOAD> variable. -Nor does it include the type information of a Code object's "long -name"; this information comes in via the type parameter, and may be -matched against using ordinary subsignature matching: - - multi CANDO ( MyPackage, &:($), $name, *%args) # 1 arg - multi CANDO ( MyPackage, &:($,$), $name, *%args) # 2 args - -The slurpy C<%args> hash is likely to be empty in standard Perl 6 -usage, but it's possible that some dialects of Perl will desire -a mechanism to pass in additional contextual information, so this -parameter is reserved for such purposes. - -The C<CANDO> is expected to return an inner container object of -the proper sort (i.e. a variable, subroutine, or method object), -or a proxy object that can "autovivify" lazily, or C<Nil> if that -name is not to be considered declared in the namespace in question. -(Only bare C<Nil> is interpreted as "not there", since typed undefs -may function as autovivifiable proxy objects. See S12.) - -The declaration merely defines the interface to the new object. That object -need not be completely defined yet, though the C<CANDO> routine is certainly -I<allowed> to define it eagerly, and even install the inner object into the -outer container (the symbol table) if it wants to cache the declaration. - -At declaration time it might not yet be known whether the inner -container object will be used in lvalue or rvalue context; the use -of a proxy object can supply either readonly or rw semantics later. - -When the package in question is a class, it is also possible to declare -real methods or submethods: - - multi method CANDO ($self: Code, $name, *%args) - - multi submethod CANDO ($self: Item, $name, *%args) - -The method form is inherited by subclasses. Submethods are never -inherited but may still do MMD within the class. (Ordinary multisubs -are "inherited" only to the extent allowed by nested lexical scopes.) - -When the package in question is not a class, there is a slight problem -insofar as Perl 6 doesn't by default look into packages for functions -anymore, only lexical scopes. However, we'd still like the ability -to dynamic add functions to a package, so there are two ways to get -around the lexical limitation. - -First, presuming you have a C<CANDO> that adds to your current package, -you can simply call a newly-minted subroutine explicitly via the -current package: - - OUR::($somename)(); - -This bypasses the lexical namespaces entirely. Alternately, we can set -up a mechanism whereby, if you import or define a C<CANDO> into a given -lexical scope, all calls from within that scope register a failover that -adds the current package to the list of places to look for subroutines (or, -obviously, call the C<CANDO> as a last resort after that). There is no -performance impact on existing lexically scoped definitions, including those -from C<CORE>. This approach does require that failure to find a function name -cannot be reported at compile time, but must be delayed till run time instead. -Another potential disadvantage is that the package's symbols are also shadowed -by all symbols defined in your outer lexical scopes, including C<CORE>. -If this is a problem, use the direct C<OUR> call above. - -Another way to look at it is that a lexical C<CANDO> adds itself to -the end of the function dispatcher's search, but sets up the current -package as a kind of cache for newly-defined functions just ahead of itself -in the search path. - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - -=for vim:set expandtab sw=4: diff --git a/S11-modules.pod b/S11-modules.pod deleted file mode 100644 index 1a67e663..00000000 --- a/S11-modules.pod +++ /dev/null @@ -1,744 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 11: Compilation Units - -=head1 VERSION - - Created: 27 Oct 2004 - - Last Modified: 2 Apr 2015 - Version: 45 - -=head1 Overview - -This synopsis discusses those portions of Apocalypse 12 that ought to have -been in Apocalypse 11. - -=head1 Units - -Perl 6 code is compiled per compilation unit, or I<compunit> for short. These -are loaded with a C<use>, C<need> or C<require> statement (usually at compile -time). Or they are created as a string in a variable and compiled with an -C<EVAL> statement (usually at runtime). This synopsis is mostly about -compunits loaded at compile time. - -In the common vernacular of a Perl 5 developer, a I<module> is the same as the -file that contains the source code of a package. For Perl 6 developers, this -is generally not much different. However, such a I<module> is really a -compunit that may contain 0 or more package-like statements, some of which -may be I<module>. Confusing? Yes it is. On top of that, Perl 6 allows -different versions of the same compunit to be installed in a single -I<repository>. And it allows compunits from other languages to be loaded. - -In Perl, the C<use> statement is really just telling Perl to find a compunit -for the given name and load its contents. Whether that name is the name of a -C<package>, C<module>, C<class>, C<grammar> or C<role>, a combination of these -or something else entirely in a C<slang>, is B<not> known at the moment the -compunit is searched for (and hopefully found). Only when the contents of the -compunit are compiled, does Perl find out what's inside. - -In Perl 5, the compunit's name to filename translation is generally mechanical. -C<Foo::Bar> will always refer to C<Foo/Bar.pm> in a directory: it does not need -any outside information to find out the name of the file to be loaded. - -Perl 6 however, only knows about I<repositories> that contain compunits. Each -repository is represented as an object with the L<CompUnitRepo> interface in -the C<@?INC> array. Whenever a compunit needs to be loaded, each element in -the C<@?INC> is queried for the compunit, and any candidates are returned. -An exception occurs if there is no candidate, or more than one candidate that -matches the requirement. Otherwise, the contents of the compunit is then -obtained and loaded. - -There are 2 standard implementations of the C<CompUnitRepo> interface: -L<CompUnitRepo::Local::File> and L<CompUnitRepo::Local::Installation>. The -first is used whenever you're specifying the C<-I> parameter when running -Perl 6. The second is always used when searched for locally installed -compunits as files in directories. Of course, one is free to devise any -other way of storing and searching for compunits, as long as C<API> is the -same. - -See L<S22/"Distributions, Recommendations, Delivery and Installation"> for -more information about the C<CompUnitRepo> interface. - -=head1 Modules - -As in Perl 5, a C<module> is just a kind of package. Unlike in Perl 5, modules -and classes are declared with separate keywords, but they're still just -packages with extra behaviors. In the case of modules, the extra behavior is -the availability of the C<export> trait and any associated support for Perl 6 -standard export semantics. - -A module is declared with the C<module> keyword. There are two basic -declaration syntaxes: - - unit module Foo; # rest of scope is in module Foo - ... - - module Bar {...} # block is in module Bar - -A named module declaration can occur as part of an expression, just like -named subroutine declarations. - -Since there are no barewords in Perl 6, module names must be predeclared, -or use the sigil-like C<::ModuleName> syntax. The C<::> prefix does not -imply globalness as it does in Perl 5. (Use C<GLOBAL::> for that.) - -A bare (unscoped) C<module> declarator declares a nested C<our> module -name within the current package. However, at the start of a compunit, -the current package is C<GLOBAL>, so the first such declaration in the -file is automatically global. - -X<use> -You can use C<our module> to explicitly declare a module in the current -package. To declare a lexically scoped module, use C<my module>. -Module names are always searched for from innermost scopes to outermost. -As with an initial C<::>, the presence of a C<::> within the name -does not imply globalness (unlike in Perl 5). - -The default package for the main program is C<GLOBAL>. -(Putting C<module GLOBAL;> at the top of your program -is redundant, except insofar as it tells Perl that the code is Perl -6 code and not Perl 5 code. But it's better to say C<use v6> for that.) - -Module traits are set using C<is>: - - module Foo is bar {...} - -An anonymous module may be created with either of: - - module {...} - module :: {...} - -The second form is useful if you need to apply a trait: - - module :: is bar {...} - -=head1 Exportation - -Exportation is now done by trait declaration on the exportable item: - - unit module Foo; # Tagset... - sub foo is export {...} # :DEFAULT, :ALL - sub bar is export(:DEFAULT :others) {...} # :DEFAULT, :ALL, :others - sub baz is export(:MANDATORY) {...} # (always exported) - sub bop is export(:ALL) {...} # :ALL - sub qux is export(:others) {...} # :ALL, :others - -Methods also take the "is export" trait: the method will then be exported -as a I<multi sub> that takes the object as the first parameter: - - method close (IO::Handle:D) is export { ... } - -Constants (and enums) are also exportable items. As are variables declared -in C<our> scoping: - - our @foo is export = <foo bar> - our %bar is export = <foo bar> - our $baz is export = "foobar" - constant $FOO is export = "foobar" - enum FooBar is export (:baz(1)) - -Every compunit has a C<UNIT> package, which gets a lexically scoped C<EXPORT> -package automatically. Declarations marked as C<is export> are bound into -it, with their tagsets as inner packages. For example, the C<sub bar> above -will bind as C<< UNIT::EXPORT::DEFAULT::<&bar> >>, -C<< UNIT::EXPORT::ALL::<&bar> >>, and C<< UNIT::EXPORT::others::<&bar> >>. - -Tagset names consisting entirely of capitals are reserved for Perl. - -Exports contained within a module will also be bound into an our-scoped -C<EXPORT> package nested in the module, again with the tagsets forming -inner packages. This is so the C<import> keyword can be used with a package -to import from it; the lexical C<IMPORT> package in C<UNIT>, on the other -hand, is the only thing that is considered by C<use> for importing. - -Inner packages automatically add their export list to packages in all their -outer scopes (including UNIT): - - module Foo { - sub foo is export {...} - module Bar { - sub bar is export {...} - module Baz { - sub baz is export {...} - } - } - } - -This compunit will export C<&foo>, C<&bar> and C<&baz> by default. - -=head1 Dynamic exportation - -The default C<EXPORTALL> handles symbol exports by removing recognized -export items and tagsets from the argument list, then calls the C<EXPORT> -subroutine in that package (if there is one), passing in the remaining -arguments. - -If the exporting module is actually a class, C<EXPORTALL> will invoke its -C<EXPORT> method with the class itself as the invocant. - -=head1 Compile-time Importation -X<use> - -[Note: the :MY forms are being rethought currently.] - -Importing via C<use> binds into the current lexical scope by default -(rather than the current package, as in Perl 5). - - use Sense <&common @horse>; - -You can be explicit about the desired package: - - use Sense :MY<&common> :OUR<@horse>; - -That's pretty much equivalent to: - - use Sense; - my &common ::= Sense::<&common>; - our @horse ::= Sense::<@horse>; - -(if C<&common> and C<@horse> are C<our>-scoped in package C<Sense>). - -It is also possible to re-export the imported symbols: - - use Sense :EXPORT; # import and re-export the defaults - use Sense <&common> :EXPORT; # import "&common" and re-export it - use Sense <&common> :EXPORT<@horse>; # import "&common" but export "@horse" - -In the absence of a specific scoping specified by the caller, one -may also specify a different scoping default by use of C<:MY> or C<:OUR> -tags as arguments to C<is export>. (Of course, mixing incompatible scoping -in different scopes is likely to lead to confusion.) - -The C<use> declaration is actually a composite of two other declarations, -C<need> and C<import>. Saying - - use Sense <&common @horse>; - -breaks down into: - - need Sense; - import Sense <&common @horse>; - -These further break down into: - - BEGIN { - my $target ::= OUTER; - for <Sense> { - my $scope = load_compunit(find_compunit_defining($_)); - # install the name of the type - $target.install_alias($_, $scope{$_}) if $scope{$_}:exists; - # get the package declared by the name in that scope, - my $package = $_ ~ '::'; - # if there isn't any, then there's just the type... - my $loaded_compunit = $scope{$package} or next; - # get a copy of the package, to avoid action-at-a-distance - # install it in the target scope - $target{$package} := $loaded_compunit.copy; - # finally give the chance for the module to install - # the selected symbols - $loaded_compunit.EXPORTALL($target, <&common @horse>); - } - } - -=head2 Loading without importing -X<need> - -The C<need> declarator takes a list of modules and loads them (at -compile time) without importing any symbols. It's good for loading -class modules that have nothing to export (or nothing that you want -to import): - - need ACME::Rocket; - my $r = ACME::Rocket.new; - -This declaration is equivalent to Perl 5's: - - use ACME::Rocket (); - -Saying - - need A,B,C; - -is equivalent to: - - BEGIN { - my $target ::= OUTER; - for <A B C> { - my $scope = load_compunit(find_compunit_defining($_)); - # install the name of the type - $target.install_alias($_, $scope{$_}) if $scope{$_}:exists; - # get the package declared by the name in that scope, - my $package = $_ ~ '::'; - # if there isn't any, then there's just the type... - my $loaded_compunit = $scope{$package} or next; - # get a copy of the package, to avoid action-at-a-distance - # install it in the target scope - $target{$package} := $loaded_compunit.copy; - } - } - -=head2 Importing without loading -X<import> - -The importation into your lexical scope may also be a separate declaration -from loading. This is primarily useful for modules declared inline, which -do not automatically get imported into their surrounding scope: - - my module Factorial { - sub fact (Int $n) is export { [*] 1..$n } - } - ... - import Factorial 'fact'; # imports the multi - -The last declaration is syntactic sugar for: - - BEGIN Factorial.WHO.EXPORTALL(MY, 'fact'); - -This form functions as a compile-time declarator, so that these -notations can be combined by putting a declarator in parentheses: - - import (role Silly { - enum Ness is export <Dilly String Putty>; - }) <Ness>; - -This really means: - - BEGIN (role Silly { - enum Ness is export <Dilly String Putty>; - }).WHO.EXPORTALL(MY, <Ness>) - - -Without an import list, C<import> imports the C<:DEFAULT> imports. - -=head1 Runtime Importation - -Importing via C<require> also installs names into the current lexical scope by -default, but delays the actual binding till runtime: - - require Sense <common @horse>; - -This means something like: - - BEGIN MY.declare_stub_symbols('Sense', <common @horse>); - # run time! - MY.import_realias(:from(load_compunit(find_compunit_defining('Sense'))), 'Sense'); - MY.import_realias(:from(Sense), <common @horse>); - -(The C<.import_realias> requires that the symbols to be imported already -exist; this differs from C<.import_alias>, which requires that the -imported symbols do I<not> already exist in the target scope.) - -Additionally, the C<require> expression evaluates to the value which is -installed as the alias, so that C<(require Foo::Bar).new> and similar -expressions do the most useful thing. - -Alternately, a filename may be mentioned directly, which installs a -package that is effectively anonymous to the current lexical scope, -and may only be accessed by whatever global names the module installs: - - require "/home/non/Sense.pm" <common @horse>; - -which breaks down to: - - BEGIN MY.declare_stub_symbols(<common @horse>); - MY.import_realias(:from(load_compunit("/home/non/Sense.pm")), <common @horse>); - -Only explicitly mentioned names may be so imported. In order -to protect the run-time sanctity of the lexical pad, it may not be -modified by C<require>. Tagsets are assumed to be unknown at compile -time, hence tagsets are not allowed in the default import list to -C<:MY>, but you can explicitly request to put names into the C<:OUR> -scope, since that is modifiable at run time: - - require Sense <:ALL> # does not work - require Sense :MY<ALL> # this doesn't work either - require Sense :OUR<ALL> # but this works - -If the import list is omitted, then nothing is imported. Since you -may not modify the lexical pad, calling an importation routine at -runtime cannot import into the lexical scope, and defaults to importation -to the package scope instead: - - require Sense; - Sense.EXPORTALL; # goes to the OUR scope by default, not MY - -(Such a routine I<may> rebind existing lexicals, however.) - -When you pass a string, C<require> always assumes the string contains a filename. -To specify both a module name and a filename, use a colonpair modifier: - - require Sense:file("/home/non/Sense.pm") <common @horse>; - -At minimum, this will create the C<Sense> package at compile time, -even if the C<require> never puts anything into it at run time. -(Sound practice would keep it consistent with whatever the C<require> -is going to do later, however.) By default the package is created -as an C<our> package unless it has already been declared C<my> earlier. - -It is also possible to specify the compunit name indirectly by string: - - my $sense = "Sense"; - require ::($sense) <common @horse>; - -The parser will have no idea what your module is actually going -to be called, so it installs no package name known at compile time. -Other than that, the semantics are identical to the direct form. - -=head1 Versioning - -Whenever an authority (such as a CPAN author or a company) posts a -compilation unit as part of a distribution of Perl 6 code, or enters it into -any Perl 6 library, the module is required to declare its full -name so that installations can know its unique, immutable identity, -such that multiple versions by different authors can coexist, all of -them available to any installed version of Perl. (For the purposes of -"standard Perl 6 library" we do not just mean publicly shared libraries -such as CPAN, but also any internal or site-wide libraries that are -shared outside the given module's dev group.) - -Such modules are also required to specify exactly which version (or -versions) of Perl they are expecting to run under, so that future -versions of Perl can emulate older versions of Perl (or give a cogent -explanation of why they cannot). This will allow the language to -evolve without breaking existing widely used modules. (Perl 5 library -policy is notably lacking here; it would induce massive breakage even -to change Perl 5 to make strictness the default.) If an installed module -breaks because it declares that it supports future versions of Perl -when it doesn't, then it must be construed to be the module's fault, -not Perl's. If Perl evolves in a way that does not support emulation -of an older version (at least, back to 6.0.0), then it's Perl's fault -(unless the change is required for security, in which case it's the -fault of the insensitive clod who broke security :). - -The internal API for package names is always case-sensitive, even if -the library system is hosted on a system that is not case-sensitive. -Likewise internal names are Unicode-aware, even if the filesystem isn't. -This implies either some sort of name mangling capability or storage -of intermediate products into a database of some sort for the -L<CompUnitRepo::Local::Installation> class and similar classes. In any event, -the actual storage location must be encapsulated in the library system -such that it is hidden from all language level naming constructs. -(Provision must be made for interrogating the library system for -the actual location of a module, of course, but this falls into -the category of introspection.) Note also that distributions -need to be distributed in a way that they can be installed on -case-insensitive systems without loss of information. That's fine, -but the language-level abstraction must not leak details of this -mechanism without the user asking for the details to be leaked. - -As discussed in C<Units>, the required parts for library insertion are the -(long) name of the compilation unit, a URI identifying the author/authority -(called auth to be intentionally ambiguous), its version number (ver for -short) and an optional API indicator. For example, if a compunit contains -this configuration in its L<META6.json>: - - "name" : "Dog", - "version" : "1.2.1" - "api" : "woof" - -and has been installed from an author identified by C<cpan:JRANDOM>, then -when you then attempt to load a compilation unit, like: - - use Dog; - -you're really wildcarding the unspecified bits: - - use Dog:auth(Any):ver(Any):api(Any); - -And when you say: - - use Dog:<1.2.1>; - -you're really asking for: - - use Dog:auth(Any):ver<1.2.1>:api(Any); - -Saying C<1.2.1> specifies an I<exact> match on that part of the -version number, not a minimum match. To match more than one version, -put a range operator as a selector in parens: - - use Dog:ver(v1.2.1..v1.2.3); - use Dog:ver(v1.2.1..^v1.3); - use Dog:ver(v1.2.1..*); - -When specifying the version of your own module, C<1.2> is equivalent -to C<1.2.0>, C<1.2.0.0>, and so on. However C<use> searches for -modules matching a version prefix, so the subversions are wildcarded, -and in this context C<< :ver<1.2> >> really means C<< :ver<1.2.*> >>. -If you say: - - use v6; - -which is short for: - - use Perl:ver<6.*>; - -you're asking for any version of Perl 6. You need to say something like - - use Perl:<6.0>; - use Perl:<6.0.0>; - use Perl:<6.2.7.1>; - -if you want to lock in a particular set of semantics at some greater -degree of specificity. And if some large company ever forks Perl, you can say -something like: - - use Perl:auth<cpan:TPF> - -to guarantee that you get the unembraced Perl. C<:-)> - -When it happens that the same module is available from more than one -auth, and the desired auth is not specified by the C<use>, -the version lineage that was created first wins, unless overridden by -local policy or by official abandonment by the original auth (as -determined either by the author or by community consensus in case the -author is no longer available or widely regarded as uncooperative). -An abandoned lineage will be selected only if it is the -only available lineage of locally installed modules. - -Once the auth is selected, then and only then is any version -selection done. This implies that all installed compunits record -permanently when they were first installed in the library, -and this creation date is considered immutable. This date can be specified -with the uppercase block typename CREATED. For example: - - =CREATED 20130626 - it was a good day - -As with the other credentials of the compunit, only the first \S+ are used -and expected to be in the form YYYYMMDD. - -When loading a compilation unit with wildcards, any valid smartmatch selector -works: - - use Dog:auth(/:i jrandom/):ver(v1.2.1 | v1.3.4); - use Dog:auth({ .substr(0,5) eq 'cpan:'}):ver(Any); - -In any event, however you select the compunit, its full name is automatically -aliased to the short name for the rest of your lexical scope. So you can just -say - - my Dog $spot .= new("woof"); - -and it knows (even if you don't) that you meant the one by I<cpan:JRANDOM> and -version I<1.3.4>. - -If you need to have two different versions of the same compunit loaded at the -same time, you can specify the name of the compunit separately with the -I<:name> adverb: - - use OldDog:name<Dog>:auth<cpan:JRANDOM>:ver<1.2.1>; - use OldDog:<Dog cpan:JRANDOM 1.2.1>; # same thing - -This would alias Dog of I<cpan:JRANDOM>, version I<1.2.1> to OldDog in the -current lexical scope. - -The C<use> statement also allows an external language to be specified in -addition to (or instead of) an authority, so that you can use modules -from other languages. The C<from> adverb also parses any additional -parts as short-form arguments. For instance: - - use Whiteness:from<perl5>:name<Acme::Bleach>:auth<cpan:DCONWAY>:ver<1.12>; - use Whiteness:from<perl5 Acme::Bleach cpan:DCONWAY 1.12>; # same thing - -The string form of a version recognizes the C<*> wildcard in place of any -position. It also recognizes a trailing C<+>, so - - :ver<6.2.3+> - -is short for - - :ver(v6.2.3 .. v6.2.*) - -And saying - - :ver<6.2.0+> - -specifically rules out any prereleases. - -If two different compunits in your program require two different -versions of the same compunit, Perl will simply load both versions at -the same time. For compunits that do not manage exclusive resources, -the only penalty for this is memory, and the disk space in the library -to hold both the old and new versions. For compunits that do manage -an exclusive resource, such as a database handle, there are two approaches -short of requiring the user to upgrade. The first is simply to refactor -the compunit into a stable supplier of the exclusive resource that doesn't -change version often, and then the outer wrappers of that resource can -both be loaded and use the same supplier of the resource. - -The other approach is for the compunit to keep the management of its exclusive -resource, but offer to emulate older versions of the API. Then if there -is a conflict over which version to use, the new one is used by both users, -but each gets a view that is consistent with the version it thinks it is -using. Of course, this depends crucially on how well the new version -actually emulates the old version. - -=head2 Tie-breaking - -When specifing an insufficiently strict -use- statement, it will be possible -that more than one compunit will match the given specification. In that case -the following rules apply: - -=over 4 - -=item die if the selected compunits have a different :api value - -A different :api value indicates a difference in API, which means that -probably at least one of the compunits is incompatible with the code wanting -to use it. - -=item select the highest version (within the same api) - -All compunits with the same API can be considered compatible. It's most -likely that the newest version will be the best to be used. So if you didn't -care about the version, the newest will be used. - -=back - -=head1 Forcing Perl 6 - -To get Perl 6 parsing rather than the default Perl 5 parsing, -we said you could force Perl 6 mode in your main program with: - - use v6; - -Actually, if you're running a parser that is aware of Perl 6, you -can just start your main program with any of: - - use v6; - unit module; - unit class; - -Those all specify the latest Perl 6 semantics, and are equivalent to - - use Perl:auth(Any):ver(v6..*); - -To lock the semantics to 6.0.0, say one of: - - use Perl:ver<6.0.0>; - use :<6.0.0>; - use v6.0.0; - -In any of those cases, strictures and warnings are the default -in your main program. To start it in I<lax> mode, start it with - - no strict; - -(Invoking perl with C<-e> has the same effect.) - -In the other direction, to inline Perl 5 code inside a Perl 6 program, put -C<use v5> at the beginning of a lexical block. Such blocks can nest arbitrarily -deeply to switch between Perl versions: - - use v6; - # ...some Perl 6 code... - { - use v5; - # ...some Perl 5 code... - { - use v6; - # ...more Perl 6 code... - } - } - -It's not necessary to force Perl 6 if the interpreter or command -specified already implies it, such as use of a "C<#!/usr/bin/perl6>" -shebang line. Nor is it necessary to force Perl 6 in any file that -begins with the C<unit>, C<class>, C<module>, C<grammar> or C<role> keywords. - -=head1 Tool use vs language changes - -In order that language processing tools know exactly what language -they are parsing, it is necessary for the tool to know exactly which -variant of Perl 6 is being parsed in any given scope. All Perl 6 -compilation units that are complete files start out at the top of the -file in the Standard Dialect (which itself has versions that correspond -to the same version of the official Perl test suite). C<EVAL> strings, -on the other hand, start out in the language variant in use at the -point of the C<EVAL> call, so that you don't suddenly lose your macro -definitions inside C<EVAL>. - -All language tweaks from the start of the compilation unit must -be tracked. Tweaks can be specified either directly in your code as -macros and such, or such definitions may be imported from a package. -As the compiler progresses through the compilation unit, other grammars -may be substituted in an inner lexical scope for an outer grammar, -and parsing continues under the new grammar (which may or may not be -a derivative of the standard Perl grammar). - -Language tweaks are considered part of the interface of any package -you import. Version numbers are assumed to represent a combination of -interface and patch level. We will use the term I<interface version> -to represent that part of the version number that represents the -interface. For typical version number schemes, this is the first two -numbers (where the third number usually represents patch level within -a constant interface). Other schemes are possible though. (It is -recommended that branches be reflected by differences in authority -rather than differences in version, whenever that makes sense. To make -it make sense more often, some hierarchical authority-naming scheme -may be devised so that authorities can have temporary subauthorities -to hold branches without relinquishing overall naming authority.) - -So anyway, the basic rule is this: you may import language tweaks from -your own private (user-library as specified in @?INC) code as you like; -however, all imports of language tweaks from the installed Perl 6 -library must specify the exact interface version of the package. - -Such installed interface versions must be considered -immutable on the language level, so that once any language-tweaking -compunit is in circulation, it may be presumed to represent a fixed -language change. By examination of these interface versions a language -processing tool can know whether it has sufficient information to -know the current language. - -In the absence of that information, the tool can choose either -to download and use the compunit directly, or the tool can proceed -in ignorance. As an intermediate position, if the tool does not -actually care about running the code, the tool need not actually have -the complete compunit in question; many language tweaks could be stored -in a database of interface versions, so if the tool merely knows the -nature of the language tweak on the basis of the interface version it -may well be able to proceed with perfect knowledge. A compunit that -uses a well-behaved macro or two could be fairly easily emulated -based on the version info alone. - -But more realistically, in the absence of such a hypothetical database, -most systems already come with a kind of database for distributions that -have already been installed. So perhaps the most common case is -that you have downloaded an older version of the same distribution, in -which case the tool can know from the interface version whether that -older distribution represents the language tweak sufficiently well that -your tool can use the interface definition from that distribution without -bothering to download the latest patch. - -Note that most compilation units do no language tweaking, and in any case -cannot perform language tweaks unless these are explicitly exported. - -Compilation units that export C<multi>s are technically language tweaks on the -semantic level, but as long as those new definitions modify semantics -within the existing grammar (by avoiding the definition of new macros -or operators), they do not fall into the language tweak category. -Compilation units that export new operators or macros are always considered -language tweaks. (Unexported macros or operators intended only for -internal use of the module itself do not count as language tweaks.) - -The requirement for immutable interfaces extends transitively to -any packages imported by a language tweak module. There can be no -indeterminacy in the language definition either directly or indirectly. - -It must be possible for any compilation unit to be separately compiled -without knowledge of the lexical or dynamic context in which it will be -embedded, and this separate compilation must be able to produce a deterministic -profile of the interface. It must be possible to extract out the -language tweaking part of this profile for use in tools that wish to -know how to parse the current language variant deterministically. - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S12-objects.pod b/S12-objects.pod deleted file mode 100644 index dee1a769..00000000 --- a/S12-objects.pod +++ /dev/null @@ -1,2745 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 12: Objects - -=head1 VERSION - - Created: 27 Oct 2004 - - Last Modified: 26 Oct 2014 - Version: 134 - -=head1 Overview - -This synopsis summarizes Apocalypse 12, which discusses object-oriented -programming. - -=head1 Classes - -A class is a module declared with the C<class> keyword. As with -modules, the public storage, interface, and name of the class is -represented by a package and its name, which is usually (but not -necessarily) a global name. A class is a module and thus can export -stuff, but a class adds even more behavior to support Perl 6's -standard class-based OO. - -Taken as a type object, a class name represents all of the possible values of -its type, and the type object can thus be used as a proxy for any -"real" object of that type in calculating what a generic object of -that type can do. The class object is an object, but it is not a -Class, because there is no mandatory Class class in Perl 6, and because type -objects in Perl 6 are considered undefined. We wish -to support both class-based and prototype-based OO programming. -So all metaprogramming is done through the current object's C<HOW> -object, which can delegate metaprogramming to any metamodel it likes. -However, by default, objects derived from C<Mu> support a fairly -standard class-based model. - -There are two basic class declaration syntaxes: - - unit class Foo; # rest of file is class definition - has $.foo; - - class Bar { has $.bar } # block is class definition - -The first form is allowed only as the first declaration in a compilation -unit (that is, file or C<EVAL> string). - -If the class body begins with a statement whose main operator is a -single C<< prefix:<...> >> (yada) listop, the class name is introduced -without a definition, and a second declaration of that class in the -same scope does not complain about redefinition. (Statement modifiers -are allowed on such a C<...> operator.) Thus you may -forward-declare your classes: - - class A {...} # introduce A as a class name without definition - class B {...} # introduce B as a class name without definition - - my A $root .= new(:a(B)); - - class A { - has B $.a; - } - - class B { - has A $.b; - } - -As this example demonstrates, this allows for mutually recursive class -definitions (though, of course, it can't allow recursive inheritance). - -It is also possible to extend classes via the C<augment> declarator, -but that is considered somewhat antisocial and should not be used -for forward declarations. - -[Conjecture: we may also allow the C<proto> and C<multi> declarator modifiers -on class definitions to explicitly declare classes with multiple bodies -participating in a single definition intentionally.] - -A named class declaration can occur as part of an expression, just like -named subroutine declarations. - -Classes are primarily for instance management, not code reuse. -Consider using roles when you simply want to factor out -common code. - -Perl 6 supports multiple inheritance, anonymous classes, and autoboxing. - -All public method calls are "virtual" in the C++ sense. - -You may derive from any built-in type, but the derivation of a low-level -type like C<int> may only add behaviors, not change the representation. -Use composition and/or delegation to change the representation. - -Since there are no barewords in Perl 6, bare class names must be -predeclared. You can predeclare a stub class and fill it in later -just as you would a subroutine. - -You can force interpretation of a name as a class or type name using -the C<::> prefix. In an rvalue context the C<::> prefix is a no-op, -but in a declarational context, it binds a new type name within the -declaration's scope along with anything else being declared by the declaration. - -Without a C<my> or other scoping declarator, a bare C<class> -declarator declares an C<our> declarator, that is, a name within -the current package. Since class files begin parsing in the -C<GLOBAL> package, the first class declaration in the file installs -itself as a global name, and subsequent declarations then install -themselves into the current class rather than the global package. - -Hence, to declare an inner class in the current package (or module, or -class), use C<our class> or just C<class>. To declare a lexically -scoped class, use C<my class>. Class names are always searched -for from innermost scopes to outermost. As with an initial C<::>, -the presence of a C<::> within the name does not imply globalness -(unlike in Perl 5). So the outward search can look in children -of the searched namespaces. - -An inner class or role in a generic context must be lexically scoped -if it depends on any generic parameter or type; and such an inner -class or role is also a generic type. [Conjecture: it is erroneous -to assume that any generic type is uniquely associated with a package.] - -=head2 Class traits - -Class traits are set using C<is>: - - class MyStruct is rw {...} - -=head3 Single inheritance - -An "isa" is just a trait that happens to be another class: - - class Dog is Mammal {...} - -=head3 Multiple inheritance - -Multiple inheritance is specified with multiple C<is> modifiers: - - class Dog is Mammal is Pet {...} - -=head3 Composition - -Roles use C<does> instead of C<is>: - - class Dog is Mammal does Pet {...} - -=head3 The C<also> declarator - -You may put these inside as well by use of the C<also> declarator: - - class Dog { - also is Mammal; - also does Pet; - ... - } - -(However, the C<also> declarator is primarily intended for use -in roles, to distinguish class traits that might not be properly -understood as generic when placed in the role header, which tends to -communicate the false impression that the trait in question is to be -applied directly to the role rather than to the composed class.) - -=head2 Metaclasses - -Every object (including any class-based object) delegates to an instance -of its metaclass. You can get at the metaclass of any object via the -C<HOW> method, which returns an instance of the metaclass. A "class" -object is just considered an "empty" instance in Perl 6, more properly -called a "prototype" or "generic" object, or just "type object". -Perl 6 doesn't really have any classes named C<Class>. Types of all -kinds are instead named via these undefined type objects, which are -considered to have exactly the same type as an instantiated version of -themselves. But such type objects are inert, and do not manage the -state of class instances. - -The actual object that manages instances is the metaclass object pointed -to by the C<HOW> syntax. So when you say "C<Dog>", you're referring to -both a package and a type object, the latter of which points to the -object representing the class via C<HOW>. The type object -differs from an instance object not by having a different -type but rather in the extent to which it is defined. Some objects -may tell you that they are defined, while others may tell you that -they are undefined. That's up to the object, and depends on how the -metaclass chooses to dispatch the C<.defined> method. - -=head2 Closed classes - -Classes are open and non-final by default, but may easily be closed -or finalized not by themselves but by the entire application, provided -nobody issued an explicit compile-time request that the class stay open -or non-final. (Or a site policy could close any applications that use -the policy.) Platforms that do dynamic loading of sub-applications -probably don't want to close or finalize classes wholesale, however. - -Roles take on some of the compile-time function of closed classes, -so you should probably use those instead anyway. - -=head2 Private classes - -A private class can be declared using C<my>; most privacy issues are -handled with lexical scoping in Perl 6. The fact that importation -is lexical by default also means that any names your class imports -are also private by default. - -In grammars, one cannot use grammar attributes so one can call -a grammar rule from an unrelated grammar. -One can emulate that behavior with lexically scoped grammars created -within a closure. The lexical variables captured by the closure can then -be used where grammar attributes would be. - -=head2 Class composition - -Class declarations (in particular, role composition) are strictly -compile time statements. In particular, if a class declaration appears -inside a nested scope, the class declaration is constrained to compose -in exactly the same way on any possible execution. All named roles and -superclasses must be bound as non-rebindable readonly values; any -parameters to traits will be evaluated only in a non-cloning context. -Names bound by the class declaration are made non-rebindable and read -only so they may be used as superclasses. - -=head2 Anonymous class declaration - -In an anonymous class declaration, C<::> by itself may represent the -anonymous class name if desired: - - class {...} # ok - class is Mammal {...} # WRONG - class :: is Mammal {...} # ok - class { also is Mammal; ...} # also ok - -=head1 Methods - -Methods are routines declared in a class with the C<method> keyword: - - method doit ($a, $b, $c) { ... } - method doit ($self: $a, $b, $c) { ... } - method doit (MyName $self: $a, $b, $c) { ... } - method doit (::?CLASS $self: $a, $b, $c) { ... } - -=head2 Invocants - -Declaration of the invocant is optional. You may always access the -current invocant using the keyword C<self>. You need not declare the -invocant's type, since the lexical class of the invocant is known in any -event because methods must be declared in the class of the invocant, -though of course the actual (virtual) type may be a derived type of -the lexical type. You could declare a more restrictive type, but -that would probably be a bad thing for proper polymorphism. You may -explicitly type the invocant with the lexical type, but any check for -that will be optimized away. (The current lexically-determined class -may always be named as C<::?CLASS> even in anonymous classes or roles.) - -To mark an explicit invocant, just put a colon after it: - - method doit ($x: $a, $b, $c) { ... } - -If you declare an explicit invocant for an Array type using an array variable, -you may use that directly in list context to produce its elements - - method push3 (@x: $a, $b, $c) { ... any(@x) ... } - -Note that the C<self> term refers directly to the object the method was invoked -on, and therefore: - - class A is Array { - method m() { .say for self } - } - A.new(1, 2, 3).m; - -Will produce 3 lines of output. - -=head2 Private methods - -Private methods are declared using C<!>: - - method !think (Brain $self: $thought) - -(Such methods are completely invisible to ordinary method calls, and are -in fact called with a different syntax that uses C<!> in place of the C<.> -character. See below.) - -=head2 Method scoping - -Unlike with most other declarations, C<method> declarations do not -default to C<our> semantics, or even C<my> semantics, but rather -C<has> semantics. So instead of installing a symbol into a lexical -or package symbol table, they merely install a public or private -method in the current class or role via calls to its metaobject. -(Likewise for C<submethod> declarations--see L</Submethods> below.) - -Use of an explicit C<has> declarator has no effect on the declaration. -You may install additional aliases to the method in the lexical scope -using C<my> or in the current package using C<our>. These aliases -are named with C<&foo> notation and return a C<Routine> object that -may be called as a subroutine, in which case you must supply the -expected invocant as the first argument. - -=head2 Method calls - -To call an ordinary method with ordinary method-dispatch semantics, -use either the dot notation or indirect object notation: - - $obj.doit(1,2,3) - doit $obj: 1,2,3 - -Indirect object notation now requires a colon after the invocant, -even if there are no arguments after the colon: - - $handle.close; - close $handle:; - -To reject method call and only consider subs, simply omit the colon -from the invocation line: - - close($handle); - close $handle; - -However, here the built-in B<IO> class defines C<method close () is export>, -which puts a C<multi sub close (IO)> in scope by default. Thus if the -C<$handle> evaluates to an C<IO> object, then the two subroutine calls above -are still translated into method calls. - -Dot notation can omit the invocant if it's in C<$_>: - - .doit(1,2,3) - -Method calls use the C3 method resolution order. - -=head3 Fancy method calls - -Note that there is no corresponding notation for private methods. - - !doit(1,2,3) # WRONG, would be parsed as not(doit(1,2,3)) - self!doit(1,2,3) # okay - -There are several forms of indirection for the method name. You can -replace the identifier with a quoted string, and it will be evaluated -as a quote and then the result of that is used as the method name. - - $obj."$methodname"(1,2,3) # use contents of $methodname as method name - $obj.'$methodname'(1,2,3) # no interpolation; call method with $ in name! - - $obj!"$methodname"() # indirect call to private method name - -As an aid to catching Perl 5 brainos, this quoted form always requires -a parenthesized argument list to distinguish it from code that looks -like a Perl 5 concatenation. - -Within an interpolation, the double-quoted form may not contain -whitespace. This does what the user expects in the common case of -a quoted string ending with a period: - - say "Foo = $foo."; - -If you really want to call a method with whitespace, you may work -around this restriction with a closure interpolation: - - say "Foo = {$foo."a method"()}"; # OK - -[Note: to help catch the mistaken use of C<< infix:<.> >> as a string -concatenation operator, Perl 6 will warn you about "useless use of -quotes" at compile time if the string inside quotes is an identifier. -(It does not warn about non-identifier strings, but such strings are -likely to produce missing method errors at run time in any case.) -Also, if there is whitespace around an intended C<.> concatenation, -it cannot be parsed as a method call at all; instead it fails at -compile time because standard Perl 6 has a pseudo C<< infix:<.> >> operator -that always fails at compile time.] - -For situations where you already have a method located, you -can use a simple scalar variable in place of method name: - - $methodobj = $foo ?? &bar !! &baz; - $obj.$methodobj(1,2,3) - -or more succinctly but less readably: - - $obj.$($foo ?? &bar !! &baz)(1,2,3) - -The variable must contain a C<Callable> object (usually of type C<Code>), -that is, a closure of some sort. Regardless of whether the closure was -defined as a method or a sub or a block, the closure is called directly -without any class dispatch; from the closure's point of view, however, -it is always called as a method, with the object as its first argument, -and the rest of the arguments second, third, and so on. For instance, such -a closure may be used to abstract a "navigational" path through a -data structure without specifying the root of the path till later: - - $locator = -> $root, $x, $y { $root.<foo>[$x]<bar>{$y}[3] } - $obj.$locator(42,"baz") # $obj<foo>[42]<bar><baz>[3] - - $locator = { .<here> } - $obj.$locator # $obj<here> - -As a convenient form of documentation, such a closure may also be written -in the form of an anonymous method: - - $locator = method ($root: $x, $y) { $root.<foo>[$x]<bar>{$y}[3] } - $obj.$locator(42,"baz") # $obj<foo>[42]<bar><baz>[3] - - $locator = method { self.<here> } - $obj.$locator # $obj<here> - -Note however that, like any anonymous closure, an anonymous method -can only be dispatched to directly, like a sub. You may, of course, -bind an anonymous method to the name of a method in a class's public -interface, in which case it is no longer anonymous, and may be -dispatched to normally via the class. (And in fact, when the normal -method dispatcher is calling individual candidates in its candidate -list, it calls each candidate as a sub, not as a method, or you'd -end up with recursive dispatchers.) But fundamentally, there's -no such thing as a method closure. The C<method> declarator on an -anonymous method has the primary effect of making the declaration -of the invocant optional. (It also makes it an official C<Routine> -that can be returned from, just as if you'd used C<sub> to declare it.) - -Instead of a scalar variable, an array variable may also be used: - - $obj.@candidates(1,2,3) - -As with the scalar variant, string method names are not allowed, only -C<Callable> objects, The list is treated as a list of candidates to -call. After the first successful call the rest of the candidates are -discarded. Failure of the current candidate is indicated by calling -C<nextwith> or C<nextsame> (see L</Calling sets of methods> below). - -Note also that the - - $obj.$candidates(1,2,3) - -form may dispatch to a list of candidates if C<$candidates> is either -a list or a special C<Code> object representing a partial dispatch to a -list of candidates. If C<$candidates> (or any element of C<@candidates>) -is an iterable object it is expanded out recursively until C<Callable> -candidates are found. The call fails if it hits a candidate that is -not C<Callable>, C<Iterable>, or C<List>. - -Another form of indirection relies on the fact that operators are named -using a variant on pair notation, which gives you these forms: - - $x.infix:[$op]($y) - $x.prefix:[$op] - $x.postfix:[$op] - -Generally you see these with the literal angle bracket form of subscript: - - $a.infix:<*>($b) # equivalent to $a * $b - $a.prefix:<++> # equivalent to ++$a - $a.postfix:<++> # equivalent to $a++ - -If you omit the syntactic category, the call will be dispatched according -to the number of arguments either as "prefix" or as "infix": - - $a.:<+>($b) # equivalent to $a + $b - $a.:<++> # equivalent to ++$a - $a.:<!> # equivalent to !$a - @a.:<[*]> # equivalent to [*] @a - -But it's probably better to spell out the syntactic category when -the actual operator is not obvious: - - $x.infix:[$op]($y) - $x.prefix:[$op] - -You must use a special syntax to call a private method: - - $mybrain!think($pinky) - self!think($pinky) - -For a call on your own private method, you may also use the attribute-ish -form: - - $!think($pinky) # short for $(self!think($pinky)) - -Parentheses (or a colon) are required on the dot/bang notations if there -are any arguments (not counting adverbial arguments). There may be -no space between the method name and the left parenthesis unless you -make use of "unspace": - - .doit # okay, no arguments - .doit() # okay, no arguments - .doit () # ILLEGAL (two terms in a row) - .doit\ () # okay, no arguments, same as .doit() (unspace form) - -Note that the named method call forms are special and do not use the dot -form of postfix. If you attempt to use the postfix operator form, it -will assume you want to call the method with no arguments and then call -the result of I<that>: - - .doit.() # okay, no arguments *twice*, same as .doit().() - .doit\ .() # okay, no arguments *twice*, same as .doit.().() (unspace form) - -However, you can turn any of the named forms above into a list -operator by appending a colon: - - .doit: 1,2,3 # okay, three arguments - .doit(1): 2,3 # okay, one argument plus list - .doit (): 1,2,3 # ILLEGAL (two terms in a row) - -In particular, this allows us to pass a final closure in addition to the -"normal" arguments: - - .doit: { $^a <=> $^b } # okay - .doit(): { $^a <=> $^b } # okay - .doit(1,2,3): { $^a <=> $^b } # okay - -Normally a space is required after the colon to disambiguate what -follows from a pair that extends the previous name. However, -names may not be extended with the C<:{}> pair notation, and therefore -it is allowed to drop the space after the colon if the first argument -to the method is a closure. Hence, any of the above may be written -without the space after the colon: - - .doit:{ $^a <=> $^b } # okay - .doit():{ $^a <=> $^b } # okay - .doit(1,2,3):{ $^a <=> $^b } # okay - -These are parsed as if there were a space there, so the argument list may -continue if the closure is followed by a comma. - -In case of ambiguity between indirect object notation and dot form, -the nearest thing wins: - - dothis $obj.dothat: 1,2,3 - -means - - dothis ($obj.dothat(1,2,3)) - -and you must say - - dothis ($obj.dothat): 1,2,3 - -or - - $obj.dothat.dothis: 1,2,3 - -if you mean the other thing. - -Also note that if any term in a list is a bare closure or pointy block, -it will be considered to be the final argument of its list if the -closure's right curly is followed by a newline. - -If instead the closure's right curly is followed by a method call, the -closure is the invocant: - - @list.map:{ "'$^x $^y'".say }.assuming: 'got:' - -To call the method of the result of the former method call, add parens: - - @list.map({ "got: $^x" }).say - -Even when the colon of a method call does not require whitespace when -followed by a block, it will look odd, so it may be clearer to add the -space to make the method calls on the right look more like they attach -to the block itself instead of the term on the left: - - @list.map: { "'$^x $^y'".say }.assuming: 'got:' - -This will also visually distinguish between a method call introducing -colon and an object pair constructor. - -=head2 Lvalue methods - -Methods (and subs) may be declared as lvalues with C<is rw>. You can -use an argumentless C<rw> method anywhere you can use a variable, -including in C<temp> and C<let> statements. (In fact, you can use an -C<rw> method with arguments as a variable as long as the arguments are -used only to identify the actual value to change, and don't otherwise -have strange side effects that differ between rvalue and lvalue usage. -Setter methods that expect the new value as an argument do not fall -into the well-behaved category, however.) - -=head2 Scalar container indirection - -Method calls on mutable scalars always go to the object contained in -the scalar (autoboxing value types as necessary): - - $result = $object.doit(); - $length = "mystring".codes; - -Method calls on non-scalar variables just calls the C<Array>, C<Hash> -or C<Code> object bound to the variable: - - $elems = @array.elems; - @keys = %hash.keys; - $sig = &sub.signature; - -Use the prefix C<VAR> macro on a scalar variable to get at its -underlying C<Scalar> object: - - if VAR($scalar).readonly {...} - -C<VAR> is a no-op on a non-scalar variables and values: - - VAR(1); # 1 - VAR(@x); # @x - -There's also a corresponding C<< postfix:<.VAR> >> macro that can be used -as if it were a method: - - if $scalar.VAR.readonly {...} - -(But since it's a macro, C<VAR> is not dispatched as a real method. -To dispatch to a real C<.VAR> method, use the indirect C<$obj."VAR"> -form.) - -You can also get at the container through the appropriate symbol table: - - if MY::<$scalar>.readonly {...} - -=head2 FALLBACK methods - -If your class defines a method with the special name C<FALLBACK>, that -method will be called if all other attempts to locate a method -fail, including normal method dispatch as well as delegation (see -below). The first argument to the method will be the method name (as -a string) that was unsuccessfully searched for. The original call's -arguments are passed in as rest of the C<FALLBACK>'s argument list. - -It is legal for the C<FALLBACK> method to be a proto method that dispatches -to multi methods. - -=head1 Class methods - -Other OO languages give you the ability to declare "class" methods that -either don't need or actively prohibit calls on instances. Perl 6 gives -you a choice. If you declare an ordinary method, it can function as a -"class" method when you pass it a type object such as "C<Dog>" regardless -of how defined the prototype object is, as long as the method body doesn't -try to access any information that is undefined in the current instance. -Alternatively, a method can use the C<:U> type modifier on the invocant: - - method oh_so_static(::?CLASS:U:) { - } - -This will cause the method to actively refuse invocations on instances, and -only permit invocation through the type object. - -=head1 Submethods - -Submethods are for declaring infrastructural methods that shouldn't -be inherited by subclasses, such as initializers: - - submethod BUILD (:$arg) { - $!attr = $arg; - } - -Apart from the keyword, submethod declaration and call syntax is -identical to method syntax. You may mix methods and submethods of -the same name within the class hierarchy, but only the methods are -visible to derived classes via inheritance. A submethod is called -only when a method call is dispatched directly to the current class. - -Conjecture: in order to catch spelling errors it is a compile-time -warning to define a submethod in any class that does not inherit the -corresponding method name from some base class. More importantly, this -would help safeguard Liskov substitutability. (But note that the -standard C<Mu> class already supplies a default C<BUILD> and C<new>.) - -=head1 Attributes - -Attributes are stored in an opaque datatype, not in a hash. Not even -the class has to care how they're stored, since they're declared much like -ordinary variables. Instead of C<my>, use C<has>: - - class Dog is Mammal { - has $.name = "fido"; - has $.tail is rw; - has @.legs; - has $!brain; - ... - } - -Public attributes have a secondary sigil of "dot", indicating -the automatic generation of an accessor method of the same name -(unless the class declares an explicit method of that name before -the closing bracket). -Private attributes use an exclamation to indicate that no public accessor is -generated. - - has $!brain; - -The "true name" of the private variable always has the exclamation, but -much like with C<our> variables, you may declare a lexically scoped alias -to the private variable by saying: - - has $brain; # also declares $!brain; - -As with the C<!> declaration, no accessor is generated. - -And any later references to the private variable within the same block -may either use or omit the exclamation, as you wish to emphasize or -ignore the privacy of the variable. Outside the block, you must use -the C<!> form. If you declare with the C<!> form, you must use that -form consistently everywhere. If you declare with the C<.> form, you -also get the private C<!> form as a non-virtual name for the actual -storage location, and you may use either C<!> or C<.> form anywhere -within the class, even if the class is reopened. Outside the class -you must use the public C<.> form, or rely on a method call (which -can be a private method call, but only for trusted classes). - -For public attributes, some traits are copied to the accessor method. -The C<rw> trait causes the generated accessor to be declared C<rw>, -making it an lvalue method. The default is a read-only accessor. - -If you declare the class as C<rw>, then all the class's attributes -default to C<rw>, much like a C struct. - -You may write your own accessors to override any or all of the -autogenerated ones. - -The attribute variables may be used within instance methods to refer -directly to the attribute values. Outside the instance methods, the -only access to attributes is through the accessors since an object has -to be specified. The dot form of attribute variables may be used in -derived classes because the dot form always implies a virtual accessor -call. Every I<dot> declaration also declares a corresponding private -I<exclamation> storage location, and the exclamation form may be used -only in the actual class, not in derived classes. Reference to the -internal storage location via C<$!foo> should generally be restricted -to submethods. Ordinary methods should stick to the C<$.foo> form. - -In fact, within submethods, use of the C<$.foo> form on attributes -that are available as C<$!foo> (that is, that are declared directly -by this class) is illegal and produces a dire compile-time warning -(which may be suppressed). Within a submethod the C<$.foo> form may -only be used on attributes from parent classes, because only the parent -classes' part of the object is guaranteed to be in a consistent state -(because C<bless> calls the C<BUILD> routines of the parent classes before -the child classes). If you attempt to get around this by declaring C<BUILD> as -a method rather than a submethod, that will also be flagged as a dire -(but suppressible) compile-time warning. (It is I<possible> to define -an inheritable C<BUILD> routine if you have access to all the metadata -for the current class, but it's not easy, and it certainly doesn't -happen by accident just because you change C<submethod> to C<method>.) - -Because C<$.foo>, C<@.foo>, C<%.foo>, C<&.foo> are just shorthands of -C<self.foo> with different contexts, the class does not need to declare -any of those as an attribute -- a C<method foo> declaration can work -just as well. - -As with the normal method call forms, only dotless parentheses may -contain arguments. If you use the C<.()> form it will perform an extra -level of indirection after the method call: - - self.foo(1,2,3); # a regular method call - self.foo.(1,2,3); # self.foo().(1,2,3), call .() on closure returned by .foo - $.foo(1,2,3); # calls self.foo under $ context - $.foo.(1,2,3); # $.foo().(1,2,3), call .() on closure returned by .foo - &.foo(1,2,3); # calls self.foo under & context - &.foo.(1,2,3); # &.foo().(1,2,3), call .() on closure returned by .foo - -=head2 Attribute default values - -Pseudo-assignment to an attribute declaration specifies the default -value. The value on the right is treated as an implicit closure and -evaluated at object build time, that is, when the object is being -constructed, not when class is being composed. To refer to a value -computed at compilation or composition time, you can either use a -temporary or a temporal block of some sort: - - has $.r = rand; # each object gets different random value - - constant $random = rand; - has $.r = $random; # every object gets same value - - has $.r = BEGIN { rand }; - has $.r = INIT { rand }; - has $.r = ENTER { rand }; - has $.r = FIRST { rand }; - has $.r = constant $myrand = rand; - -When it is called at C<BUILD> time, the topic of the implicit closure -will be the attribute being initialized, while "self" refers to the -entire object being initialized. The closure will be called at the -end of the C<BUILD> only if the attribute is not otherwise initialized -in either the signature or the body of the C<BUILD>. The closure -actually defines the body of an anonymous method, so C<self> is available -with whatever attributes are constructed by that point in time (including -all parent attributes). The initializers are run in order of declaration -within the class, so a given initializer may refer back to an attribute -defined in a preceding C<has> declaration. - -=head2 Class attributes - -Class attributes are declared with either C<my> or C<our>. The only -difference from ordinary C<my> or C<our> variables is that an accessor -is generated according to the secondary sigil: - - our $.count; # generates a public read-only .count accessor - our %!cache is rw; # generates no public accessor - our @items; # generates no public accessor - my $.count; # generates a public read-only .count accessor - my %!cache is rw; # generates no public accessor - my @items; # generates no public accessor - -Unlike attributes declared with C<has>, class attributes are shared between -the undefined type, all instances of the class, and all subclasses. - -=head1 Construction and Initialization - -All classes inherit a default C<new> constructor from C<Mu>. It -expects all arguments to be named parameters initializing attributes of -the same name. You may write your own C<new> to override the default, -or write constructors with any other name you like. As in Perl 5, -a constructor is any routine that calls C<bless>. Unlike in Perl 5, -you call it as a method on the class object (though any object may be -used as a class object), passing the arguments to be used in building -the object. - -The representation of the class determines how to create the object, -so it's not longer necessary for you to supply a candidate to C<bless>. -For example, a P5Hash object would give you an object representation that -uses hashes just like P5 does. The default C<P6Opaque> representation -doesn't tell you what it's going to use for its representation, since -that's why it's called "opaque", after all. - -The C<bless> method -allows one or more positional arguments representing autovivifying -type objects. Such an object looks like a type name followed by a -hash subscript (see "Autovivifying objects" below). These are used -to initialize superclasses. - -Other than a list of autovivifying type objects, -all arguments to C<bless> must be named arguments, not positional. -Hence, the main purpose of custom constructors is to turn positional -arguments into named arguments for C<bless>. The C<bless> method -allows an object to be used for its class invocant. (Your constructor -need not allow this). In any case, the object is not used as a prototype. -Use C<.clone> instead of C<.bless> if that's what you mean. - -=head2 Semantics of C<bless> - -Any named arguments to C<bless> are automatically passed to the -C<BUILD> routines. - -For normal user classes, C<P6opaque> is the default representation. -Other possibilities are C<P6hash>, C<P5hash>, C<P5array>, C<PyDict>, -C<Cstruct>, etc. If you wish to pass special options to the -representation layer for creating the object, that's between you -and the representation. (A representation might look for additional -class traits, for instance, telling it bit sizes and such.) - -The C<bless> method automatically calls all appropriate C<BUILD> -routines for the current class, -which initializes the object in least-derived to most-derived order. -(C<DESTROY> submethods work the same way, only in reverse.) - -The default C<BUILD> semantics are inherited from C<Mu>, -so you need to write initialization routines only if you wish to -modify the default behavior. The C<bless> method automatically -passes the appropriate argument list to the C<BUILD> of its various -parent classes. If the type of the parent class corresponds to one -of the type objects passed to bless, that type object's argument -list is used. Otherwise all the arguments to bless are passed to -the parent class's C<BUILD>. For the final C<BUILD> of the current -object, all the arguments to C<bless> are passed to the C<BUILD>, so -it can deal with any type objects that need special handling. (It is -allowed to pass type objects that don't correspond to any parent class.) - - class Dog is Animal {...} - my $pet = Dog.new( :name<Fido>, Animal{ :blood<warm>, :legs(4) } ); - -Here we are using an autovivifying C<Animal> type object to specify what -the arguments to C<Animal>'s C<BUILD> routine should look like. (It does -not actually autovivify an C<Animal> apart from the one being created.) - -You can write your own C<BUILD> submethod to control initialization. -If you name an attribute as a parameter, that attribute is initialized -directly, so - - submethod BUILD (:$!tail, :$!legs) {} - -is equivalent to - - submethod BUILD (:$tail is copy, :$legs is copy) { - $!tail := $tail; - $!legs := $legs; - } - -Whether you write your own C<BUILD> or not, at the end of the C<BUILD>, -any default attribute values are implicitly copied into any attributes -that haven't otherwise been initialized. Note that the default C<BUILD> -will only initialize public attributes; you must write your own C<BUILD> -(as above) in order to present private attributes as part of your -initialization API. - -=head2 Cloning - -You can clone an object, changing some of the attributes: - - $newdog = $olddog.clone(:trick<RollOver>); - -=head1 Mutating methods - -You can call an in-place mutator method like this: - - @array .= sort; - -One handy place for an in-place mutator is to call a constructor on a -variable of a known type: - - my Dog $spot .= new(:tail<LONG>, :legs<SHORT>); - -=head1 Calling sets of methods - -For any method name, there may be some number of candidate methods -that could handle the request: typically, inherited methods or -multi variants. The ordinary "dot" operator dispatches -to a method in the standard fashion. There are also "dot" variants -that call some number of methods with the same name: - - $object.meth(@args) # calls one method or dies - $object.?meth(@args) # calls method if there is one, otherwise Nil - $object.*meth(@args) # calls all methods (0 or more, () if none) - $object.+meth(@args) # calls all methods (1 or more, die if none) - -The method name may be quoted when disambiguation is needed: - - $object."+meth"(@args) - $object.'VAR'(@args) - -As with ordinary calls, the identifier supplying the literal method -name may be replaced with an interpolated quote to specify the method -name indirectly. It may also be replaced with an array to specify -the exact list of candidates to be considered: - - my @candidates := $object.WALK(:name<foo>, :breadth, :omit($?CLASS)); - $object.*@candidates(@args); - -The C<WALK> method takes these arguments: - - :canonical # canonical dispatch order - :ascendant # most-derived first, like destruction order - :descendant # least-derived first, like construction order - :preorder # like Perl 5 dispatch - :breadth # like multi dispatch - - :super # only immediate parent classes - :name<name> # only classes containing named method declaration - :omit(Selector) # only classes that don't match selector - :include(Selector) # only classes that match selector - -Any method can defer to the next candidate method in the list by -the special functions C<callsame>, C<callwith>, C<nextsame>, and -C<nextwith>. The "same" variants reuse the original argument list -passed to the current method, whereas the "with" variants allow a -new argument list to be substituted for the rest of the candidates. -The "call" variants dispatch to the rest of the candidates and return -their values to the current method for subsequent processing, whereas -while the "next" variants don't return, but merely defer to the rest -of the candidate list: - - callsame; # call with the original arguments (return here) - callwith(); # call with no arguments (return here) - callwith(1,2,3); # call with a new set of arguments (return here) - nextsame; # redispatch with the original arguments (no return) - nextwith(); # redispatch with no arguments (no return) - nextwith(1,2,3); # redispatch with a new set of arguments (no return) - samewith(1,2,3); # same dispatcher with new arguments (no return) - -For dispatches using C<.> and C<.?>, the return value is the -C<Capture> returned by the first method completed without deferring. -(Such a return value may in fact be failure, but it still counts as a -successful call from the standpoint of the dispatcher.) Likewise the -return value of C<.*> and C<.+> is a list of C<Captures> returned by -those methods that ran to completion without deferring to next method. - -It is also possible to trim the candidate list so that the current -call is considered the final candidate. (This is implicitly the case -already for the dispatch variants that want a single successful call.) -For the multiple call variants, C<lastcall> will cause the dispatcher -to throw away the rest of the candidate list, and the subsequent -return from the current method will produce the final C<Capture> -in the returned list. (If you were already on the last call of the -candidate list, no candidates are thrown away, only the list. So -you can't accidentally throw away the wrong list by running off the -end, since the candidate list is ordinarily not thrown away by the -dispatcher until after the last call.) - -Since it's possible to be dispatching within more than one candidate -list at a time, these control flow calls are defined to apply only to -the dynamically innermost dispatcher. If, for instance, you have a -single dispatch to a C<proto> method that then calls into a multiple -dispatch on the C<multi> methods within a class, C<nextsame> within -one of those C<multi>s would go to the next best C<multi> -method within the class, not the next method candidate in the original -single dispatch. This is not a bad limitation, since dispatch loops -are dynamically scoped; to get to the outermost lists you can "pop" -unwanted candidate lists using C<lastcall>: - - lastcall; nextsame; # call next in grandparent dispatcher loop - -[Conjecture: if necessary, C<lastcall> could have an argument -or invocant to specify which kind of a dispatch loop we think -we're throwing away, in case we're not sure about our context. -This confusion could arise since we use C<nextsame> semantics at -least three different ways: single dispatch, multiple dispatch, -and routine wrapper dispatch.] - -The C<samewith> redispatches the method call using the current dispatcher: this -is mainly intended if you have one "worker" method, and several "frontend" -methods in the same class to avoid code duplication. The frontend methods then -mangle the parameters before sending them off to the worker method with -C<samewith>. - -=head1 Parallel dispatch - -Any of the method call forms may be turned into a hyperoperator by -treating the method call as a postfix: - - @object».meth(@args) # calls one method on each - @object».?meth(@args) # calls method if there is one on each - @object».*meth(@args) # calls all methods (0 or more) on each - @object».+meth(@args) # calls all methods (1 or more) on each - @object».=meth(@args) # calls mutator method on each - @object»!meth(@args) # calls private method on each - -The return value is a list with exactly the same number of elements -as C<@object>. Each such return value is a C<List> or C<List> of C<List> -as specified above for the non-hyper "dot" variants. - -Hyperoperators treat a junction as a scalar value, so saying: - - $junction».meth(@args); - -is just like: - - $junction.meth(@args); - -As with other forms of method call, the "meth" above may be replaced -with a quoted string or variable to do various forms of indirection. - -Note that, as with any hyper operator, the methods may be evaluated -in any order (although the method results are always returned in the -same order as the list of invocants). Use an explicit loop if you -want to do something with ordered side effects, such as I/O. - -=head1 Multisubs and Multimethods - -The "long name" of a subroutine or method includes the type -signature of its invocant arguments. The "short name" doesn't. - -=head2 C<multi> Declarations - -If you put C<multi> in front of any sub declaration, it allows -multiple long names to share a short name, provided all of them are -declared C<multi>, or there is a single prior or outer C<proto> in -the same file that causes all unmarked subs to default to multi in -that lexical scope. If a sub is not marked with C<multi> and it is -not governed within that same file by a C<proto> of the same short -name, it is considered unique, an I<only> sub. (An imported C<proto> -can function as such a governing declaration.) - -For method declarations, the C<proto>, C<multi>, and C<only> -declarations work similarly but not identically. The explicit -declarations work the same, except that calculation of governance -and candidate sets proceeds via the inheritance tree rather than via -lexical scoping. The other difference is that a proto method of a -given short name forcing all unmarked method declarations to assume -multi in all subclasses regardless of which file they are declared in, -unless explicitly overridden via C<only method>. - -=head2 C<only> Declarations - -An C<only> sub (or method) doesn't share with anything outside of it -or declared prior to it. Only one such sub (or method) can inhabit a -given namespace (lexical scope or class), and it hides any outer subs -(or less-derived methods) of the same short name. It is illegal for -a C<multi> or C<proto> declaration to share the same scope with an -C<only> declaration of the same short name. - -Since they come from a different file, the default C<proto> -declarations provided by Perl from the setting scope do I<not> -automatically set the defaults in the user's scope unless explicitly -imported, so a C<sub> declaration there that happens to be the same -as a setting C<proto> is considered C<only> unless explicitly marked -C<multi>. (This allows us to add new C<proto> declarations in the -setting without breaking the user's old code.) In the absence of -such an explicit C<sub> declaration, however, the C<proto> from the -innermost outer lexical scope is used by the compiler in the analysis -of any calls to that short name. (Since only list operators may be -post-declared, as soon as the compiler sees a non-listop operator it -is free to apply the setting's C<proto> since any user-defined C<only> -version of it must of necessity be declared or imported earlier in -the user's file or not at all.) - -=head2 C<proto> Declarations - -A C<proto> always functions as a dispatcher around any C<multi>s -declared after it in the same scope, More specifically, it is the -generic prototype of a dispatcher, which must be instantiated anew -in each scope that has a different candidate list. (This works -much like type punning from roles to classes. Or you can think of -this dispatcher as a priming of the proto's code with the candidate -list appropriate to the scope.) For the sake of discussion, let us -say that there is a declarator equivalent to C<only> that is instead -spelled C<dispatch>. Generally a user never writes a C<dispatch> sub -(it might not even be allowed); a C<dispatch> is always instantiated -from the governing C<proto>. A new C<dispatch> sub or method is -autogenerated in any scope that needs one, that is, in any scope that -can see a different set of multi declarations than its parent scope -(or scopes, in the case of multiple inheritance). - -More precisely, for any given C<proto> and a point of call, there -is a candidate set of routines (functions or methods) that is the -intersection of two sets: the set of routines governed downward by -the C<proto> and the set of routines visible upward from the point of -a call. It is allowed to reuse the C<dispatch> of a parent scope if -and only if it would result in the same candidate list in the current -scope (the scope at the point of call). - -Since C<dispatch> is nearly identical to C<only>, saying C<&foo> -always refers to the innermost visible C<dispatch> or C<only> sub, -never to a C<proto> or C<multi>. Likewise, C<$obj.can('foo')> will -return the most-derived C<dispatch> or C<only> method. - -=head2 C<proto> Signatures - -Within its scope, the signature of a C<proto> also nails down the presumed -order and naming of positional parameters, so that any call to that -short name with named arguments in that scope can presume to rearrange -those arguments into positional parameters based on that information. -(Unrecognized names remain named arguments.) Any other type information -or traits attached to the C<proto> may also be passed along to the -routines within its scope, so a C<proto> definition can be used to factor -out common traits. This is particularly useful for establishing -grammatical categories in a grammar by declaring a C<proto> C<token> -or C<proto> C<rule>. (Perl 6's grammar does this, for instance.) - -=head2 C<multi> Variables - -You can have multiple C<multi> variables of the same name in the -same scope, and they all share the same storage location and type. -These are declared by one C<proto> declaration at the top, in which case -you may leave the C<multi> implicit on the rest of the declarations in -the same scope. You might do this when you suspect you'll have multiple -declarations of the same variable name (such code might be produced by a -macro or by a code generator, for instance) and you wish to suppress any -possible warnings about redefinition. - -=head2 C<multi> Routines - -In contrast, C<multi> routines can have only one instance of the long -name in any namespace, and that instance hides any outer (or less-derived) -routines with the same long name. It does not hide any routines with -the same short name but a different long name. In other words, C<multi>s -with the same short name can come from several different namespaces -provided their long names differ and their short names aren't hidden -by an C<only> or C<proto> declaration in some intermediate scope. - -=head2 Multisub Resolution - -When you call a routine with a particular short name, if there are -multiple visible long names, they are all considered candidates. -They are sorted into an order according to how close the run-time types -of the arguments match up with the declared types of the parameters of -each candidate. The best candidate is called, unless there's a tie, -in which case the tied candidates are redispatched using any additional -tiebreaker strategies (see below). For the purpose of this nominal typing, -no constrained type is considered to be a type name; instead the -constrained type is unwound into its base type plus constraint. Only the -base type upon which the constrained type is based is considered for the -nominal type match (along with the fact that it is constrained). That -is, if you have a parameter: - - subset Odd of Int where { $_ % 2 } - proto foo {*} - multi foo (Odd $i) {...} - -it is treated as if you'd instead said: - - multi foo (Int $i where { $_ % 2 }) {...} - -Any constrained type is considered to have a base type that is "epsilon" -narrower than the corresponding unconstrained type. The compile-time -topological sort takes into account the presence of at least one -constraint, but nothing about the number or nature of any additional -constraints. If we think of Int' as any constrained version of Int, -then Int' is always tighter nominally than Int. (Int' is a meta-notation, -not Perl 6 syntax.) - -The order in which candidates are considered is defined by a -topological sort based on the "type narrowness" of each candidate's -long name, where that in turn depends on the narrowness of each -parameter that is participating. Identical types are considered tied. -Parameters whose types are not comparable are also considered tied. -A candidate is considered narrower than another candidate if at least -one of its parameters is narrower and all the rest of its parameters -are either narrower or tied. Also, if the signature has any additional -required parameters not participating in the long name, the signature -as a whole is considered epsilon tighter than any signature without -extra parameters. In essence, the remaining arguments are added to -the longname as if the user had declared a capture parameter to bind -the rest of the arguments, and that capture parameter has a constraint -that it must bind successfully to the additional required parameters. -All such signatures within a given rank are considered equivalent, -and subject to tiebreaker B below. - -This defines the partial ordering of all the candidates. If the -topological sort detects a circularity in the partial ordering, -all candidates in the circle are considered tied. A warning will be -issued at C<CHECK> time if this is detected and there is no suitable -tiebreaker that could break the tie. - -=head3 Candidate Tiebreaking - -There are three tiebreaking modes, in increasing order of desperation: - - A) inner or derived scope - B) run-time constraint processing - C) use of a candidate marked with "is default" - -Tiebreaker A simply prefers candidates in an inner or more -derived scope over candidates in an outer or less derived scope. -For candidates in the same scope, we proceed to tiebreaker B. - -In the absence of any constraints, ties in tiebreaker A -immediately failover to tiebreaker C; if not resolved by C, -they warn at compile time about an ambiguous dispatch. - -If there are any tied candidates with constraints, it follows from our -definitions above that all of them are considered to be constrained. -In the presence of longname parameters with constraints, or the -implied constraint of extra required arguments, tiebreaker B is -applied. Candidates which are tied nominally but have constraints -are considered to be a completely different situation, insofar as it -is assumed the user knows exactly why each candidate has the extra -constraints it has. Thus, constrained signatures are considered to -be much more like a switch defined by the user. So for tiebreaker -B the candidates are simply called in the order they were declared, -and the first one that successfully binds (and completes without -calling nextsame or nextwith) is considered the winner, and all the -other tied candidates are ignored. If all the constrained -candidates fail, we throw out the rank of constrained variants and -proceed to the next tighter rank, which may consist of the -unconstrained variants without extra arguments. - -For ranks that are not decided by constraint (tiebreaker B), -tiebreaker C is used: only candidates marked with the C<default> -trait are considered, and the best matching default routine is used. -If there are no default routines, or if two or more of the defaults -are tied for best, the dispatch fails. - -=head3 Parameter Constraint Exclusion - -Ordinarily all the parameters of a multi sub are considered for dispatch. -Here's a declaration for an integer range operator with two parameters -in its long name: - - multi sub infix:<..>(Int $min, Int $max) {...} - -Sometimes you want to have parameters that aren't counted as part of the -long name. For instance, if you want to allow an optional "step" parameter -to your range operator, but not consider it for multi dispatch, then put a -double semicolon instead of a comma before it: - - multi sub infix:<..>(Int $min, Int $max;; Int $by = 1) {...} - -The double semicolon, if any, determines the complete long name of -a C<multi>. (In the absence of that, a double semicolon is assumed -after the last declared argument, but before any return signature.) -Note that a call to the routine must still be compatible with -subsequent arguments. - -Note that the C<$by> is not a required parameter, so doesn't impose -the kind of constraint that allows tiebreaker B. If the default -were omitted, it would be a required parameter, and subject to tiebreaker B. -Likewise an ordinary named parameter does not participate as a tiebreaker, -but you can mark named parameters as required to effectively make -a switch based on named binding: - - multi foo (Int $a;; :$x!) {...} # constrained - multi foo (Int $a;; :$y!) {...} # constrained - multi foo (Int $a;; :$z!) {...} # constrained - - multi foo (Int $a;; *%_) {...} # unconstrained - -The first three are dispatched under tiebreaker B as a constrained -rank. If none of them can match, the final one is dispatched as -an unconstrained rank, since C<*%_> is not considered a required -parameter. - -=head3 Constrained Type Candidates - -Likewise, constrained types sort before unconstrained: - - multi bar (Even $a) {...} # constrained - multi bar (Odd $a) {...} # constrained - - multi bar (Int $a) {...} # unconstrained - -And values used as subset types also sort first, and are dispatched -on a first-to-match basis: - - multi baz (0) {...} # constrained - multi baz (1) {...} # constrained - - multi baz (Int $x) {...} # unconstrained - -If some of the constrained candidates come by import from other modules, -they are all considered to be declared at the point of importation -for purposes of tiebreaking; subsequent tiebreaking is provided by -the original order in the used module. - -[Conjecture: However, a given C<multi> may advertise multiple long names, -some of which are shorter than the complete long name. This is done -by putting a semicolon after each advertised long name (replacing -the comma, if present). A semicolon has the effect of inserting two -candidates into the list. One of them is inserted with exactly the -same types, as if the semicolon were a comma. The other is inserted -as if all the types after the semicolon were of type C<Any>, which puts -it later in the list than the narrower actual candidate. This merely -determines its sort order; the candidate uses its real type signature -if the dispatcher gets to it after rejecting all earlier entries on the -candidate list. If that set of delayed candidates also contains ties, -then additional semicolons have the same effect within that sublist -of ties. Note, however, that semicolon is a no-op if the types after -it are all C<Any>. (As a limiting case, putting a semicolon after -every parameter produces dispatch semantics much like Common Lisp. -And putting a semicolon after only the first argument is much like -ordinary single-dispatch methods.) Note: This single-semicolon syntax -is merely to be considered reserved until we understand the semantics -of it, and more importantly, the pragmatics of it (that is, whether -it has any valid use case). Until then only the double-semicolon -form will be implemented in the standard language.] - -A C<method> or C<submethod> doesn't ordinarily participate in any -subroutine-dispatch process. However, they can be made to do so if -prefixed with a C<my> or C<our> declarator. - -=head3 Multi Submethods et Cetera - -Multi submethods work just like multi methods except they are constrained -to an exact type match on the invocant, just as ordinary submethods are. - -Perl 6.0.0 is not required to support multiple dispatch on named -parameters, only on positional parameters. Note however that any -dispatcher derived from C<proto> will map named arguments to known -declared positional parameters and call the C<multi> candidates with -positionals for those arguments rather than named arguments. - -Within a multiple dispatch, C<nextsame> means to try the next best -match, or next best default in case of tie. - -The C<sub> keyword is optional immediately after a C<proto>, C<multi>, -or C<only> keyword, but the C<method> keyword is not. - -A C<proto> declaration may not occur after a C<multi> declaration in the -same scope. - -=head2 Method call vs. Subroutine call - -The caller indicates whether to make a method call or subroutine -call by the call syntax. The "dot" form and the indirect object form -default to method calls. All other prefix calls default to subroutine calls. -This applies to prefix unary operators as well: - - !$obj; # same as $obj.prefix:<!> - -A method call considers only methods (including multi-methods and submethods) -from the class hierarchy of its invocant, and fails if none is found. The -object in question is in charge of interpreting the meaning of the method -name, so if the object is a foreign object, the name will be interpreted -by that foreign runtime. - -A subroutine call considers only visible subroutines (including -submethods) of that name. The object itself has no say in the -dispatch; the subroutine dispatcher considers only the types the -arguments involved, along with the name. Hence foreign objects passed -to subroutines are forced to follow Perl semantics (to the extent -foreign types can be coerced into Perl types, otherwise they fail). - -There is no fail-over either from subroutine to method dispatch or -vice versa. However, you may use C<is export> on a method -definition to make it available also as a C<multi> sub. As with indirect -object syntax, the first argument is still always the invocant, -but the export allows you to use a comma after the invocant instead of -a colon, or to omit the colon entirely in the case of a method with -no arguments other than the invocant. Many standard methods (such -as C<IO::close> and C<Array::push>) are automatically exported to the -C<CORE> namespace by default. For other exported methods, you will not -see the C<multi> sub definition unless you C<use> the class in your scope, -which will import the C<proto> (and associated C<multi> subs) lexically, -after which you can call it using normal subroutine call syntax. - -In the absence of an explicit type on the method's invocant, the -exported C<multi> sub's first argument is implicitly constrained to -match the class in which it was defined or composed, so for instance -the C<multi> version of C<close> requires its first argument to be of -type C<IO> or one of its subclasses. If the invocant is explicitly -typed, that will govern the type coverage of the corresponding C<multi>'s -first argument, whether that is more specific or more general than -the class's invocant would naturally be. (But be aware that if it's -more specific than C<::?CLASS>, the binding may reject an otherwise -valid single dispatch as well as a multi dispatch.) In any case, -it does no good to overgeneralize the invocant if the routine itself -cannot handle the broader type. In such a situation you must write -a wrapper to coerce to the narrower type. - -=head1 Trusts - -Attributes are tied to a particular class definition, so a method -can only directly access the attributes of a class it's defined within -when the invocant is the "self" of that attribute. -However, it may call the private attribute accessors from a different -class if that other class has indicated that it trusts the class the -multi method is defined in: - - class MyClass { - trusts YourClass; - ... - } - -The trust really only applies to C<MyClass>, not to possible subclasses -thereof. - -The syntax for calling back to C<MyClass> is C<$obj!MyClass::meth()>. -Note that private attribute accessors are always invoked directly, -never via a dispatcher, since there is never any question about which -object is being referred to. Hence, the private accessor notation -may be aggressively inlined for simple attributes, and no simpler -notation is needed for accessing another object's private attributes. - -=head1 Delegation - -Delegation lets you pretend that some other object's methods are your own. -Delegation is specified by a C<handles> trait verb with an argument -specifying one or more method names that the current object and the -delegated object will have in common: - - has $tail handles 'wag'; - -Since the method name (but nothing else) is known at class construction -time, the following C<.wag> method is autogenerated for you: - - method wag (|args) { $!tail.wag(|args) } - -You can specify multiple method names: - - has $.legs handles <walk run lope shake lift>; - -It's illegal to call the outer method unless the attribute -has been initialized to an object of a type supporting the method, -such as by: - - has Tail $.tail handles 'wag' .= new(|%_); - -Note that putting a C<Tail> type on the attribute does not necessarily -mean that the method is always delegated to the C<Tail> class. -The dispatch is still based on the I<run-time> type of the object, -not the declared type. - -Any other kind of argument to C<handles> is considered to be a -smartmatch selector for method names. All such selectors establish a failover -to be used only if normal method dispatch fails, so it cannot be used to -override any method in the normal ancestry of the object. So you can say: - - has $.fur is rw handles /^get_/; - -If you say - - has $.fur is rw handles Groomable; - -then you get only those methods available via the C<Groomable> role -or class. To delegate everything, use the C<Whatever> matcher: - - has $the_real_me handles *; - -Wildcard matches are evaluated only after it has been determined -that there's no exact match to the method name anywhere in this -object or in any of its parents. When you have multiple wildcard -delegations to different objects, it's possible to have a conflict -of method names. Wildcard method matches are evaluated in order, -so the earliest one wins. (Non-wildcard method conflicts can be -caught at class composition time.) If the wildcards for this class -find nothing, then wildcards are checked for each of the ancestral -classes in standard method resolution order. - -The form with C<*> checks only for existing methods in the delegate's -class (or its parents). It will not call any kind of a fallback -via the delegate. (This allows you to call a C<FALLBACK> routine -of your own if the delegation would fail, since your own C<FALLBACK> -always runs after delegation, even wildcard delegation.) If instead -you want to delegate completely and utterly, including a search of -the delegate for its own fallback methods, with abject failure if -the delegate can't handle it, then use the "HyperWhatever" instead: - - has $the_real_me handles **; - -If, where you would ordinarily specify a string, you put a pair, then -the pair maps the method name in this class to the method name in the -other class. If you put a hash, each key/value pair is treated as -such a mapping. Such mappings are not considered wildcards. - - has $.fur handles { :shakefur<shake>, :scratch<get_fleas> }; - -You I<can> do a wildcard renaming, but not with pairs. Instead do smartmatch -with a substitution: - - has $.fur handles (s/^furget_/get_/); - -Ordinarily delegation is based on an attribute holding an object, but it can -also be based on the return value of a method: - - method select_tail handles <wag hang> {...} - -=head1 Types and Subtypes - -The type system of Perl consists of roles, classes, and subtypes. -You can declare a subtype like this: - - my subset Str_not2b of Str where /^[isnt|arent|amnot|aint]$/; - -or this: - - my Str subset Str_not2b where /^[isnt|arent|amnot|aint]$/; - -An anonymous subtype looks like this: - - Str where /^[isnt|arent|amnot|aint]$/; - -A C<where> clause implies future smartmatching of some kind: the as-yet -unspecified object of the type on the left must match the selector on -the right. Our example is roughly equivalent to this closure: - - { $_.does(Str) and $_ ~~ /^[isnt|arent|amnot|aint]$/; } - -except that a subtype knows when to call itself. - -A subtype is not a subclass. Subclasses add capabilities, whereas -a subtype adds constraints (takes away capabilities). A subtype is -primarily a handy way of sneaking smartmatching into multiple dispatch. -Just as a role allows you to specify something more general than a -class, a subtype allows you to specify something more specific than -a class. A subtype specifies a subset of the values that the original -type specified, which is why we use the C<subset> keyword for it. - -While subtypes are primarily intended for restricting parameter types -for multiple dispatch, they also let you impose preconditions on -assignment. If you declare any container with a subtype, -Perl will check the constraint against any value you might try to -bind or assign to the container. - - subset Str_not2b of Str where /^[isnt|arent|amnot|aint]$/; - subset EvenNum of Num where { $^n % 2 == 0 } - - my Str_not2b $hamlet; - $hamlet = 'isnt'; # Okay because 'isnt' ~~ /^[isnt|arent|amnot|aint]$/ - $hamlet = 'amnt'; # Bzzzzzzzt! 'amnt' !~~ /^[isnt|arent|amnot|aint]$/ - - my EvenNum $n; - $n = 2; # Okay - $n = -2; # Okay - $n = 0; # Okay - $n = 3; # Bzzzzzzzt - -It's legal to base one subtype on another; it just adds an additional -constraint. That is, it's a subset of a subset. - -You can use an anonymous subtype in a signature: - - sub check_even (Num where { $^n % 2 == 0 } $even) {...} - -That's a bit unwieldy, but by the normal type declaration rules you -can turn it around to get the variable out front: - - sub check_even ($even of Num where { $^n % 2 == 0 }) {...} - -and just for convenience we also let you write it: - - sub check_even (Num $even where { $^n % 2 == 0 }) {...} - -since all the type constraints in a signature parameter are just -anded together anyway. - -You can leave out the block when matching against a literal value of some -kind: - - proto sub fib (Int $) {*} - multi sub fib (Int $n where 0|1) { return $n } - multi sub fib (Int $n) { return fib($n-1) + fib($n-2) } - -In fact, you can leave out the C<where> declaration altogether: - - multi sub fib (0) { return 0 } - multi sub fib (1) { return 1 } - multi sub fib (Int $n) { return fib($n-1) + fib($n-2) } - -Subtype constraints are used as tiebreakers in multiple dispatch: - - use Rules::Common :profanity; - - multi sub mesg ($mesg of Str where /<profanity>/ is copy) { - $mesg ~~ s:g/<profanity>/[expletive deleted]/; - print $MESG_LOG: $mesg; - } - - multi sub mesg ($mesg of Str) { - print $MESG_LOG: $mesg; - } - -For multi dispatch, a long name with a matching constraint is preferred over -an equivalent one with no constraint. So the first C<mesg> above is -preferred if the constraint matches; otherwise the second is preferred. - -To export a subset type, put the export trait just before the C<where>: - - subset Positive of Int is export where * > 0; - -Note that the declaration of the C<of> type for a subset doesn't -really mean what an C<of> type means elsewhere in the language. It is -merely declaring the universe of input values for a boolean function. -In fact, when used as a coercion, a subset type returns a C<Bool> -based on its condition, so it can be used directly as a predicate -without the overhead of smartmatching: - - if Even($x) { ... } - .say if .Even for 1..10; - -=head2 Abstract vs Concrete types - -For any named type, certain other subset types may automatically be derived -from it by appending an appropriate adverbial to its name: - - Int:_ Allow either defined or undefined Int values - Int:D Allow only defined (concrete) Int values - Int:U Allow only undefined (abstract) Int values - -That is, these mean something like: - - Int:D Int:_ where DEFINITE($_) - Int:U Int:_ where not(DEFINITE($_)) - -where C<DEFINITE> is a boolean macro that says whether the object -in question has a valid concrete representation (see L</Introspection> below). - -In standard Perl 6, C<Int> is generally assumed to mean C<Int:_>, except -for invocants, where the default is C<Int:D>. (The default C<new> method -has a prototype whose invocant is C<:U> instead, so all new methods all -default to allowing type objects.) - -These defaults may be changed within a lexical scope by various pragmas. -In particular, - - use parameters :D; - -will cause non-invocant parameters to default to C<:D>. Conjecturally, - - use variables :D; - -would do the same for types used in variable declarations. - -In such lexical -scopes you may use the C<:_> form to get back to the standard behavior. -In particular, since invocants default to defined, - - use invocant :_; - -will make invocants allow any sort of defined or undefined invocant. - -=head2 Multiple constraints - -[Conjecture: This entire section is considered a guess at our -post-6.0.0 direction. For 6.0.0 we will allow only a single constraint -before the variable, and post constraints will all be considered -"epsilon" narrower than the single type on the left. The single -constraint on the left may, however, be a value like 0 or a named -subset type. Such a named subset type may be predeclared with an -arbitrarily complex C<where> clause; for 6.0.0 any structure type -information inferable from the C<where> clause will be ignored, -and the declared subset type will simply be considered nominally -derived from the C<of> type mentioned in the same declaration.] - -More generally, a parameter can have a set of constraints, and -the set of constraints defines the formal type of the parameter, -as visible to the signature. (No one constraint is privileged as -the storage type of the actual argument, unless it is a native type.) -All constraints are considered in type narrowness. -That is, these are equivalently narrow: - - Foo Bar @x - Bar Foo @x - -The constraint implied by the sigil also counts as part of the official type. -The sigil is actually a constraint on the container, so the actual -type of the parameter above is something like: - - Positional[subset :: of Any where Foo & Bar] - -Static C<where> clauses also count as part of the official type. -A C<where> clause is considered static if it can be applied to -the types to the left of it at compile time to produce a known finite set -of values. For instance, a subset of an enum type is a static set -of values. Hence - - Day $d where 'Mon'..'Fri' - -is considered equivalent to - - subset Weekday of Day where 'Mon'..'Fri'; - Weekday $d - -Types mentioned in a dynamic C<where> class are not considered part of -the official type, except insofar as the type includes the notion: "is -also constrained by a dynamic C<where> clause", which narrows it by -epsilon over the equivalent type without a C<where> clause. - - Foo Bar @x # type is Foo & Bar & Positional - Foo Bar @x where Baz # slightly tighter than Foo Bar Positional - -The set of constraints for a parameter creates a subset type that implies -some set of allowed values for the parameter. The set of allowed values -may or may not be determinable at compile time. When the set of allowed -values is determinable at compile time, we call it a static subtype. - -Type constraints that resolve to a static subtype (that is, with a -fixed set of elements knowable (if not known) at compile time) are -considered to be narrower than type constraints that involve run-time -calculation, or are otherwise intractable at compile time. -Note that all values such as 0 or "foo" are considered -singleton static subtypes. Singleton values are considered narrower -than a subtype with multiple values, even if the subtype contains -the value in question. This is because, for enumerable types, type -narrowness is defined by doing set theory on the set of enumerated values. - -So assuming: - - my enum Day ['Sun','Mon','Tue','Wed','Thu','Fri','Sat']; - subset Weekday of Day where 'Mon' .. 'Fri'; # considered static - subset Today of Day where *.today; - -we have the following pecking order: - - Parameter # Set of possible values - ========= ======================== - Int $n # Int - - Int $n where Today # Int plus dynamic where - Int $n where 1 <= * <= 5 # Int plus dynamic where - - Day $n # 0..6 - - Day $n where Today # 0..6 plus dynamic where - - Day $n where 1 <= * <= 5 # 1..5 - Int $n where Weekday # 1..5 - Day $n where Weekday # 1..5 - Weekday $n # 1..5 - - Tue # 2 - -Note the difference between: - - Int $n where 1 <= * <= 5 # Int plus dynamic where - Day $n where 1 <= * <= 5 # 1..5 - -The first C<where> is considered dynamic not because of the nature -of the comparisons but because C<Int> is not finitely enumerable. -Our C<Weekday> subset type can calculate the set membership at compile -time because it is based on the C<Day> enum, and hence is considered -static despite the use of a C<where>. Had we based C<Weekday> on -C<Int> it would have been considered dynamic. Note, however, that -with "anded" constraints, any enum type governs looser types, so - - Int Day $n where 1 <= * <= 5 - -is considered static, since C<Day> is an enum, and cuts down the -search space. - -The basic principle we're trying to get at is this: in comparing -two parameter types, the narrowness is determined by the subset -relationships on the sets of possible values, not on the names of -constraints, or the method by which those constraints are specified. -For practical reasons, we limit our subset knowledge to what can be -easily known at compile time, and consider the presence of one or -more dynamic constraints to be epsilon narrower than the same set of -possible values without a dynamic constraint. - -As a first approximation for 6.0.0, subsets of enums are static, -and other subsets are dynamic. We may refine this in subsequent -versions of Perl. - -=head1 Enumerations - -An enumeration is a type that facilitates the use of a set of symbols to -represent a set of constant values. Its most obvious use is the translation -of those symbols to their corresponding values. Each enumeration association -is a constant pair known as an I<enum>, which is of type C<Enum>. -Each enum associates an I<enum key> with an I<enum value>. Semantically -therefore, an enumeration operates like a constant hash, but since it uses a -package C<Stash> to hold the entries, it presents itself to the -user's namespace as a typename package containing a set of constant -declarations. That is, - - enum E <a b c>; - -is largely syntactic sugar for: - - package E { - constant a = 0; - constant b = 1; - constant c = 2; - } - -(However, the C<enum> declaration supplies extra semantics.) - -Such constant declarations allow the use of the declared names to -stand in for the values where a value is desired. In addition, since -a constant declaration introduces a name that behaves as a subtype -matching a single value, the enum key can function as a typename in -certain capacities where a typename is required. The name of the -enumeration as a whole is also considered a typename, and may be -used to represent the set of values. (Note that when we wish to -verbally distinguish the enumeration as a whole from each individual -enum pair, we use the long term "enumeration" for the former, despite -the fact that it is declared using the C<enum> keyword.) - -In the C<enum> declaration, the keys are specified as a parenthesized -list, or an equivalent angle bracket list: - - my enum Day ('Sun','Mon','Tue','Wed','Thu','Fri','Sat'); - my enum Day <Sun Mon Tue Wed Thu Fri Sat>; - -=head2 Value Generation - -The values are generated implicitly by default, but may also be -specified explicitly. If the first value is unspecified, it defaults -to 0. To specify the first value, use pair notation (see below). - -If the declared enumeration typename begins with an uppercase letter, -the enum values will be derived from C<Int> or C<Str> as appropriate. -If the enumeration typename is lowercase, the enumeration is assumed -to be representing a set of native values, so the default value type -is C<int> or C<buf>. - -The base type can be specified if desired: - - my bit enum maybe <no yes>; - my Int enum day ('Sun','Mon','Tue','Wed','Thu','Fri','Sat'); - our enum day of uint4 <Sun Mon Tue Wed Thu Fri Sat>; - -The declared base type automatically distributes itself to the individual -constant values. For non-native types, the enum objects are guaranteed -only to be derived from and convertible to the specified type. The -actual type of the enum object returned by using the symbol is the -enumeration type itself. - - Fri.WHAT # Day, not Int. - +Fri # 5 - Fri.Numeric # 5 - Fri ~~ Int # True, because derived from Int - Fri.perl # 'Day::Fri' - ~Fri # 'Fri' (only for numeric enums) - Fri.Stringy # 'Fri' (only for numeric enums) - Fri.Str # 'Fri' (only for numeric enums) - Fri.gist # 'Fri' (used by say) - Fri.key # 'Fri' - Fri.value # 5 - Fri.pair # :Fri(5) - Fri.kv # 'Fri', 5 - Fri.defined # True - -Other than that, number valued enums act just like numbers, while -string valued enums act just like strings. C<Fri.so> is true -because its value is 5 rather than 0. C<Sun.so> is false. - -Enums based on native types may be used only for their value, since a -native value doesn't know its own type. - -Since methods on native types delegate to their container's type, -a variable typed with a native type will know which method to call: - - my day $d = 3; - $d.key # returns "Wed" - -Such declarational forms are not always convenient; to translate -native enum values back to their names operationally, you can pull -out the enum type's C<EnumMap> and invert it: - - constant %dayname := day.enums.invert; - %dayname{3} # Wed - -=head2 The Enumeration Type - -The enumeration type itself is an undefined type object, but supplies -convenient methods: - - Day.defined # False - 3 ~~ Day($_) # True, in range - 8 ~~ Day($_) # False, *not* in range - Day.enums # map of key/value pairs - -The C<.enums> method returns an C<EnumMap> that may be used either as -a constant hash value or as a list of pairs: - - my enum CoinFace <Heads Tails>; - CoinFace.enums.keys # ('Heads', 'Tails') - CoinFace.enums.values # (0, 1) - CoinFace.enums.kv # ('Heads', 0, 'Tails', 1) - CoinFace.enums.invert # (0 => 'Heads', 1 => 'Tails') - CoinFace.enums.[1] # Tails => 1 - -The enumeration typename itself may be used as a coercion operator from either -the key name or a value. First the argument is looked up as a key; -if that is found, the enum object is returned. If the key name lookup -fails, the value is looked up using an inverted mapping table (which -might have duplicates if the mapping is not one-to-one): - - Day('Tue') # Tue constant, found as key - Day::('Tue') # (same thing) - - Day(3) # Wed constant, found as value - Day.enums.invert{3} # (same thing) - -=head2 Anonymous Enumerations - -An anonymous C<enum> just makes sure each string turns into a pair with -sequentially increasing values, so: - - %e = enum < ook! ook. ook? >; - -is equivalent to: - - %e = (); - %e<ook!> = 0; - %e<ook.> = 1; - %e<ook?> = 2; - -The return value of an anonymous enumeration is an C<EnumMap>. The -C<enum> keyword is still a declarator here, so the list is evaluated at -compile time. Use a coercion to C<EnumMap> to get a run-time map. - -=head2 Composition from Pairs - -The enumeration composer inspects list values for pairs, where the value -of the pair sets the next value explicitly. Non-pairs C<++> the -previous value. (Str and buf types increment like Perl 5 strings.) -Since the C<«...»> quoter automatically recognizes -pair syntax along with interpolations, we can simply say: - - my enum DayOfWeek «:Sun(1) Mon Tue Wed Thu Fri Sat»; - - our Str enum Phonetic «:Alpha<A> Bravo Charlie Delta - Echo Foxtrot Golf Hotel India Juliet - Kilo Lima Mike November Oscar Papa - Quebec Romeo Sierra Tango Uniform - Victor Whiskey X-ray Yankee Zulu»; - - enum roman (i => 1, v => 5, - x => 10, l => 50, - c => 100, d => 500, - m => 1000); - - my Item enum hex «:zero(0) one two three four five six seven eight nine - :ten<a> eleven twelve thirteen fourteen fifteen»; - -Note that enumeration declaration evaluates its list at compile time, so -any interpolation into such a list may not depend on run-time values. -Otherwise enums wouldn't be constants. (If this isn't what you want, -try initializing an ordinary declaration using C<::=> to make a scoped -readonly value.) - -You may import enum types; only non-colliding symbols are imported. -Colliding enum keys are hidden and must be disambiguated with the -type name. Any attempt to use the ambiguous name will result in a fatal -compilation error. (All colliding values are hidden, not just the new one, -or the old one.) Any explicit sub or type definition hides all imported -enum keys of the same name but will produce a warning unless -C<is redefined> is included. - -=head2 Anonymous Mixin Roles using C<but> or C<does> - -Since non-native C<Enum> values know their enumeration type, they may be -used to name a desired property on the right side of a C<but> or C<does>. -So these: - - $x = "Today" but Tue; - $y does True; - -expand to: - - $x = "Today" but Day::Tue; - $y does Bool::True; - -The C<but> and C<does> operators expect a role on their right side. -An enum type is not in itself a role type; however, the C<but> -and C<does> operators know that when a user supplies an enum type, -it implies the generation of an anonymous mixin role that creates an -appropriate accessor, read-write if an attribute is being created, and -read-only otherwise. It depends on whether you mix in the whole -or a specific enum or the whole enumeration: - - $x = "Today" but Tue; # $x.Day is read-only - $x = "Today" but Day; # $x.Day is read-write - -Mixing in a specific enum object implies only the readonly accessor. - - $x = "Today" but Tue; - -really means something like: - - $x = "Today".clone; - $x does anon role { method Day { Day::Tue } }; - -The fully qualified form does the same thing, and is useful -in case of enum collision: - - $x = "Today" but Day::Tue; - -Note that the method name is still C<.Day>, however. If -you wish to mix in colliding method names, you'll have to -mixin your own anonymous role with different method names. - -Since an enumeration supplies the type name as a coercion, you can -also say: - - $x = "Today" but Day(Tue); - $x = "Today" but Day(2); - -After any of those - - $x.Day - -returns C<Day::Tue> (that is, the constant object representing 2), and -both the general and specific names function as typenames in normal -constraint and coercion uses. Hence, - - $x ~~ Day - $x ~~ Tue - $x.Day == Tue - Day($x) == Tue - $x.Tue - -all return true, and - - $x.Wed - $x.Day == Wed - 8 ~~ Day($_) - -all return false. - -Mixing in the full enumeration type produces a read-write attribute: - - $x = "Today" but Day; # read-write .Day - -really means something like: - - $x = "Today".clone; - $x does anon role { has Day $.Day is rw } - -except that nothing happens if there is already a C<rw> attribute of that name. - -Note that the attribute is not initialized. If that is desired -you can supply a C<WHENCE> closure: - - $x = "Today" but Day{ :Day(Tue) } - $x = "Today" but Day{ Tue } # conjecturally, for "simple" roles - -=head2 Adding Traits - -To add traits to an enumeration declaration, place them after the declared -name but before the list: - - enum Size is silly <regular large jumbo>; - -=head2 Exporting - -To export an enumeration, place the export trait just before the list: - - enum Maybe is export <No Yes Dunno>; - -=head2 Implying a Role - -To declare that an enumeration implies a particular role, -supply a C<does> in the same location - - enum Maybe does TristateLogic <No Yes Dunno>; - -=head2 Built-in Enumerations - -Two built-in enumerations are: - - our enum Bool does Boolean <False True>; - our enum Taint does Tainting <Untainted Tainted>; - -Note that C<Bool> and C<Taint> are not role names themselves but imply -roles, and the enum values are really subset types of C<Int>, though the -constant objects themselves know that they are of type C<Bool> or C<Taint>, -and can therefore be used correctly in multimethod dispatch. - -You can call the low-level C<.Bool> coercion on any built-in type, because -all built-in types do the C<Boolean> role, which requires a C<.Bool> method. -Hence, there is a great difference between saying - - $x does Boolean; # a no-op, since $x already does Boolean - $x does Bool; # create a $.Bool attribute, also does Boolean - -Conditionals evaluate the truth of a boolean expression by testing -the return value of C<.Bool>; how they do this is a mystery, except -that they must do something mysterious and platform dependent to -avoid calling C<.Bool> recursively on the results of C<.Bool>. - -Never compare a value to "C<True>". Just use it -in a boolean context. Well, almost never... - -If you wish to be explicit about a boolean context, use the high-level -C<so> function or C<?> prefix operator, which are underlying based -on the C<.Bool> method. Since C<.Bool> always collapses junctions, -so do these functions. (Hence if you really need to autothread a -bunch of boolean values, you'll have to convert them to some other -type such as C<Bit> that can be used as a boolean value later. -Generally it makes no sense to autothread booleans, so we have a -policy of collapsing them sooner rather than later.) - -=head2 Miscellaneous Rules - -Like other type names and constant names, enum keynames are parsed as -standalone tokens representing scalar values, and don't look for any -arguments. Unlike type names but like constant names, enum keynames -return defined values. Also unlike types and unlike the enum type as a -whole, individual keynames do not respond to C<.()> unless you mix in -C<Callable> somehow. (That is, it makes no sense to coerce Wednesday -to Tuesday by saying C<Tue($wed)>.) Enumerations may not be post-declared. - - our enum Maybe <OK FAIL>; - sub OK is redefined {...} - $x = OK; # certainly the enum value - $x = OK() # certainly the function - -Since there is an enum C<OK>, the function C<OK> may only be -called using parentheses, never in list operator form. (If there is -a collision on two enum values that cancels them both, the function -still may only be called with parentheses, since the enum key -is "poisoned".) - -=head2 The C<.pick> Method - -Enumeration types (and perhaps certain other finite, enumerable types such -as finite ranges) define a C<.pick> method on the type object of -that type. Hence: - - my enum CoinFace <Heads Tails>; - CoinFace.pick - -returns C<Heads> or C<Tails> with equal probability, and - - Month.pick(*) - -will return the months in random order. Presumably - - StandardPlayingCards.pick(5) - -might return a Royal Flush, but a Full House is much -more likely. It can never return Five Aces, since the pick -is done without replacement. (If it I<does> return Five Aces, -it's time to walk away. Or maybe run.) - -To pick from the list of keynames or values, derive them via the -C<.enums> method described above. - -=head1 Open vs Closed Classes - -By default, all classes in Perl are non-final, which means -you can potentially derive from them. They are also open, which means -you can add more methods to them, though you have to be explicit that -that is what you're doing: - - augment class Mu { - method wow () { say "Wow, I'm in the Cosmic All." } - } - -Otherwise you'll get a class redefinition error. (Also, to completely -replace a definition, use "C<supersede>" instead of "C<augment>"...but -don't do that, since the compiler may have already committed to -optimizations based on the old definition.) - -In order to discourage casual misuse of these declarators, they are not -allowed on global classes unless you put a special declaration at the top: - - use MONKEY-TYPING; - -For optimization purposes, Perl 6 gives the top-level application the -right to close and finalize classes by the use of C<oo>, a pragma for -selecting global semantics of the underlying object-oriented engine: - - use oo :closed :final; - -This forces the optimizer to consider the current file to represent -the top-level application; however, the optimizer is also allowed to -assume these semantics when it can determine that it is linking an -entire application, such as when the current file is being run from -the command line or from a mouse click. - -These pragmatics (whether explicit or assumed) merely change the application's -default to closed and final, -which means that at the end of the main compilation (C<LINK> time) -the optimizer is allowed to look for candidate classes to close or -finalize. But anyone (including the main application) can request -that any class stay open or nonfinal, and the class closer/finalizer -must honor that. - - use class :open<Mammal Insect> :nonfinal<Str> - -These properties may also be specified on the class definition: - - class Mammal is open {...} - class Insect is open {...} - class Str is nonfinal {...} - -or by lexically scoped pragma around the class definition: - - { - use class :open; - class Mammal {...} - class Insect {...} - } - { - use class :nonfinal; - class Str {...} - } - -There is I<no> syntax for declaring individual classes closed or final. -The application may only request that the optimizer close and finalize -unmarked classes. - -=head1 Representations - -By default Perl 6 assumes that all objects have a representation -of C<P6opaque>. This may be overridden with a trait: - - class Mammal is repr(P6Hash) {...} - -Whether implicit or explicit, the representation is considered to be -fixed for the class after declaration, and the optimizer is free to -optimize based on this guarantee. It is illegal to create an object -of the same type with any other representation. If you wish to allow -objects to be created with run-time specified representations, you -must specifically pessimize the class: - - class Mammal is repr(*) {...} - -An C<augment> is allowed to do this as long as it is before the -main C<LINK> time, at which point the compiler commits to its -optimization strategies. Compilers are not required to support -run-time pessimizations (though they may). Compilers may also generate -both optimal and pessimal code paths and choose which to run based -on run-time information, as long as correct semantics are maintained. - -All non-native representations are required to support undefined type -objects that may contain unthrown exceptions (C<Failure> objects); -while this can be implemented using an alternate representation, -Perl 6 doesn't think of it that way. All normal objects in Perl 6 -may be used as a specific object (proper noun) if they are defined, -or as a generic object (common noun) whether or not they are defined. -You get this representation polymorphism for free independently of -the restriction above. - -=head1 Interface Consistency - -By default, all methods and submethods that do not declare an explicit -C<*%> parameter will get an implicit C<*%_> parameter declared for -them whether they like it or not. In other words, all methods allow -unexpected named arguments, so that C<nextsame> semantics work -consistently. - -If you mark a class "C<is hidden>", it hides the current class -from "C<nextsame>" semantics, and incidentally suppresses the -autogeneration of C<*%_> parameters. Methods on hidden classes may -still be called as C<$obj.NameOfHiddenClass::yourmethod>. - -A similar effect can be achieved from the derived class by saying -C<hides Base> instead of C<is Base>. - -=head1 Introspection - -Metamethods for objects are named with interrogative pronouns in uppercase: - - WHAT the type object of the type, .gist returns MyClass() - WHICH the object's identity value - WHO the package supporting the object, stringifies to long name - WHERE the memory address of the object - HOW the metaclass object: "Higher Order Workings" - WHEN (reserved for events?) - WHY the attached Pod value - WHENCE autovivification closure - -These may be used either as methods or as unary operators: - - $obj.WHAT # method form of P5's ref - WHAT $obj # unary form of P5's ref - -These should all be considered built-in language primitives, not -true operators or methods, even if a given implementation happens to -implement one or more of them that way. The optimizer reserves the -right to assume it knows what these names mean without user meddling. -Do not attempt to override or overload them, or bend them into twisty -little brain pretzels, except to fulfill those parts of the standard -interface that require you to do so. (Value types, for instance, -currently require a definition of WHICH. This too may change as -our notions of identity are refined.) - -If you get a foreign object from another language and need to call -its C<.WHERE> method, you can say: - - $obj."WHERE"() - -And if you don't know the method name in advance, you'd be using the -variable form anyway: - - $obj."$methodname"() - -or: - - $obj.$methodobject - -which also bypasses the macros. - -There is one more macro: - - DEFINITE the object has a valid concrete representation - -The C<DEFINITE> macro serves as the default for the C<Mu.defined> method. - -For now Perl 6 reserves the right to change how all these macros -and the corresponding C<^> forms are defined in terms of each other. -In particular, the C<.^> forms will automatically supply the invocant -as the first argument to methods of the metaclass, while the other -forms require you to pass this explicitly. - -Note that C<WHAT.gist> surrounds the name with parens to indicate undefinedness. -Use C<.perl> to get the bare name from a type object. Use one of -C<.Str>, C<.Stringy>, C<< prefix:<~> >>, or C<< infix:<~> >> to get the Perl5ish -semantics of returning the empty string (with a warning) on any type -object. (There is no "undef", in Perl 6; type objects provide typed -undefs instead.) - -In general, use of these uppercased accessors in ordinary code should -be a red flag that Something Very Strange is going on. (Hence the allcaps.) -Most code should use Perl 6's operators that make use of this information -implicitly. For instance, instead of - - $obj.WHAT === Dog - $x.WHICH === $y.WHICH - $obj.WHAT.bless(%args) - -you usually just want: - - $obj ~~ Dog - $x === $y - $obj.bless(%args) - -Every class has a C<HOW> function/method that lets you get at the -class's metaobject, which lets you get at all the metadata properties -for the class (or other metaobject protocol) implementing the objects -of the class: - - MyClass.methods() # call MyClass's .methods method (error?) - MyClass.HOW.methods($obj) # get the method list of MyClass - -The C<^> metasyntax is equivalent to C<.HOW>: - - MyClass.HOW.methods($obj) # get the method list of MyClass - MyClass.^methods() # get the method list of MyClass - -Each object of the class also has a C<.HOW> or C<.^> method: - - $obj.HOW.methods($obj); - $obj.^methods(); - -(If you are using prototype-based OO rather than class-based, you must use -the object form, since every such object functions as its own class.) - -Class traits may include: - - identifier { :name<Dog> :auth<http://www.some.com/~jrandom> :ver<1.2.1> } - name Dog - authority http://www.some.com/~jrandom - version v1.2.1 - author Joe Random - description This class implements camera obscura. - subject optics, boxes - language ja_JP - licensed Artistic|GPL - parents list of parent classes - roles list of roles - disambig how to deal with ambiguous method names from roles - repr P6opaque, P6hash, P5hash, P5array, PyDict, Cstruct, etc. - -These are for the standard Perl 6 Meta-Object Protocol, but other MOPs -may define other traits. The identifier should probably be accessed -through the C<.WHO> object in any case, which may have its own object -methods depending on how type namespaces evolve over time. Which of -these items are actually part of the C<.HOW> object and which are -delegated back to the package and prototype objects is up to the MOP. -(Note also that anonymous classes may have anonymous packages and -prototype objects, in which case stringification is not likely to -produce something of interest to non-gurus.) - -The C<.^parents> method by default returns a flattened list of all -parents out to (but not including) C<Cool> or C<Any>, -sorted in MRO (dispatch) order. Other options are: - - :local just returns the immediate parents - :local($n) return $n levels - :excl exclude Cool and Any (the default) - :all include Cool and Any - :tree the inheritance hierarchy as nested arrays - -The C<.^methods> method returns method-descriptors containing: - - name the name of the method - signature the parameters of the method - as the coercion type of the method - proto whether this method governs a set of multi methods - do the method body - -The C<.^methods> method has a selector parameter that lets you -specify whether you want to see a flattened or hierarchical view, -whether you're interested in private methods, and so forth. - - :local only methods defined in the current class - :local($n) out $n levels - :excl exclude Cool and Any (the default) - :all include Cool and Any - :tree methods by class structure (inheritance hierarchy) - :private include private methods - -Note that, since introspection is primarily for use by the outside -world (the class already knows its own structure, after all), a set of -C<multi> methods are presented to be a single C<proto> method. You need to -use C<.candidates> on that to break it down further. - -The C<.^attributes> method returns a list of C<Attribute> objects -that have methods like these: - - name - type - scope - rw - private - has-accessor - build - readonly - get_value($obj) - set_value($obj, $new_value) - -Note that an C<Attribute> is not tied to a particular object of a type, but -rather to the type itself. Which is why C<get_value> and C<set_value> need to -receive the actual object as first positional parameter. - -[Conjecture: if it's not feasible for a meta class or a representation to -implement C<set_value> and C<get_value>, it may die with an helpful error -message when these methods are called.] - -C<set_value> and C<get_value> violate the privacy of attributes, -and thus should be used with care, and at the user's own risk. - -C<.^attributes> also takes the parameters: - - :local only methods defined in the current class - :local($n) out $n levels - :excl exclude Cool and Any (the default) - :all include Cool and Any - :tree attributes by class structure (inheritance hierarchy) - -Strictly speaking, metamethods like C<.isa()>, C<.does()>, and C<.can()> -should be called through the meta object: - - $obj.HOW.can($obj, "bark") - $obj.HOW.does($obj, Dog) - $obj.HOW.isa($obj, Mammal) - -or - - $obj.^can("bark") - $obj.^does(Dog) - $obj.^isa(Mammal) - -But C<Any> gives you shortcuts to those: - - $obj.can("bark") - $obj.does(Dog) - $obj.isa(Mammal) - -These, may, of course, be overridden in a subclass, so don't use the -short form unless you wish to allow for overrides. In general, C<Any> -will delegate only those metamethods that read well when reasoning -about an individual object. Infrastructural methods like C<.^methods> -and C<.^attributes> are not delegated, so C<$obj.methods> fails. - -The smartmatch: - - $obj ~~ Dog - -actually calls: - - $obj.HOW.does($obj, Dog) - -which is true if C<$obj> either "does" or "isa" C<Dog> (or "isa" -something that "does" C<Dog>). If C<Dog> is a subset, any additional -C<where> constraints must also evaluate true. - -Unlike in Perl 5 where C<.can> returns a single C<Code> object, -Perl 6's version of C<.^can> returns a "WALK" iterator for a -set of routines that match the name, including all autoloaded and -wildcarded possibilities. In particular, C<.^can> interrogates -any class package's C<CANDO> method for names that are to be considered -autoloadable methods in the class, even if they haven't been declared yet. -Role composition sometimes relies on this ability to determine whether -a superclass supplies a method of a particular name if it's required -and hasn't been supplied by the class or one of its roles. - -The motivation for stopping at C<Cool> and C<Any> by default is that -the first derivation from one of those is really what the user thinks -of as the root class of the type hierarchy most of the time. Methods -outside of that are really part of Perl 6's lexicon, recognizable -across all types. Hence if you say, for example, C<$object.sort> -or C<$object.arctan>, you're invoking well-known cultural concepts -that tend to transcend the user's type hierarchy. When the user -asks for $object.^methods, listing such methods by default is -rather irritating. - -Note that when we say "C<Cool> and C<Any>" above, we really mean -those types as well as any types outside of them, such as C<Mu> or -C<Junction>. But users should not generally be deriving from those -types anyway. - -=head1 Custom Meta-objects - -[Note: This section is still subject to some changes, but does at least -reflect current implementation reality fairly well.] - -When the parser encounters a package declarator, it uses the name of -the declarator (such as C<class> or C<grammar>) to look up the type of -meta-object to use. The default meta-objects support the standard Perl 6 -OO semantics. However, it is possible for a module to export different -meta-objects with different semantics. This is done by declaring an -C<EXPORTHOW> package, which should be located in C<UNIT> of the module -(and thus can be lexically scoped). - -Just as the C<EXPORT> package never contains symbols directly, but instead -contains packages that denote tags and directives (such as C<DEFAULT>), the -C<EXPORTHOW> package expects meta-objects to be installed under one of the -following packages: - - SUPERSEDE Uses the exported meta-object for the named declarator in - the scope that the module is imported in to - COMPOSE Takes the meta-object currently in effect for the named - declarator and composes the exported role into it - DECLARE Like SUPERSEDE, but also adds a new package declarator to - the grammar if required - -For example, a module can replace the meta-object used for the C<grammar> -keyword in any scope it is imported into by doing: - - my module EXPORTHOW::SUPERSEDE { } - EXPORTHOW::SUPERSEDE<grammar> = TracedGrammarHOW; - -An MVC framework could declare a new C<controller> package declarator and -associate it with a meta-class of its choosing by doing: - - my module EXPORTHOW::DECLARE { } - EXPORTHOW::DECLARE<controller> = ControllerHOW; - -The C<COMPOSE> directive is perhaps the most sophisticated, and its usage is -encouraged where possible. Instead of exporting an entirely new meta-object, -C<COMPOSE> enables exporting a role. At the point the declarator is first used, -all roles exported for it through C<COMPOSE> will be taken together and added -to a class derived from the current meta-object for the declarator (which may -have been provided by a SUPERSEDE or DECLARE export from another module used in -the scope). This class will then be composed, with any conflicts indicated. - - my module EXPORTHOW::COMPOSE { - # Provide a role that adds logging to class method calls. - role class { - method find_method($obj, $name) { - say "Calling $name"; - nextsame; - } - - method publish_method_cache($obj) { - # Make sure all dispatches go through find_method - } - } - } - -The benefit of C<COMPOSE> is that it enables two modules that extend a meta-object -in a non-conflicting way to be used together in the same scope, with explicit -detection of conflicts if they occur. For example, if one module wishes to -override C<compose> and another wishes to override C<find_method>, the two can -be used together safely. By contrast, C<SUPERSEDE> and C<DECLARE> can only be used -by one module per declarator in a given scope, thwarting composition. The -compiler should produce an error if this rule is broken. - -The easiest way to define a new meta-object is to inherit from an existing -meta-object. - - my class TracedGrammarHOW is Metamodel::GrammarHOW { - } - -Here is a list of the various meta-objects that you may safely subclass and -the name they are installed under by default. - - Metamodel::ClassHOW class - Metamodel::EnumHOW enum - Metamodel::GrammarHOW grammar - Metamodel::ModuleHOW module - Metamodel::PackageHOW package - Metamodel::ParametricRoleHOW role - Metamodel::ParametricRoleGroupHOW role-group - Metamodel::SubsetHOW subset - -All of these meta-objects inherit from C<Any>. However, they will in turn -be implemented by other meta-objects that may or may not do so. This is -considered implementation specific, and implementations may re-arrange these -details freely between versions. Thus, relying on them is erroneous. - - SomeP6Class.HOW # Promises to (ultimately) inherit from Any - SomeP6Class.HOW.HOW # Implementation specific - -Roles are a little interesting, since they involve multiple meta-objects. -When you write: - - role Foo { - } - -Then a C<ParametricRoleHOW> is created to represent the role declaration. -It is in turn wrapped up inside a C<ParametricRoleGroupHOW>, which is then -installed under the name C<Foo>. This is because one short name may have -many long names due to signatured roles. - - role Foo[::T] { - } - -Sometimes, it may be interesting to customize meta-object behaviour on a -per-type basis. While this could be done by writing a custom meta-class and -arranging for it to be used, Perl 6 permits overriding specific meta-methods -on a per-type basis. For example, if the C<trusts> adverb was not flexible -enough and the class instead wanted to implement a more custom policy on -what other types it trusts, it could do something like: - - method ^is_trusted($obj, $do_we_trust_it) { - return $do_we_trust_it ~~ TheRoleOfTheTrustworthy; - } - -It's not necessary to override existing meta-methods either; this can be used -to attach whatever properties are desired to the meta-object for the type: - - method ^license($obj) { 'Artistic License' } - -Note that meta-methods generally need to take an argument that corresponds to -the object they are invoked on. This is because: - - $obj.^license - -Desugars to: - - $obj.HOW.license($obj) - -Meaning that implementing meta-methods providing prototype-like semantics are -possible. - -Methods declared with the C<^> modifier are handed to the meta-object by the -C<add_meta_method> method, rather than the usual C<add_method>. At compose -time of the class (usually, the closing C<}>), if there are any such per-type -meta-methods, a role will be generated containing the meta-methods, and this -will be mixed in to the meta-object. This means that this mechanism is only -useful for overriding meta-methods called after class composition. Therefore, -short of trying to restrict C<augment> operations in the future, it does not -make sense to write a C<method ^add_method(...) { ... }>. Such declarational -behaviour changes should be handled through the C<EXPORTHOW> approach. Any -meta-methods in a role will not have immediate effect, but will rather be -passed along to any class the role is composed into, and so take effect at -composition time of each class composing the role. - -=head1 Autovivifying objects - -The C<WHENCE> property of an object is its autovivifying closure. -Any undefined prototype object may carry such a closure that can -lazily create an object of the appropriate type. When the closure -is eventually evaluated it is expected to return an argument list -corresponding to the arguments to a C<.bless> call. For instance, -a C<CANDO> routine, instead of creating a C<Dog> object directly, -could instead return something like: - - Dog but WHENCE({ :name<Fido> }) - -which runs the closure if the object ever needs to be autovivified. -The closure can capture whatever initializers were available in the -original lexical scope. - -The short form of the above is simply: - - Dog{ :name<Fido> } - -This form is also lazily evaluated: - - my $dog = Dog{ :name<Fido> }; - defined $dog or say "doesn't exist"; # Fido doesn't exist - $dog.wag() # Fido wags his tail - -When the typename happens to be a role, autovivifying it involves -attempting to create a punned class of the same name as the role. -Whether this succeeds or not depends on whether the role is -sufficiently complete to serve as a class on its own. Regardless of -whether such an attempt would succeed, it is always perfectly fine to -define a lazy type object for a role just as long as it's only ever -used as an argument to C<bless>, since C<bless> will only be using -its closure to construct the role's C<BUILD> arguments in the context -of the complete new class. (Of course, an inconsistent or incomplete -class composition may subsequently fail, and in fact the incomplete -role autovivification mentioned above is likely to be implemented by -failing at the point of class composition.) - -Note that when used as an argument to a method like C<bless>, -the type object is sufficiently lazy that autovivifying is done -only by the appropriate C<BUILD> routine. It does not waste energy -creating a C<Dog> object when that object's attributes would later -have to be copied into the actual object. (On top of which, such -an implementation would make it impossible to use type objects to -initialize incomplete roles.) - -The object autovivification syntax works only for literal named types, -so any indirection must be written more explicitly: - - ::($dogproto){ :name<Fido> } - $dogproto but WHENCE({ :name<Fido> }) - $dogproto.WHAT{ :name<Fido> } - -Note that in contrast to this syntax, a lookup of a symbol in the C<Dog> -package requires a final C<::> before the subscript: - - Dog::{$varname} - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - -=for vim:set expandtab sw=4: diff --git a/S13-overloading.pod b/S13-overloading.pod deleted file mode 100644 index dff3efc4..00000000 --- a/S13-overloading.pod +++ /dev/null @@ -1,216 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 13: Overloading - -=head1 VERSION - - Created: 2 Nov 2004 - - Last Modified: 17 Jan 2012 - Version: 17 - -=head1 Overview - -This synopsis discusses those portions of Apocalypse 12 that ought to have -been in Apocalypse 13. - -=head1 Multiple dispatch - -The overloading mechanism of Perl 5 has been superseded by Perl 6's -multiple dispatch mechanism. Nearly all internal functions -are defined as C<multi> subs or C<multi> methods on generic types. -Built-in operators are merely oddly named functions with an alternate -call syntax. All you have to do to overload them is to define your -own C<multi> subs and methods that operate on arguments with more -specific types. - -For unary operators, this makes little effective difference, but for -binary operators, multiple dispatch fixes the Perl 5 problem of paying -attention only to the type of the left argument. Since both argument -types are used in deciding which routine to call, there is no longer -any trickery involving swapping the arguments to use the right argument's -type instead of the left one. And there's no longer any need to -examine a special flag to see if the arguments were reversed. - -For much more about multiple dispatch, see S12. - -=head1 Syntax - -There is no longer any special C<use overload> syntax separate from the -declarations of the C<multi> routines themselves. To overload an -existing built-in sub, say something like: - - multi sub uc (TurkishStr $s) {...} - -A C<multi> is automatically exported if governed by a proto that is exported. -It may also be explicitly exported: - - multi sub uc (TurkishStr $s) is export {...} - -Now if you call C<uc()> on any Turkish string, it will call your -function rather than the built-in one. - -If you import a multi into a UNIT scope, it is automatically re-exported. - -The types of the parameters are included in the I<longname> of any C<multi> -sub or method. So if you want to overload string concatenation for Arabic -strings so you can handle various ligatures, you can say: - - multi sub infix:<~>(ArabicStr $s1, ArabicStr $s2) {...} - multi sub infix:<~>(Str $s1, ArabicStr $s2) {...} - multi sub infix:<~>(ArabicStr $s1, Str $s2) {...} - -The C<use overload> syntax had one benefit over Perl 6's syntax in that -it was easy to alias several different operators to the same service -routine. This can easily be handled with Perl 6's aliasing: - - multi sub unimpl (MyFoo $x, MyFoo $y) { upchuck(); } - &infix:<+> ::= &unimpl; - &infix:<-> ::= &unimpl; - &infix:<*> ::= &unimpl; - &infix:</> ::= &unimpl; - -A C<multi> is in effect only within the scope in which it is defined or -imported. Generally you want to put your C<multi> subs into a package -that will be imported wherever they are needed. - -Conjectural: If the first parameter to a C<multi> signature is followed -by an invocant colon, that signature represents two signatures, one -for an ordinary method definition, and one for the corresponding C<multi> -definition that has a comma instead of the colon. This form is legal -only where the standard method definition would be legal, and only -if any declared type of the first parameter is consistent with C<$?CLASS>. - -=head1 Fallbacks - -Dispatch is based on a routine's signature declaration without regard -to whether the routine is defined yet. If an attempt is made to -dispatch to a declared but undefined routine, Perl will redispatch -to an C<AUTODEF> submethod [conjectural] as appropriate to define the routine. This provides -a run-time mechanism for fallbacks. By default, these declarations -are taken at face value and do not specify any underlying semantics. -As such, they're a "shallow" interpretation. - -[Note: the following section on "is deep" may no longer be necessary given -the way metaoperators are now constructed.] - -However, sometimes you want to specify a "deep" interpretation of -your operators. That is, you're specifying the abstract operation, -which may be used by various shallow operators. Any deep multi -declarations will be "amplified" into all the shallow operators that -can be logically based on it. If you say: - - multi sub infix:<%> (Us $us, Them $them) is deep { mymod($us,$them) } - -then - - multi sub infix:<%=> (Us $us, Them $them) { $us = $us % $them } - -is also generated for you (unless you define it yourself). -The mappings of magical names to sub definitions is controlled by the -C<%?DEEPMAGIC> compiler hash. Pragmas can influence the contents of -this hash over a lexical scope, so you could have different policies -on magical autogeneration. The default mappings correspond to the -standard fallback mappings of Perl 5 overloading. - -These deep mappings are mainly intended for infix operators that would have -difficulty naming all their variants. Prefix operators tend to be simpler; -note in particular that - - multi prefix:<~> is deep {...} - -is better written: - - method Stringy {...} - -(see below). - -=head1 Type Casting - -A class may define methods that allow it to respond as if it were a -routine, array, or hash. The long forms are as follows: - - method postcircumfix:<( )> (|capture) {...} - method postcircumfix:<[ ]> (**@slice) {...} - method postcircumfix:<{ }> (**@slice) {...} - -Those are a bit unwieldy, so you may also use these short forms: - - method &.( |capture ) {...} - method @.[ **@slice ] {...} - method %.{ **@slice } {...} - -The sigil-dot sequence in these short forms autogenerates the -corresponding public operators, in exactly the same way that -the sigil-dot in: - - has $.action; - has @.sequence; - has %.mapping; - -autogenerates public accessor methods. - -And because it uses the same method-autogeneration mechanism, the -specific sigil used to specify a short-form postcircumfix operator -doesn't actually matter...as long as it's followed by a dot and the -bracket pair containing the signature. (Though it's probably kinder -to future readers of your code to stick with the "natural" sigil -for each type of bracket.) - -Note that the angle bracket subscripting form C<< .<a b c> >> -automatically translates itself into a call to C< .{'a','b','c'} >, -so defining methods for angles is basically useless. - -The expected semantics of C<&.()> is that of a type -on which may -or may not create a new object. So if you say: - - $fido = Dog.new($spot) - -it certainly creates a new C<Dog> object. But if you say: - - $fido = Dog($spot) - -it might call C<Dog.new>, or it might pull a C<Dog> with Spot's -identity from the dog cache, or it might do absolutely nothing if -C<$spot> already knows how to be a C<Dog>. As a fallback, if no -method responds to a coercion request, the class will be asked to attempt to -do C<Dog.new($spot)> instead. - -It is also possible (and often preferable) to specify coercions from -the other end, that is, for a class to specify how to coerce one of -its values to some other class. So, if you define a method whose name -happens to be type name, you can view it as a coercion to that type. But that method -is a regular method even its name happens to be a type name. That means the -compiler does not enforce the type of the returned value. - - method Str { self.makestringval() } - -As with all methods, you can also export the corresponding C<multi>: - - multi method Str is export { self.makestringval() } - -in which case you can use both calling forms: - - $x.Str - Str($x) - -If the source class and the destination class both specify a -coercion routine, the ambiguity is settled by the ordinary rules -of dispatch. That is, C<$x.Str> will always prefer the method form -and C<Str($x)> will always prefer the functional form. - -Note that, because the name of an anonymous class is unknown, coercion to -an anonymous class can only be specified by the destination class: - - $someclass = generate_class(); - $someclass($x); - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - -=for vim:set expandtab sw=4: diff --git a/S14-roles-and-parametric-types.pod b/S14-roles-and-parametric-types.pod deleted file mode 100644 index 551eabc4..00000000 --- a/S14-roles-and-parametric-types.pod +++ /dev/null @@ -1,611 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 14: Roles and Parametric Types [DRAFT] - -=head1 VERSION - - Created: 24 Feb 2009 (extracted from S12-objects.pod) - - Last Modified: 24 Nov 2012 - Version: 11 - -=head1 Overview - -This synopsis discusses roles and parametric types, which were -originally discussed in A12. - -=head1 Roles - -Classes are primarily in charge of object management, and only -secondarily in charge of software reuse. In Perl 6, roles take over -the job of managing software reuse. Depending on how you care to look -at it, a role is like a partial class, or an interface with default -implementation, or a set of generic methods and their associated data, -or a class closed at compile time. - -Roles may be composed into a class at compile time, in which case -you get automatic detection of conflicting methods. A role may also -be mixed into a class or object at run time to produce an anonymous -derived class with extra capabilities, but in this case conflicting -methods are overridden by the new role silently. In either case, -a class is necessary for instantiation--a role may not be directly -instantiated. - -A role is declared like a class, but with a C<role> keyword: - - role Pet { - method feed ($food) { - $food.open_can; - $food.put_in_bowl; - self.eat($food); - } - } - -A role may not inherit from a class, but may be composed of other -roles. However, this "crony" composition is not evaluated until -class composition time. This means that if two roles bring in the -same crony, there's no conflict--it's just as if the class pulled in -the crony role itself and the respective roles didn't. A role may -never conflict with itself regardless of its method of incorporation. -A role that brings in two conflicting crony roles I<may> resolve them -as if it were a class. This solution is accepted by the class unless -the class supplies its own solution. If two different roles resolve -the same crony conflict two different ways, those roles are themselves -in conflict and must be resolved by a "more derived" role or the class. - -A role doesn't know its own type until it is composed into a class. -Any mention of its main type (such as C<::?CLASS>) is generic, as is -any reference to C<self> or the type of the invocant. You can use -a role name as a type, but only for constraints, not for declaring -actual objects. (However, if you use a role as if it were a class, -an anonymous class is generated that composes the role, which provides -a way to force a role to test its crony composition for infelicities.) - -If a role merely declares methods without defining them, it degenerates -to an interface: - - role Pet { - method feed ($food) {...} - method groom () {...} - method scratch (:$where) {...} - } - -Note that, while these methods must become available at class -composition time, they might be supplied by any of: another role, -the class itself, or some superclass. We know the methods that are -coming from the other roles or the class, but we don't necessarily know -the complete set of methods supplied by our super classes if they are -open or rely on wildcard delegation. However, the class composer is -allowed to assume that only currently declared superclass methods or -non-wildcard methods are going to be available. A stub can always -be installed somewhere to "supply" a missing method's declaration. - -Roles may have attributes: - - role Pet { - has $.collar = Collar.new(tag => Tag.new); - method id () { return $.collar.tag } - method lose_collar () { undefine $.collar } - } - -Within a role the C<has> declarator always indicates the declaration -from the viewpoint of the class. Therefore a private attribute declared -using C<has> is private to the class, not to the role. You may wish to -declare an attribute that is hidden even from the class; a completely -private role attribute (that will exist per instance of the class) may -be declared like this: - - my $!spleen; - -The name of such a private attribute is always considered lexically scoped. -If a role declares private lexical items, those items are private to -the role due to the nature of lexical scoping. Accessors to such -items may be exported to the class, but this is not the default. -In particular, a role may say - - trusts ::?Class; - -to allow C<self!attr()> access to the role's C<$!attr> variables with the -class or from other roles composed into the class. Conflicts between -private accessors are also caught at composition time, but of course -need not consider super classes, since no-one outside the current -class (or a trusted class) can call a private accessor at all. -(Private accessors are never virtual, and must be package qualified -if called from a trusted scope other than our own. That is, it's -either C<self!attr()> or C<$obj!TrustsMe::attr().>) - -A role may also distinguish a shared method - - has method foo ... - method foo ... # same - -from a nonshared private method: - - my method !foo ... - my method foo ... # same, but &foo is aliased to &!foo - -Generally you'd just use a lexically scoped sub, though. - - my sub foo ... - -A role can abstract the decision to delegate: - - role Pet { - has $groomer handles <bathe groom trim> = hire_groomer(); - } - -Note that this puts the three methods into the class as well as -C<$groomer>. In contrast, "C<my $!groomer>" would only put the -three methods; the attribute itself is private to the role. - -A role is allowed to declare an additional inheritance for its class when -that is considered an implementation detail: - - role Pet { - also is Friend; - } - -=head2 Compile-time Composition - -A class incorporates a role with the verb "does", like this: - - class Dog is Mammal does Pet does Sentry {...} - -or equivalently, within the body of the class closure: - - class Dog { - also is Mammal; - also does Pet; - also does Sentry; - ... - } - -or - - class Dog { - also is Mammal does Pet does Sentry; - ... - } - -There is no ordering dependency among the roles. - -A class's explicit method definition hides any role definition of -the same name. A role method in turn hides any methods inherited -from other classes. - -If there are no method name conflicts between roles (or with the -class), then each role's methods can be installed in the class. If, -however, two roles try to introduce a method of the same name the -composition of the class fails. (Two C<has> attributes of the same -name, whether public or private, are always a composition fail. -Role-private attributes are exempt from this, and from the viewpoint of -the composition, don't even exist, except to allocate a slot for each -such attribute.) - -There are several ways to solve method conflicts. The first is simply to -write a class method that overrides the conflicting role methods, perhaps -figuring out which role method to call. - -Alternately, if the role's methods are declared C<multi>, they can be -disambiguated based on their long name. If the roles forget to declare -them as multi, you can force a multi on the roles' methods by installing -a proto stub in the class being constructed: - - proto method shake {...} - -(This declaration need not precede the C<does> clause textually, since -roles are not actually composed until the end of the class definition, -at which point we know which roles are to be composed together -in a single logical operation, as well as how the class intends to -override the roles.) - -The proto method will be called if the multi fails: - - proto method shake { warn "They couldn't decide" } - -=head2 Run-time Mixins - -Run-time mixins are done with C<does> and C<but>. The C<does> binary -operator is a mutator that derives a new anonymous class (if necessary) -and binds the object to it: - - $fido does Sentry - -The C<does> infix operator is non-associative, so this is a syntax error: - - $fido does Sentry does Tricks does TailChasing does Scratch; - -You can, however, say - - $fido does Sentry; - $fido does Tricks; - $fido does TailChasing; - $fido does Scratch; - -And since it returns the left side, you can also say: - - ((($fido does Sentry) does Tricks) does TailChasing) does Scratch; - -Unlike the compile-time role composition, each of these layers on a new -mixin with a new level of inheritance, creating a new anonymous class -for dear old Fido, so that a C<.chase> method from C<TailChasing> hides a -C<.chase> method from C<Sentry>. - -You can also mixin a precomposed set of roles: - - $fido does (Sentry, Tricks, TailChasing, Scratch); - -This will level the playing field for collisions among the new -set of roles, and guarantees the creation of no more than one more -anonymous class. Such a role still can't conflict with itself, but it -can hide its previous methods in the parent class, and the calculation -of what conflicts is done again for the set of roles being mixed in. -If you can't do compile-time composition, we strongly recommend this -approach for run-time mixins since it approximates a compile-time -composition at least for the new roles involved. - -A role applied with C<does> may be parameterized with an initializer -in parentheses, but only if the role supplies exactly one attribute -to the mixin class: - - $fido does Wag($tail); - $line does taint($istainted); - -Note that the parenthesized form is I<not> a subroutine or method call. -It's just special initializing syntax for roles that contain a single -property. - -The supplied initializer will be coerced to the type of the attribute. -Note that this initializer is in addition to any parametric type -supplied in square brackets, which is considered part of the actual -type name: - - $myobj does Array[Int](@initial) - -A property is defined by a role like this: - - role answer { - has Int $.answer is rw = 1; - } - -The property can then be mixed in or, alternatively, applied using the -C<but> operator. C<but> is like C<does>, but creates a copy and mixes into -that instead, leaving the original unmodified. Thus: - - $a = 0 but answer(42) - -Really means something like: - - $a = ($anonymous = 0) does answer(42); - -Which really means: - - (($anonymous = 0) does answer).answer = 42; - $a = $anonymous; - -Which is why there's a C<but> operator. - -If you put something that is not a role on the right hand side of the -C<does> or C<but> operators then an anonymous role will be auto-generated -containing a single method that returns that value. The name of the method -is determined by doing .WHAT.perl on the value supplied on the RHS. The -generated role is then mixed in to the object. For example: - - $x does 42 - -Is equivalent to: - - $x does role { method Int() { return 42 } } - -Note that the role has no attributes and thus no storage; if you want that, -then you should instead use: - - $x does Int(42) - -Which mixes in the Int role and initializes the single storage location Int -that it declares with 42, and provides an lvalue accessor. - -Note that .WHAT on an enumeration value stringifies to the name of the -enumeration, and as a result: - - 0 but True - -Is equivalent to: - - 0 but role { method Bool() { return True } } - -And thus the resulting value will be considered true in boolean context. - -The list syntax for composing multiple roles in a single C<does> or C<but> -by putting them in a list also applies here. Thus: - - 42 but ("the answer", False) - -Is equivalent to: - - 42 but (role { method Str() { return "the answer" } }, - role { method Bool() { return False } }) - -Which gives you a compact way to build context-sensitive return values. -Note that multiple roles rather than a single one are generated, so that -anything like: - - 42 but (True, False) - -Will fail as a result of standard role composition semantics (because two -roles are both trying to provide a method Bool). - -=head1 Traits - -Traits are just properties (roles) applied to something that is being declared (the I<declarand>), -such as containers or classes. It's the declaration of the item itself that -makes traits seem more permanent than ordinary properties. In addition -to adding the property, a trait can also have side effects. - -Traits are generally applied with the "is" keyword, though not always. -To define a trait handler for an "is xxx" trait, define one or -more multisubs into a property role like this: - - role xxx { - has Int $.xxx; - multi trait_mod:<is>(::?CLASS:U $declarand, :$xxx!) {...} - multi trait_mod:<is>(Any $declarand, :$xxx!) {...} - } - -Then it can function as a trait. A well-behaved trait handler will say - - $declarand does xxx($arg); - -somewhere inside to set the metadata on the declarand correctly. -Since a class can function as a role when it comes to parameter type -matching, you can also say: - - class MyBase { - multi trait_mod:<is>(MyBase:U $declarand, MyBase $base) {...} - multi trait_mod:<is>(Any $declarand, MyBase $tied) {...} - } - -These capture control if C<MyBase> wants to capture control of how it gets -used by any class or container. But usually you can just let it call -the generic defaults: - - multi trait_mod:<is>(Any:U $declarand, $base) {...} - -which adds C<$base> to the "isa" list of class C<$declarand>, or - - multi trait_mod:<is>(Any $declarand, $tied) {...} - -which sets the "tie" type of the container declarand to the implementation type -in C<$tied>. - -Most traits are really just adverbial pairs which, instead of being -introduced by a colon, are introduced by a (hopefully) more readable -"helping verb", which could be something like "C<is>", or "C<will>", or -"C<can>", or "C<might>", or "C<should>", or "C<does>". Any trait verb -that is parsed the same as trait_mod:<is> may be defined the same way. -Here's "C<will>", which (being syntactic sugar) merely delegates to -back to "is": - - multi sub trait_mod:<will>($declarand, :$trait) { - trait_mod:<is>($declarand, :$trait); - } - -Other traits are applied with a single word, and require special -parsing. For instance, the "C<of>" trait is defined something -like this: - - role of { - has ReturnType $.of; - multi sub trait_mod:<of>($declarand, ReturnType $arg) is parsed /<typename>/ { - $declarand does of($arg); - } - ... - } - -Unlike compile-time roles, which all flatten out in the same class, -compile-time traits are applied one at a time, like mixin roles. -You can, in fact, apply a trait to an object at run time, but -if you do, it's just an ordinary mixin role. You have to call the -appropriate C<trait_mod:<is>()> routine yourself if you want it to -do any extra shenanigans. The compiler won't call it for you at run -time like it would at compile time. - -Note that the declarations above are insufficient to install new trait -auxiliaries or verbs into the user's grammar, since macro definitions -are lexically scoped, and in the declarations above extend only to -the end of the role definition. The user's lexical scope must somehow -have processed (or imported) a proto declaration introducing the new -syntax before it can be parsed correctly. (This doesn't apply to -pre-existing syntax such as C<is>, of course.) - -Calls to C<trait_mod> routines are evaluated in sink context. - -=head1 Parametric Roles - -A role's main type is generic by default, but you can also parameterize -other types explicitly using type parameters: - - role Pet[::Petfood = TableScraps] { - method feed (Petfood $food) {...} - } - -(Note that in this case you must not use ::Petfood in the inner declaration, -or it would rebind the type to type of the actual food parameter.) - -If you want to parameterize the initial value of a role attribute, -be sure to put a double semicolon if you don't want the parameter to -be considered part of the long name: - - role Pet[::ID;; $tag] { - has ID $.collar .= new($tag); - } - -You don't just have to parameterize on types; any value is fine. Imagine -we wanted to factor out a "greet" method into a role, which takes -somebody's name and greets them. We can parameterize it on the greeting. - - role Greet[Str $greeting] { - method greet() { say "$greeting!"; } - } - class EnglishMan does Greet["Hello"] { } - class Slovak does Greet["Ahoj"] { } - class Lolcat does Greet["OH HAI"] { } - EnglishMan.new.greet(); # Hello - Slovak.new.greet(); # Ahoj - Lolcat.new.greet(); # OH HAI - -Similarly, we could do a role for requests. - - role Request[Str $statement] { - method request($object) { say "$statement $object?"; } - } - class EnglishMan does Request["Please can I have a"] { } - class Slovak does Request["Prosim si"] { } - class Lolcat does Request["I CAN HAZ"] { } - EnglishMan.new.request("yorkshire pudding"); - Slovak.new.request("borovicka"); - Lolcat.new.request("CHEEZEBURGER"); - -Sadly, the Slovak output sucks here. Borovicka is the nominative form -of the word, and we need to decline it into the accusative case. But -some languages don't care about that, and we don't want to have to make -them all supply a transform. Thankfully, you can write many roles with -the same short name, and a different signature, and multi-dispatch will -pick the right one for you (it is the exact same dispatch algorithm used -by multi-subs). So we can write: - - role Request[Str $statement] { - method request($object) { say "$statement $object?"; } - } - role Request[Str $statement, &transform] { - method request($object) { - say "$statement " ~ transform($object) ~ "?"; - } - } - module Language::Slovak { - sub accusative($nom) { - # ...and before some smartass points it out, I know - # I'm missing some of the masculine animate declension... - return $nom.subst(/a$/, 'u'); - } - } - class EnglishMan does Request["Please can I have a"] { } - class Slovak does Request["Prosim si", &Language::Slovak::accusative] { } - class Lolcat does Request["I CAN HAZ"] { } - EnglishMan.new.request("yorkshire pudding"); - Slovak.new.request("borovicka"); - Lolcat.new.request("CHEEZEBURGER"); - -Which means we can now properly order our borovicka in Slovakia, which -is awesome. Until you do it in a loop and find the Headache['very bad'] -role got mixed into yourself overnight, anyway... - -=head2 Relationship Between of And Types - -The of keyword is just syntactic sugar for providing a single -parameter to a parametric type. Thus: - - my Array of Recipe %book; - -Actually means: - - my Array[Recipe] %book; - -This can be nested, so: - - my Hash of Array of Recipe @library; - -Is just: - - my Hash[Array[Recipe]] @library; - -Therefore: - - my Array @array; - -Means an Array of Array (actually, a Positional of Array). - -=head2 Parametric Subtyping - -If you have two types in a subtyping relationship such that T1 is -narrower than T2, then also the roles: - - role R[::T] { } - role R[::T1, ::T2] { } - -Will act such that R[T1] is narrower than R[T2]. This extends to multiple -parameters, however they must all be narrower or the same (this is unlike -in multiple dispatch where you can have one narrower and the rest narrower -or tied). That is, assuming we have some unrelated type T3, then R[T2, T1] -is narrower than R[T1,T1] but R[T2,T1] is not narrower than R[T1,T3]. - -Nesting follows naturally from this definition, so a role R[R[T2]] is -narrower than a role R[R[T1]]. - -This all means that, for example, if you have a sub: - - sub f(Num @arr) { ... } - -Then you can also call it with an array of Int. - - my Int @a = 1,2,3; - f(@a); - -=head2 The structure of role types and packages - -When a role is declared: - - role Foo { } - -Then the symbol `Foo` that gets installed in the enclosing package represents -a potential group of roles that will be disambiguated by arguments. A later -declaration: - - role Foo[::T] { } - -Adds to the existing group. The C<::?PACKAGE> inside of each of these is -therefore something different from Foo itself. The group's meta-object type -is C<ParametricRoleGroupHOW>, while C<ParametricRoleHOW> is the meta-object -type for individual parametric roles. - -Writing C<Foo[Int]> is not sufficient to concretize a role, because that -needs the target class; therefore this returns a type with the meta-object -C<CurriedRoleHOW> that will pass along the extra type parameters at the -point of composition, to aid selection of the correct parametric variant. -Therefore, it does not address a particular C<ParametricRoleHOW>. - -Normal users of Perl 6 will have to care little for these details. However, -given that any C<our> scoped symbol declared inside of a role body will end -up in a package that is simply unaddressable without digging into the -meta-objects, C<our> declarations in a role are forbidden. This does not -prevent installation directly into C<::?PACKAGE.WHO>, for expert users who -want the escape hatch. It simply means syntactic C<our> declarations will be -forbidden to avoid the inevitable confusion that will result from trying to -access them. - -=head2 Interaction of typed and untyped data structures - -Certainly so far as Perl 6.0.0 goes, only types that have been declared -on a container count in the type check. That is, if we have a sub: - - sub f(Int @arr) { ... } - -And call it with any of: - - f([1,2,3]); - my @a = 1,2,3; - f(@a); - -Then neither of these calls will work. The type check is based on the -declared type of the array, and the content is unknown to the type -checker. - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - Tim Nelson <wayland@wayland.id.au> - Jonathan Worthington <jnthn@jnthn.net> - -=for vim:set expandtab sw=4: diff --git a/S15-unicode.pod b/S15-unicode.pod deleted file mode 100644 index d9a3cda5..00000000 --- a/S15-unicode.pod +++ /dev/null @@ -1,736 +0,0 @@ -=comment Oh, this is in Pod6 format. Just so you know. - -=begin pod - -=TITLE Synopsis 15: Unicode [DRAFT] - -=VERSION -=for table - Created 2 December 2013 - Last Modified 10 October 2014 - Version 8 - -This document describes how Unicode and Perl 6 work together. Needless to say, -it would be good for your chosen reader to support various Unicode characters. - -=head1 String Base Units - -A Unicode string can be looked at in any of four ways. It could be seen in terms -of its graphemes, its codepoints, its encoding's code units, or the bytes that -make up the encoding. - -For example, consider a string containing the Devanagari syllable नि, which is -comprised of the codepoints - - U+0928 DEVANAGARI LETTER NA - U+093F DEVANAGARI VOWEL SIGN I - -There are a variety of ways in which to perceive the length of this string. For -reference, here is how the syllable gets encoded in each of UTF-8, UTF-16BE, and -UTF-32BE. - -=for table - UTF-8 E0 A4 A8 E0 A4 BF - UTF-16BE 0928 093F - UTF-32BE 00000928 0000093F - -And depending on if you desire to count by graphemes, codepoints, code units, or -bytes, the perceived length of the string differs: - -=for table - |------------+-------+--------+--------| - | count by | UTF-8 | UTF-16 | UTF-32 | - |============+=======+========+========| - | bytes | 6 | 4 | 8 | - | code units | 6 | 2 | 2 | - | codepoints | 2 | 2 | 2 | - | graphemes | 1 | 1 | 1 | - |------------+-------+--------+--------| - -Perl 6 offers various mechanisms to count by each of these "base units" of a -string. - -Perl 6 by default operates on graphemes, so counting by graphemes involves: - - "string".chars - -To count by codepoints, conversion of a string to one of NFC, NFD, NFKC, or NFKD -is needed: - - "string".NFC.codes - "string".NFKD.codes - -To count by code units, you can convert to the appropriate buffer type. - - "string".encode("UTF-32LE").elems - "string".encode("utf-8").elems - -And finally, counting by bytes simply involves converting that buffer to a -C<buf8> object: - - "string".encode("UTF-16BE").buf8.elems - -Note that C<utf8> already stores by bytes, so the count for bytes and code units -is always the same. - -=head1 Normalization Forms - -=head2 NFG - -Perl 6, by default, stores all strings given to it in NFG form, Normalization -Form Grapheme. It's a Perl 6–invented character representation, designed to deal -with un-precomposed graphemes properly. - -Formally Perl 6 graphemes are defined exactly according to Unicode Grapheme Cluster Boundaries -at level "extended" (in contrast to "tailored" or "legacy"), -see Unicode Standard Annex #29 UNICODE TEXT SEGMENTATION -L<3 Grapheme Cluster Boundaries|http://www.unicode.org/reports/tr29/tr29-25.html#Grapheme_Cluster_Boundaries>>. -This is the same as the Perl 5 character class - - \X Match Unicode "eXtended grapheme cluster" - -With NFG, strings start by being run through the normal NFC process, compressing -any given character sequences into precomposed characters. - -Any graphemes remaining without precomposed characters, such as ậ or नि, are -given their own internal designation to refer to them, at least 32 bits in -length, in such a way that they avoid clashing with any potential future -changes to Unicode. The mapping between these internal designations and -graphemes in this form is not guaranteed constant, even between strings in -the same process. - -The Perl 6 C<Str> type, and more generally the C<Stringy> role, deals -exclusively in NFG form. - -=head2 NFC and NFD - -The NFC and NFD normalization forms are a defined part of the Unicode -standard. NFD takes precomposed characters and separates them into their -constituent parts, with a specific ordering of those pieces. NFC tries to -replace characters sequences into singular precomposed characters whenever -possible, after first running it through the NFD process. - -These two Normalization Forms are similar to NFG, except that graphemes without -precomposed versions exist as multiple codepoints. - -NFC is the form Perl 6 uses whenever NFG is not viable, such as printing the -string to stdout or passing it to a C<{ use v5; }> section. - -=head2 NFKC and NFKD - -These forms are known as compatibility forms (denoted by a K to avoid confusion -with C for Composition). They are similar to their canonical counterparts, but -may transform various characters (such as fi or ſ) to perform better with the -software. - -All four of NFC, NFD, NFKC, and NFKD can be considered valid "codepoint views", -though each differ in their exact formulation of the contents of a string: - - say "ẛ̣".codes; # OUTPUT: 2 (NFG, ẛ̣) - say "ẛ̣".NFC.codes; # OUTPUT: 2 (NFC, ẛ + ̣) - say "ẛ̣".NFD.codes; # OUTPUT: 3 (NFD, ſ + ̣+ ̇) - say "ẛ̣".NFKC.codes; # OUTPUT: 1 (NFKC, ṩ) - say "ẛ̣".NFKD.codes; # OUTPUT: 3 (NFKD, s + ̣+ ̇) - -Those who wish to operate with strings on the codepoint level may wish to use -NFC, as it is the least different from NFG, as well as Perl 6's default form for -NFG-less contexts. - -All of C<Uni>, C<NFC>, C<NFD>, C<NFKC>, and C<NFKD>, and more generally the -C<Unicodey> role, deal with the various codepoint-based compositions. - -=head1 The C<Str> Type - -Presented are the variety of methods of C<Str> which are related to -Unicode. C<Str> deals exclusively in the NFG form of Unicode strings. - -=head2 String to Numeral Conversion - - Str.ord - Str.ords - ord(Str $string) - ords(Str $string) - -These give you the numeric values of the B<base character> of graphemes in a -string. C<ord> only works on the first graphemes, while C<ords> works on every -grapheme. - -=head2 Length Methods - - Str.chars - -These methods are equivalent, and count the number of graphemes in your string. - -[Should there be methods that implicitly convert to the other string types, or -would .NFKD.chars be necessary?] - -=head2 Buf conversion - - Str.encode($enc = "utf-8") - -Encodes the contents of the string by the specified encoding (by default UTF-8) -and generates the appropriate C<blob>. - -Note that if you convert to one of the UTFs, you'll get a UTF-aware version of -the C<blob>. (Non-Unicode encodings will go for the most appropriate C<blob> -type.) - -UTF-16 and UTF-32 default to big endian if you don't specify endianness. - - Str.encode --> utf8 - Str.encode("UTF-16") --> utf16 (big endian) - Str.encode("UTF-32LE") --> utf32 (little endian) - Str.encode("ASCII") --> blob8 - -=head1 The C<NF*> Types - -Perl 6 has four types corresponding to a specific Unicode Standard Normalization -Form: C<NFC>, C<NFD>, C<NFKC>, and C<NFKD>. - -Each one of these types perform normalization on strings stored in it. - -The C<NF*> types do the C<Unicodey> role. - -=head1 The C<Uni> Type - -The C<Uni> type is like the various C<NF*> types, but allows a mixed collection -of normalization forms to make up the string. - -The C<Uni> type does the C<Unicodey> role. - -=head1 The C<Unicodey> Role - -The C<Unicodey> role deals in various Unicode-aware functions. - -=head2 Length Methods - - Unicodey.chars - Unicodey.codes - -Both are synonymous. Counts the number of codepoints in a C<Unicodey> type. - -[Maybe C<Unicodey does Stringy> ?] - -=head1 The C<Stringy> Role - -The C<Stringy> role deals with a more general, not necessarily Unicode-based -view of strings. C<Str> uses this because it doesn't always play by the Unicode -Standards' rules (most notably the use of NFG). - -=head1 C<Buf> methods - -=head2 Decoding buffers - - Buf.decode($dec = "utf-8"); - -Transforms the buffer into a C<Str>. Defaults to assuming a "utf-8" -encoding. Encoding-aware buffers have a different default decoding, for -instance: - - utf8.decode($dec = "utf-8"); - utf16.decode($dec = "utf-16be"); - utf32.decode($dec = "utf-32be"); - -[It would be best if utf16 and utf32 changed its default between BE and LE at -creation, either because of what Str.encode said or, if the utf16/32 was -manually created, analyzing the BOM, if any. Just know that Unicode itself -defaults to BE if nothing else.] - -=head1 String Type Conversions - -If you desire to have a string in one of the other Normalization Forms, there -are various conversion methods to do this. - - Cool.Str - Cool.NFG [ XXX this is purely a synonym to .Str. Necessary? ] - Cool.NFC - Cool.NFD - Cool.NFKC - Cool.NFKD - Cool.Uni - -Notably, conversion to the C<Uni> type will assume NFC for either NFG strings or -non-strings being converted to this string-like type. Otherwise it's a -transposition of the string without changes in normalization. - -=head1 Unicode Information - -There's plenty of information each Unicode codepoint possesses, and Perl 6 -provides various ways of accessing that information. - -Unless plural forms of these functions are provided, each function operates only -on the first codepoint of the string. Various array-based operations would be -needed to gain information on every character in the string. - -[Note: The properties of graphemes are not defined by Unicode, but to inherit -the properties from the first NFC codepoint in the grapheme should make sense -in most cases, but not for e.g. charnames. Or are they not supported at NFG?] - -[Note: If adding additional methods to access Unicode information, priority -should be placed on info that can't be accessed as a Unicode property.] - -=head2 Property Lookup - - uniprop(Int $codepoint, Stringy $property) - Int.uniprop(Str $property) - - uniprop(Unicodey $char, Stringy $property) - Unicodey.uniprop(Stringy $property) - - uniprops(Unicodey $str, Stringy $property) - Unicodey.uniprops(String $property) - -This function returns the value of C<$property> for the given C<$codepoint> or -C<$char>, or an array of values of the property of each character in C<$str> . - -All official spellings of a property name are supported. - - uniprops("a", "ASCII_Hex_Digit") # is this character an ASCII hex digit? - uniprops("a", "AHex") # ditto - -Values returned for properties may be the narrowest possible type for numeric -(widest C<Rat>), and C<Str> objects. -Boolean properties are returned True or False as a Bool. -Note there is no version of C<uniprops> for integers, while there is one for -strings. To achieve the same thing, use normal array operations: - - my @isws = (32,42,43)».uniprop("White_Space"); - -Note that the integer-based lookup is the fundamental version; the string-based -versions are convenience functions. These two are nearly equivalent: - - uniprop("0".ord, "Numeric_Value"); # integer lookup - uniprop("0", "Numeric_Value"); # stringy lookup - -However, the string-based version will convert NFG strings to NFC before sending -either the first or all characters through the lookup. This is because Unicode -property lookup is considered an NFG-less environment (see L<NFC and NFD|#NFC -and NFD>). - -Integer-based lookup should die on negative integers, or integers greater than -C<0x10_FFFF>. - -[Conjecture: would versions of uniprop with a slurpy instead of a single string -property be useful? Or is C<uniprop(0x20, $_) for @props> good enough?] - -=head3 Binary Property Lookup - - unibool(Int $codepoint, Stringy $property) - Int.unibool(Str $property) - - unibool(Unicodey $char, Stringy $property) - Unicodey.unibool(Stringy $property) - - unibools(Unicodey $str, Stringy $property) - Unicodey.unibools(String $property) - -Looks up a boolean Unicode property (such as C<Case_Ignorable>) and returns a -boolean. Throws an error on non-boolean properties. - - unibool(0x41, "Case_Ignorable"); # OK - unibool(0x41, "General_Category"); # dies - -As with C<uniprop>, the string version converts NFG strings to NFC, but -otherwise is equivalent to feeding the result of C<.ord> through the base -integer version. - -=head3 Binary Category Check - - unimatch(Int $codepoint, Stringy $category) - Int.unimatch(Str $category) - - unimatch(Unicodey $char, Stringy $category) - Unicodey.unimatch(Stringy $category) - - unimatches(Unicodey $str, Stringy $category) - Unicodey.unimatches(String $category) - -Checks to see if the character(s) given are in the given C<$category>. The -string-based versions are conveniences that convert any NFG input to NFC, and -then pass it along to the integer version. - - unimatch("A", "Lu"); # True - unimatch("A", "L"); # True - unimatch("A", "Sc"); # False - -An error may be issued if the given category name is not valid. - -=head2 Numeric Codepoint - - ord(Stringy $char) --> Int - ords(Stringy $string) --> Array[Int] - - Stringy.ord() --> Int - - Stringy.ords() --> Array[Int] - -The C<&ord> function (and corresponding C<Stringy.ord> method) return the -codepoint number of the base character of the first grapheme of the string. -The C<&ords> function and method returns an C<Array> of codepoint numbers -of the base character for every grapheme in the string. - -This works on any type that does the C<Stringy> role. - -=head2 Character Representation - - chr(Int $codepoint) --> Uni - chrs(Array[Int] @codepoints) --> Uni - - Cool.chr() --> Uni - Cool.chrs() --> Uni - -Converts one or more numbers into a series of characters, treating those numbers -as Unicode codepoints. The C<chrs> version generates a multi-character string -from the given array. - -Note that this operates on encoding-independent codepoints (use C<Buf> types for -encoded codepoints). - -An error will occur if the C<Uni> generated by these functions contains an -invalid character or sequence of characters. This includes, but is not limited -to, codepoint values greater than C<0x10FFFF> and parts of surrogate code pairs. - -To obtain a more definitive string type, the normal ways of type conversion may -be used. - -=head2 Character Name - - uniname(Str $char, :$one = False, :$either = False) --> Str - uninames(Str $char, :$one = False, :$either = False) --> Array[Str] - - Str.uniname(:$one = False, :$either = False) --> Str - Str.uninames(:$one = False, :$either = False) --> Array[Str] - -The C<&uniname> function returns the Unicode name associated with the first -codepoint of the string. C<&uninames> returns an array of names, one per -codepoint. - -By default, C<uniname> tries to find the Unicode name associated with that -character, returning a code point label (see -L<UAX#44|http://www.unicode.org/reports/tr44/tr44-12.html#Code_Point_Labels> and -section 4.8 of the Standard). This is nearly identical to accessing the C<Name> -property from the C<uniprops> list, except that the list holds an empty string -for undefined names. - - uninames("A\x[00]¶\x[2028,80]") - # results in: - "LATIN CAPITAL LETTER A", - "<control-0000>", - "PILCROW SIGN", - "LINE SEPARATOR", - "<control-0080>" - -The C<:one> adverb instead tries to find the Unicode 1.0 name associated with -the character (this would most often be useful with getting a proper name for -control codes). If there is no Unicode 1.0 name associated with the character, a -code point label is returned. This is similar to the C<Unicode_1_Name> property -of the C<uniprops> list, except that the list holds an empty string for -undefined Unicode 1.0 names. - - uninames("A\x[00]¶\x[2028,80]", :one) - # results in: - "<graphic-0041>", - "NULL", - "PARAGRAPH SIGN", - "<format-2028>", - "<control-0080>" - -The C<:either> adverb will try to first obtain a Unicode name for the -character. Failing that, it will try to instead obtain the Unicode 1.0 name. If -the character has neither name property defined, a code point label is returned. - - uninames("A\x[00]¶\x[2028,80]", :either) - # results in: - "LATIN CAPITAL LETTER A", - "NULL", - "PILCROW SIGN", - "LINE SEPARATOR", - "<control-0080>" - -The use of C<:either> and C<:one> together will prefer Unicode 1.0 names over -newer Unicode names, but otherwise function identically to C<:either>. - - uninames("A\x[00]¶\x[2028,80]", :either :one) - # results in: - "LATIN CAPITAL LETTER A", - "NULL", - "PARAGRAPH SIGN", - "LINE SEPARATOR", - "<control-0080>" - -In the case of graphical or formatting characters without a Unicode 1.0 name, -the use of the C<:one> adverb by itself will return a I<non-standard> codepoint -label of either of the following: - - <graphic-XXXX> - <format-XXXX> - -Note that the use of C<:either> and C<:one> together will not use these -non-standard labels, as every graphic and format character has a current Unicode -name. - -The definition of "graphic" and "format" characters is covered in Section 2.4, -Table 2-3 of the current Unicode Standard. - -This command does not deal with name aliases; get the C<Name_Alias> property -from C<uniprop>. - -If a strict adherence to the values in those properties is desired (i.e. return -null strings instead of code-point labels), the C<Name> and C<Unicode_1_Name> -properties my be used. - -=head2 Numeric Value - - unival(Int $codepoint) - Int.unival - - unival(Unicodey $char) - Unicodey.unival - - univals(Unicodey $str) - Unicodey.univals - -Returns a C<Rat> (or C<Int> if the denominator is 1) of the given character's -numeric value. Returns C<NaN> if the character is not a number. - - say unival("0"); # output: 0 - say unival("½"); # output: .5 - say unival("."); # output: NaN - say univals("½¾"); # output: .5 .75 (array of Rats and/or Ints) - -Note that this will not convert a multi-digit string into one numeral; use the -normal string-to-numeral coercers for that. - -[Conjecture: should C<val()> use C<unival> on one-character strings as part of -its allomorphic type process? E.g. K<./fractionmagic.p6 ¾> takes the one -positional argument as a C<RatStr>.] - -=head1 Regexes - -By default regexes operate on the grapheme (NFG) level, regardless of how the -string itself is stored. - -The following is a list of adverbs that change how regexes view strings: - - :i Ignore case (a ~~ A) - :m Ignore marks (ä ~~ a) - - :nfg String matching against as NFG (default) - :nfc String as NFC - :nfd String as NFD - :nfkc String as NFKC - :nfkd String as NFKD - -There's of course the syntax for accessing Unicode properties inside a regex: - - <:Letter> - <:East_Asian_Width<Narrow>> - -(For example, if you needed to collect combining mark usage (e.g. for -language-guessing purposes): - - $string ~~ /:nfd [<:Letter> (<:Mark>*)]+/ - -would get that info for you.) - -C</./> always matches one "character" in the current view, in other words one -element of C<"string being matched".ords>. - -=head2 Grapheme Explosion - -To match to one specific character under different rules, you may use one of the -C«</ />» rules. - - <D/ /> Work on next character in NFD mode - <C/ /> NFC mode - <KD/ /> NFKD mode - <KC/ /> NFKC mode - <G/ /> NFG mode - </ /> NFD mode - -This construct was primarily invented to allow you to deal with combining -characters (matches C«<:Mark>») on single graphemes. This is why C«</ />» is -used as a synonym to C«<D/ />». - -The forms with letters may use any brackets. Similar to how C<m/ /> and C</ /> -relate to each other. - - </ /> Explodes grapheme - <⦃ ⦄> Doesn't explode grapheme - <D/ /> Explodes grapheme - <D⦃ ⦄> Explodes grapheme - -So to collect base characters and combining marks in one section of what you're -parsing, you could define such a regex as: - - $string ~~ / </ $<base>=<:Letter> $<marks>=[<:Mark>+] /> / - -Note that each of these exploders become useless when their counterpart adverbs -are used beforehand. - -And yes, some of these forms do the opposite of exploding; the imagery of -radically changing things in a localized area still applies C<:)>. - -=head1 Quoting Constructs - -By default, all quoting forms create C<Str> objects: - - "interpolating $string" - 'non-interpolating' - Q[Base form] - -Various adverbs may be used to generate non-NFG literals: - - Q:nfd/NFD literal/ - qq:nfc:to/heredocIsNFC/ - qx:nfkd/useful for commands on less capable terminals perhaps/ - -The typical C<:nf> adverbs are in use here. - - :nfg Str literal (default) - :nfd NFD literal - :nfc NFC literal - :nfkd NFKD literal - :nfkc NFKC literal - -=head1 Unicode Literals - -=head2 Identifiers - -Identifiers in Perl 6 can start with any alphabetic character (those characters -in the C<L> category, as well as underscore), followed by any number of -alphanumeric characters (those characters in the C<L> or C<N> category, as well -as underscore). Dashes (C<->) and apostrophes (C<'>) may also appear, provided -that they are followed by an alphabetic character. - - my $foo; # OK - my $ｆｏｏ; # also OK - my $১০kinds; # not ok (১০ are digits) - -Combining marks (characters in the C<M> category) may not be the first character -in an identifier, but they may appear at any time afterwards. - -Perl 6 internally stores all identifiers in NFG form, so these two lines create -the same variable (and throw a redeclaration warning if used like this in code): - - my $ä; # precomposed - my $ä; # not precomposed - -=head2 Numbers - -Similar to its support for any kind of Unicode in identifiers, Perl 6 allows any -kind of character within the category C<Nd> (Decimal Number) for decimal -numbers: - - say 42 + ٤٢; # ascii digits + arabic indic - say ᱄2; # lepcha & ascii - say ⑨; # not ok (category No, not Nd) - -For hexadecimal digits, any character with C<Hex_Digit = yes> is allowed: - - say 0xCAFE; # OK - say 0xｃａｆｅ; # OK too - -The C<:radix[]> form of specifying numbers can accept strings following this -same rule, with the following sets of characters specifying digits C<10..35>, as -they have characters with true C<Hex_Digit> properties: - - a b c d e f g h i j k l m n o p q r s t u v w x y z - A B C D E F G H I J K L M N O P Q R S T U V W X Y Z - ａ ｂ ｃ ｄ ｅ ｆ ｇ ｈ ｉ ｊ ｋ ｌ ｍ ｎ ｏ ｐ ｑ ｒ ｓ ｔ ｕ ｖ ｗ ｘ ｙ ｚ - Ａ Ｂ Ｃ Ｄ Ｅ Ｆ Ｇ Ｈ Ｉ Ｊ Ｋ Ｌ Ｍ Ｎ Ｏ Ｐ Ｑ Ｒ Ｓ Ｔ Ｕ Ｖ Ｗ Ｘ Ｙ Ｚ - -For radices greater than 36, you must use literal numbers (see L<doc:S02/General -radices> for details). - -=head1 Pragmas - -[ the NF* pragmas have been removed, as they no longer are attributes of a Str -object, and there's no sane way to set a default string-like type in a clean -fashion. ] - - use encoding :utf8; - use encoding :utf16<be> or :utf16<le>; - use encoding :utf32<be> or :utf32<le>; - -The C<encoding> pragma changes the default encoding for situations where that's -necessary, e.g. for the default C<Str.encode> or C<Buf.decode>. C<Str>s -themselves don't store encoding information. - -=for code :allow<R> - use unicode :v(R<version>); - -Specifies what version of Unicode you want to use. The C<$*UNICODE> variable -will tell you what version of Unicode is currently in use. This is useful if you -need to work on data created for much older Unicode versions, or if you're doing -work with properties known to be highly volatile between versions. - -Pragmas are of course localize-able: - - my $first = "hello"; # NFG string - { - use unicode :v(3.2); - ⋮ - } - - my $buffer = "foobar".encode; # object of type utf8 in $buffer - { - use utf32<le>; - $buffer = "foobar".encode; # object of type utf32 in $buffer - } - say $buffer.WHAT # output: (utf32) - -=head1 Final Considerations - -The C<Stringy> and C<Unicodey> roles need some expansion, definitely. Keep in -mind that the C<Uni> type is supposed to accept any of the C<NFC>, C<NFD>, -C<NFKC>, and C<NFKD> contents without normalizing. - -The inclusion of ropey types will most directly impact C<Uni>. - -Operators between various string types need defining. The general rule should be -"most specialized type wins" for the return value. - - NFD ~ NFD --> NFD - NFC ~ NFKD --> Uni - (UAX#15 says concat of mismatched NFs results in a non-NF string, which - is our Uni type.) - -[Note: concatenation and similar operations forming one string from parts can lead to non-NF, -even between NFC ~ NFC or NFG ~ NFG, if the second string begins with one (or more) "orphan" -combining characters.] - -Regexes likely need more work, though I don't see anything immediate. - -Some easy way to change how Perl 6 handles language specific weirdness, possibly -through another type (C<Rope>? C<Twine>? C<Yarn>?). A very small selection of -those weirdnesses: - -=item Turkish dotted and dotless eyes (I ı and İ i), which follow non-standard -casing. - -=item Those who realize the superiority of a capital ẞ and would rather ß not be -capitalized to SS C<:D>. - -How would a hypothetical C<EBCDIC> string type be implemented by some module -writer? - -Other areas to consider, surely. - -(This spec should not be moved to a status more official than DRAFT status until -this Final Considerations section disappears.) - -=AUTHOR -=for table - Matthew N. "lue" <L<rnddim@gmail.com|mailto:rnddim@gmail.com>> - Helmut Wollmersdorfer <L<helmut.wollmersdorfer@gmail.com|mailto:helmut.wollmersdorfer@gmail.com>> - -=ACKNOWLEDGEMENT - -Thanks to TimToady and the rest here: -L<http://irclog.perlgeek.de/perl6/2013-12-02#i_7942599> for answering my -questions and inadvertently steering this document in a far different direction -than I would've taken it otherwise. - -=comment vim: expandtab sw=4 -=end pod diff --git a/S16-io-OLD.pod b/S16-io-OLD.pod deleted file mode 100644 index bc6b76d3..00000000 --- a/S16-io-OLD.pod +++ /dev/null @@ -1,293 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 16: IO / Name Services - -=head1 VERSION - - Created: 12 Sep 2006 - - Last Modified: 19 Nov 2009 - Version: 23 - -This is a draft document. Many of these functions will work as in Perl -5, except we're trying to rationalize everything into roles. For -now you can assume most of the important functions will automatically -be in the * namespace. However, with IO operations in particular, -many of them are really methods on an IO handle, and if there is a -corresponding global function, it's merely an exported version of -the method. - -=head1 IO - -=head2 Overridable IO handles - -In Perl 6, there are the I<standard> IO handles, and any number of overriding -inner filehandles for the same symbol. - -The I<standard> handles are our old familiar friends (with new names). -Standard input changed from STDIN to C<$*IN>, standard output changed -from STDOUT to C<$*OUT>, and standard error changed from STDERR to -C<$*ERR>. In Perl 6 these symbols represent more of a concept than -a given filehandle, since the meaning is contextually determined. -The process's version of these handles live in the C<PROCESS::> -namespace, which is more global than the per-interpreter C<GLOBAL::> -namespace. - -When no explicit filehandle is used, the standard IO operators are -defined in terms of the dynamic variables. So the C<print> function -prints to C<$*OUT>, while C<warn> warns to C<$*ERR>. The C<< lines() >> -term inputs from C<$*ARGFILES> which defaults to C<$*IN> in the absence of any -filenames. So any given dynamic scope (interpreter, -thread, function or method call) may redefine the current meaning of -any of those filehandles within the dynamic scope of itself and of -its called routines. - -So to put it another way, when you write something like - - say "Howdy, world!" - -the C<say> function looks for the current meaning of C<$*OUT>, and -takes the closest definition it can find in its callers. If none -of the callers have overridden the definition, it looks in the -interpreter's C<GLOBAL> namespace. If the interpreter hasn't overridden -the meaning, it takes the meaning from C<PROCESS>. In essence, any -dynamic scope in Perl 6 is allowed to do IO redirection much like -a Unix shell does with its subprocesses, albeit with a different -syntax: - - { - temp $*OUT = open $newfile, :w; - foo() # all stdout goes to $newfile - } - # stdout reverts to outer scope's definition - -=head2 Roles and Classes - -The roles and classes that define most of the functionality for IO are defined in -S32-setting-library/IO.pod. The main functions used are listed in S29 with references to -S32-setting-library/IO.pod. - -=head2 Special Quoting Syntax - -The use of filenames requires a special quoting syntax. It works as follows: - - qp{/path/to/file} - q:p{/path/to/file} - -Both of the above result in the same C<IO::Path> object. - -The quote characters can be any of the usual ones, although / is probably a bad choice -for filenames. - -The code shown above returns a Path object (or a descendant thereof). - -Naturally you can also ask for interpolation in filenames: - - qp:qq{$directory/$file} - qq:p{$directory/$file} - -There are a number of special adverbs that can be applied to the file quoting -operator. Most of these are filesystem-specific. They confine what can be -included in a filename. - -Any path that starts with a "/" is considered an absolute path, otherwise -the path is considered relative. - -When creating a path with qp{}, the Path.Encoding attribute is set to $?ENC, unless -the :bin modifier (see below) is used. - -=head3 Default constraints - -The default constraints can be set with the "use path" pragma, for example: - - use path :posix; - use path :modern; - use path :local; - -The default when in strict mode is "use path :posix", whereas the default in -lax mode is "use path :local". - -=head3 :posix constraints - -The :modern set of constraints paths are portable POSIX paths (see POSIX.1-2008 sections -4.7 and 3.276). If platform/filesystem specific behavior is needed, -specific constraints should be applied as needed (see below). - -The default constraints are to only allow "/" as separator and only allows -portable POSIX filenames. That means A-Z, a-z, 0-9, <period>, <underscore>, -and <hyphen>. Additionally, hyphen may not be the first character in the path. - -Any path that starts with a "/" is considered an absolute path, otherwise -the path is considered relative. - -=head3 :portable - -In addition to the POSIX constraints above, the path should fit into 8 -characters, followed by a full stop, and then three more characters. Only -the one full stop should appear in the filename. Additionally, no path -may be longer than 64 characters. - -=head3 :local - -This is :win on a Windows platform, :unix on a Unix platform, etc. Note -that this is specifically not portable between platforms with different -constraint sets. - -=head3 :modern constraints - -The :modern set of constraints are the same as :posix, except that they -may contain any UTF-8 character, rather than just those listed. - -=head3 :win constraints - -We allow Windows style paths so converting and maintaining code on this -platform is not a pain. - -my Path $path = p:win{C:\Program Files\MS Access\file.file}; - -Note that this specifically excludes the backslash quoting usually used with -q{}. - -=head3 :unix constraints - -For Unix specific behavior we have a p:unix{} literal. Here the only -limits are what is defined by the locale and the filesystem type. So we won't -be able to write full Unicode if locale is set to Latin1. - -my Path $path = p:unix{/usr/src/bla/myfile?:%.file}; - -=head3 :bin constraints (no constraints at all) - -If the above are causing problems, p:bin{} can be used as no checking is -done here. However, this leaves the Path.Encoding attribute undefined, which -means that certain features of Path will remain unavailable unless this -attribute is set. - -=head3 Other constraints - -It is expected that other sets of constraints, such as VMS, DOS, and old-style -Mac will be provided by modules. - -=head2 $*CWD - -The global variable $*CWD is a C<IO::Path> object with certain special -properties, mainly: - - * It must check whether the path exists before changing its value - * It can only be assigned an absolute path; if you want to make relative - changes, use the Array interface with .push and .pop - -$*CWD is specific to the current thread, unlike C<< %*ENVZ<><PATH> >> or the -native getcwd/chdir path, which are both usually process-wide. - -The variable is used in at least these cases: - - * When a IO::Path object is created, if the string it is given is not an - absolute path, then $*CWD is prepended to it. - * When a subprocess is executed, it is executed with the current - thread's $*CWD as its working directory. - -=head2 $*TMPDIR - -The global variable $*TMPDIR is an IO::Path object which points to the system's -temporary directory. It will check the usual places such a C<< %*ENVZ<><TMPDIR> >>, -C</tmp>, C<C:\Windows\temp>, etc (depending on the OS) for a writable directory. -If a writable directory isn't found, it is set to $*CWD. - -=head1 Name Services - -=head2 User role - - role User { - has $username; # Username (some descendants(?) may want to implement a real $name) - has $id; # User ID - has $dir; # Home directory for files - } - -=over - -=item new - - method User new($Username?, $UID?) {...} - -Creates a new User object, fetching the information either by username or user ID. - -=item write - - method write() {...} - -Tries to write the current User object to the user database. This may well fail. - -=item Str - -When converted to a Str, returns $username. - -=item Num - -When converted to a Num, returns $uid. - -=back - -=head2 OS::Unix::User role - - role OS::Unix::User does User { - has $password; - has $gid; - has $gecos; - has $shell; - } - -All the information is naturally fetched from the system via getpwuid, getpwnam, or the -like. - -=head2 Group role - - role Group { - has $name; - has $id; - has @members; - } - -=over - -=item new - - method Group new(:$Name, :$ID); - -=item write - - method write(); - -Tries to write the group entry into the system group database. - -=back - -=head2 OS::Unix::NameServices role - -The NameServices role has a bunch of functions that between them will return the whole -Name Services database between them, as lists of objects. The lists are specifically -intended to be lazy. - - role NameServices { - method List of User users() {...} # getpwent, setpwent, endpwent - method List of Group groups() {...} # getgrent, setgrent, endgrent - method List of Service services() {...} # getservent, setservent, endservent - method List of Protocol protocols() {...} # getprotoent, setprotoent, endprotoent - method List of Network networks() {...} # getnetent, setnetent, endnetent - method List of Host hosts() {...} # gethostent, sethostent, endhostent - } - -=cut - -=head1 AUTHORS - - Largely, the authors of the related Perl 5 docs. - Larry Wall <larry@wall.org> - Mark Stosberg <mark@summersault.com> - Tim Nelson <wayland@wayland.id.au> - Daniel Ruoso <daniel@ruoso.com> - -=for vim:set expandtab sw=4: diff --git a/S16-io.pod b/S16-io.pod deleted file mode 100644 index bb0f4d16..00000000 --- a/S16-io.pod +++ /dev/null @@ -1,469 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -Synopsis 16: I/O - -=head1 VERSION - - Created: 12 Sep 2006 - - Last Modified: 5 Nov 2014 - Version: 28 - -Many of these functions will work as in Perl 5, except we're trying to rationalize everything into roles. For -now you can assume most of the important functions will automatically -be in the * namespace. However, with IO operations in particular, -many of them are really methods on an IO handle, and if there is a -corresponding global function, it's merely an exported version of -the method. - -=head1 IO - -=head2 Overridable IO handles - -In Perl 6, there are the I<standard> IO handles, and any number of overriding -inner filehandles for the same symbol. - -The I<standard> handles are our old familiar friends (with new names). -Standard input changed from STDIN to C<$*IN>, standard output changed -from STDOUT to C<$*OUT>, and standard error changed from STDERR to -C<$*ERR>. In Perl 6 these symbols represent more of a concept than -a given filehandle, since the meaning is contextually determined. -The process's version of these handles live in the C<PROCESS::> -namespace, which is more global than the per-interpreter C<GLOBAL::> -namespace. - -When no explicit filehandle is used, the standard IO operators are -defined in terms of the dynamic variables. So the C<say> function -prints to C<$*OUT>, while C<note> prints to C<$*ERR>. The C<lines()> -term inputs from C<$*ARGFILES> which defaults to C<$*IN> in the absence of any -filenames. So any given dynamic scope (interpreter, -thread, function or method call) may redefine the current meaning of -any of those filehandles within the dynamic scope of itself and of -its called routines. - -So to put it another way, when you write something like - - say "Howdy, world!" - -the C<say> function looks for the current meaning of C<$*OUT>, and -takes the closest definition it can find in its callers. If none -of the callers have overridden the definition, it looks in the -interpreter's C<GLOBAL> namespace. If the interpreter hasn't overridden -the meaning, it takes the meaning from C<PROCESS>. In essence, any -dynamic scope in Perl 6 is allowed to do IO redirection much like -a Unix shell does with its subprocesses, albeit with a different -syntax: - - { - my $*OUT will leave *.close = open $newfile, :w; - say "Written to $newfile"; - } - # stdout reverts to outer scope's definition, and closed the file - -In short: - - default handle - routine for sub form purpose - ======= =========== ======= - print $*OUT string-based writing - say $*OUT string-based writing - get $*ARGFILES read a line (Str) - lines $*ARGFILES read all lines (Str) - words $*ARGFILES read all words (Str) - read binary reading (Buf) - write binary writing (Buf) - -=head2 Path Names and the .IO coercer - -Path names are just strings (C<Str>). Methods that return path names, will -just return strings. As soon as you need to do manipulation on the path name -(e.g. to find out its C<basename> or C<extension>), you can create an -C<IO::Path> object out of the string by applying the C<.IO> coercer: - - my $path = $filename.IO; - -Then you can use any of the C<IO::Path> methods, such as C<open>: - - my $handle = $newfile.IO.open(:w); - -Note that the C<open()> sub, is just really syntactic sugar for the above: - - my $handle = open $newfile, :w; - -=head2 $*SPEC - -The current system's path semantics are encapsulated in C<$*SPEC> dynamic -variable. It adheres to the C<IO::Spec> interface, and is automatically -initialized for the current environment. But like any dynamic variable, -can be overridden in a scope: - - { # Win32 path semantics in here - my $*SPEC = IO::Spec::Win32; - ... # your code - } - # original path semantics here again - -Please note that it does B<not> need to be an instantiated object: the standard -C<IO::Spec> subclasses only provide class methods, and therefore do not need an -instantiated object. But that could be different for a very specific -third-party implementation of an C<IO::Spec> class. - -=head2 $*CWD and chdir() - -The dynamic variable $*CWD is an C<IO::Dir> object representing the current -working directory. It is normally set with the C<chdir()> function, which will -check whether the specified path exists as a directory and is accessible -(C<-x>). - - chdir($dir); # sets $*CWD of scope, usually PROCESS::<$CWD> - -The C<chdir()> function returns a C<X::IO::Chdir> Failure if the path does -not exist, or is not a directory, or is not accessible. Otherwise -returns a newly created C<IO::Dir> object (which will be C<True>). - -Please note that the path in C<$*CWD> does not have any bearing on what the -underlying operating system's concept of a "current directory". It is simply -the path that will prepended before any implicit or explicit relative paths, -and the default path that will be used when executing a sub-process. - -To be changing C<$*CWD> just for a given scope, you can use C<indir()>: - - indir $dir, { - ... your code in $dir ... - }; - ... your code in $*CWD again ... - -or you can use C<chdir()> with a temporary C<$*CWD>: - - { - temp $*CWD = chddir($dir); - ... your code in $dir ... - } - ... your code in $*CWD again ... - -=head2 $*TMPDIR and tmpdir() - -The dynamic variable C<$*TMPDIR> is an C<IO::Dir> object which points to the -system's directory for temporary files. It can be set with the C<tmpdir()> -function which will check whether the specified path exists as a directory and -has complete access (C<+rwx>). - - tmpdir($dir); # sets $*TMPDIR of scope, usually PROCESS::<$TMPDIR> - -To set a locally scoped version of C<$*TMPDIR>, you can use C<tmpdir()> with -a temporary C<$*TMPDIR>: - - { - temp $*TMPDIR = $tmpdir($dir); - ... your code with $*TMPDIR being $dir ... - } - ... your code in original $*TMPDIR again ... - -It will return a newly created C<IO::Dir> object (which is C<True>) or an -appropriate C<Failure>. - -The initialization of C<$*TMPDIR> at startup is set depending on the OS you're -on. - -=head2 $*HOME and homedir() - -The dynamic variable C<$*HOME> is an C<IO::Dir> object which points to the -user's home directory. It can be set with the C<homedir()> function -which will check whether the specified path exists as a directory and is -completely accessible (C<+rwx>). - - homedir($dir); # sets $*HOME of scope, usually PROCESS::<$HOME> - -To set a locally scoped version of C<$*HOME>, you can use C<homedir()> with a -temporary C<$*HOME>: - - { - temp $*HOME = homedir($dir); - ... your code with $*HOME being $dir ... - } - ... your code in original $*HOME again ... - -It will return a newly created C<IO::Dir> object (which is C<True>) or an -appropriate C<Failure>. - -The initialization of C<$*HOME> at startup is set depending on the OS you're on. - -=head2 System dependent path semantics and IO::Spec - -Each time an C<IO::Path> object is created, the current C<$*SPEC> will be -encapsulated in the object, to be used for all path related operations. - -Of course, it is also possible to specify a specify a specific system's -path semantics module when creating an C<IO::Path> object with the C<:SPEC> -named parameter: - - my $SPEC = IO::Spec::Win32; - my $path = $fileonNTFS.IO(:$SPEC); - -or: - - my $path = $fileonNTFS.IO(:SPEC<Win32>); # auto-expand to IO::Spec::Win32 - -=head2 Functions and Classes - -The functions and classes that define most of the functionality for IO are -more thoroughly defined in S32-setting-library/IO.pod. The main functions -used are listed in S29 with references to S32-setting-library/IO.pod. -An overview: - -=head3 Functions - - print(@text) # print text on $*OUT - say(@text) # print text + newline on $*OUT - note(@text) # print text + newline on $*ERR - dd($a,$b,$c) # tiny data dumper on $*ERR - $line = prompt($message) # print message on $*OUT, obtain next line - - $handle = open($path) # open a file, return IO::Handle - - @paths = dir # paths (as IO::Path) in $*CWD - @paths = dir($dir) # paths (as IO::Path) in $dir - - $contents = slurp($handle) # read all that's left of an opened filehandle - $contents = slurp($filename) # read all from given filename - - spurt($handle,$contents) # write $contents to $handle - spurt($filename,$contents) # write $contents to $filename - - mkdir($dir) # create a directory - rmdir($dir) # remove a directory - mkpath($path) # create directory and parents as appropriate - - chdir($dir) # set $*CWD - temp $*CWD = chdir($dir) # set $*CWD for the current scope - - indir($dir, { ... }) # execute code with temporary $*CWD - ... - }; - - tmpdir($dir) # set $*TMPDIR - temp $*TMPDIR = tmpdir($dir) # set $*TMPDIR for the current scope - - homedir($dir) # set $*HOME - temp $*HOME = homedir($dir) # set $*HOME for the current scope - - copy($from,$to) # copy a file - rename($from,$to) # rename (move) a file on same physical storage - move($from,$to) # move (rename) a file to other storage - unlink(*@files) # remove one or more files - chmod($permission,*@files) # change permissions of one or more files - - link($target,$source) # create a hard-link to a file - symlink($target,$source) # create a symbolic link to a file - -=head3 IO::Spec Class - -The C<IO::Spec> itself only has one method: C<select>. It takes an OS -descriptive name (usually something like what C<$*DISTRO.name> gives) and -returns the type object of the appropriate C<IO::Spec> subclass. - - my $*SPEC = IO::Spec.select("MSWin32"); # gives IO::Spec::Win32 - -Such a subclass should provide at least the following methods (in alphabetical -order): - - abs2rel convert an absolute path into a relative one - canonpath return a canonical version of the given path - catdir concatenate directories - catpath create a path from volume/directories/filename - curdir the path to the current directory (usually '.') - curupdir test for matching curdir|updir - devnull the path to the bit bucket (on Unixy systems '/dev/null') - extension the extension of the path - is-absolute whether the path is absolute - join create a path from hash with volume/directories/filename - PATH %ENV<PATH> interpreted as paths - rel2abs convert a relative path into an absolute one - rootdir the path to the root directory (on Unixy systems '/') - split split a path into volume/directories/filename in hash - splitdir split directories - splitpath split a path into volume/directories/filename as list - tmpdir path of the first writeable directory for temporary files - updir the path to the path directory (usually '..') - -=head3 IO::Path Class - - class IO::Path is Cool { } - -The official way to create an C<IO::Path> object is with the C<new> method. -Apart from the C<path> positional, it also takes optional C<:SPEC> and -C<CWD> named parameters. The C<.IO> coercer (which takes the same parameters -as C<.new>) is the syntactic sugar that will most likely be used most often. - - my $io = $filename.IO; # current $*SPEC/$*CWD - my $io = $filename.IO(:SPEC(*$SPEC)); # specific IO::SPEC - my $io = $filename.IO(:SPEC(*$SPEC), :CWD($*CWD)); - -which would be the same as: - - my $io = IO::Path.new($filename); - my $io = IO::Path.new($filename, :SPEC(*$SPEC)); - my $io = IO::Path.new($filename, :SPEC(*$SPEC), :CWD($*CWD)); - -If you only have filename components to start with, you can also create an -C<IO::Path> object with the C<:volume>, C<:directory> and C<:basename> named -parameters: - - my $io = IO::Path.new( :$volume, :$directory, :$basename ); - -The following file test methods are provided: - - r is readable by effective uid/gid - w is writable by effective uid/gid - x is executable by effective uid/gid - o is owned by effective uid - - R is readable by real uid/gid - W is writable by real uid/gid - X is executable by real uid/gid - O is owned by real uid - - e exists - s Size of the $!path of $io in bytes - z has zero size (an empty file) - - f is a plain file - d is a directory - l is a symbolic link - L path of symbolic link (readlink) - p is a named pipe (FIFO) - S is a socket - b is a block special file - c is a character special file - - u has setuid bit set - g has setgid bit set - k has sticky bit set - -To allow for easy chaining of file tests, there is an C<.all> method that can -be fed the tests to be tried as a list of strings. The value returned -will be the first non-True value, or the final True value. - - say "rwx" if $io.all: <r w x>; - - if $io.all(<f r w x s>) -> $size { - say "plain file with rwx of $size bytes"; - } - -This is mostly handy when passing file tests as parameters between routines -and methods. From a performance point of view, direct use of the methods, -like: - - if $io.f && $io.r && $io.w && $io.x && $io.s -> $size { - say "plain file with rwx of $size bytes"; - } - -or the smart match method: - - given $io { - when :f :r :w :x { - say "plain file with rwx of $_.s() bytes"; - } - } - -is probably faster. - -These other methods are also provided (in alphabetical order): - - absolute the absolute, canonical path - accessed last access time (if available) - basename the basename of the path - changed last (metadata) changed time - chdir change $*CWD if directory - child append basename to path, return new object for that - chmod change attributes of path - copy create a copy of file - dir files in path (if dir) - directory the directory part of the absolute path - extension the extension of the file - is-absolute is the (original) path absolute - is-relative is the (original) path relative - lines contents of file as lines - mkdir create directory - modified last modified time - move move (rename) to other storage - open attempt to open file, return IO::Handle - parent remove last portion of path, return new object for that - pipe attempt to open a pipe, return IO::Pipe - pred previous logical path, return new object for that - relative the relative path against CWD - rename rename (move) to other name - resolve follow symlinks to the real path, return new object for that - rmdir remove directory if empty directory - slurp obtain the contents of the file - SPEC the :SPEC at instantiation time - spurt set the contents of the file - succ next logical path, return new object for that - unlink remove file - volume the volume of the path (if any) - words contents of file as words - -=head3 IO::Handle Class - - class IO::Handle does IO { } - -The C<IO::Handle> object is usually B<not> directly instantiated, but -with C<open()> or C<IO::Path.open>. Nonetheless, you B<can> create an -C<IO::Handle> object with just a path: - - my $handle = IO::Handle.new($filename); - my $handle = IO::Handle.new($filename, :SPEC(*$SPEC)); - my $handle = IO::Handle.new($filename, :SPEC(*$SPEC), :CWD($*CWD)); - -This does not interact with anything at all and will appear as if the file -has been C<.close>d. The C<.open> method does interact with the file system: - - $handle.open; # same as $handle = $filename.IO.open - -It either returns True, or a C<Failure> with additional information. - -The other methods of the C<IO::Handle> class are only valid B<after> the -C<.open> has been called successfully: - - close close file handle, flush buffers - encoding set/return encoding of file handle - eof file pointer reached end of file - fileno file descriptor (usually a native integer) - flush flush buffers - get get next line from file - getc get next character from file - ins number of lines read - IO return new IO::Path of path of file - lines return rest of contents of file as lines - opened is the file open? - p the handle is a pipe - path the IO::Path of path of file, handles file tests - print write characters to file - read read bytes from file - say write characters + newline to file - seek move file pointer to given position - slurp return rest of contents of file - spurt write / append contents to file - t is the file a TTY (as a person looking?) - tell return position of file pointer - words return rest of contents of file as words - write write bytes to file - -=head3 Interplay between Roles and Classes - -These classes and roles may cache and share pertinent information for better -performance. - -=head1 AUTHORS - - Largely, the authors of the related Perl 5 docs. - Larry Wall <larry@wall.org> - Mark Stosberg <mark@summersault.com> - Tim Nelson <wayland@wayland.id.au> - Daniel Ruoso <daniel@ruoso.com> - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S17-concurrency.pod b/S17-concurrency.pod deleted file mode 100644 index 981bf9da..00000000 --- a/S17-concurrency.pod +++ /dev/null @@ -1,959 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 17: Concurrency - -=head1 VERSION - - Created: 3 Nov 2013 - - Last Modified: 27 December 2014 - Version: 25 - -This synopsis is based around the concurrency primitives and tools currently being implemented in Rakudo on MoarVM and the JVM. It covers both things that are already implemented today, in addition to things expected to be implemented in the near future (where "near" means O(months)). - -=head1 Design Philosophy - -=head2 Focus on composability - -Perl 6 generally prefers constructs that compose well, enabling large problems to be solved by putting together solutions for lots of smaller problems. This also helps make it easier to extend and refactor code. - -Many common language features related to parallel and asynchronous programming lack composability. For example: - -=over - -=item * - -Locks do not compose, since two independently correct operations using locks may deadlock when performed together. - -=item * - -Callback-centric approaches tend to compose badly, with chains of asynchronous operations typically leading to deeply nested callbacks. This essentially is just leaving the programmer to do a CPS transform of their own logical view of the program by hand. - -=item * - -Directly spawning threads on a per-component basis tends to compose badly, as when a dozen such components are used together the result is a high number of threads with no ability to centrally schedule or handle errors. - -=back - -In Perl 6, concurrency features aimed at typical language users should have good composability properties, both with themselves and also with other language features. - -=head2 Boundaries between synchronous and asynchronous should be explicit - -Asynchrony happens when we initiate an operation, then continue running our own idea of "next thing" without waiting for the operation to complete. This differs from synchronous programming, where calling a sub or method causes the caller to wait for a result before continuing. - -The vast majority of programmers are much more comfortable with synchrony, as in many senses it's the "normal thing". As soon as we have things taking place asynchronously, there is a need to coordinate the work, and doing so tends to be domain specific. Therefore, placing the programmer in an asynchronous situation when they didn't ask for it is likely to lead to confusion and bugs. We should try to make places where asynchrony happens clear. - -It's also worthwhile trying to make it easy to keep asynchronous things flowing asynchronously. While synchronous code is pull-y (for example, eating its way through iterable things, blocking for results), asynchronous code is push-y (results get pushed to things that know what to do next). - -Places where we go from synchronous to asynchronous, or from asynchronous to synchronous, are higher risk areas for bugs and potential bottlenecks. Thus, Perl 6 should try to provide features that help minimize the need to make such transitions. - -=head2 Implicit parallelism is OK - -Parallelism is primarily about taking something we could do serially and using multiple CPU cores in order to get to a result more quickly. This leads to a very nice property: a parallel solution to a problem should give the same answer as a serial solution. - -While under the hood there is asynchrony and the inherent coordination it requires, on the outside a problem solved using parallel programming is still, when taken as a whole, a single, synchronous operation. - -Elsewhere in the specification, Perl 6 provides several features that allow the programmer to indicate that parallelizing an operation will produce the same result as evaluating it serially: - -=over - -=item * - -Hyper operators (L<S03/Hyper operators>) express that parallel operator application is safe. - -=item * - -Junctions (L<S09/Junctions>) may auto-thread in parallel. - -=item * - -Feeds (L<S06/Feed operators>) form pipelines and express that the stages may be executed in parallel in a producer-consumer style relationship (though each stage is in itself not parallelized). - -=item * - -C<hyper> and C<race> list operators (L<S02/The hyper operator>) express that iteration may be done in parallel; this is a generalization of hyper operators. - -=back - -=head2 Make the hard things possible - -The easy things should be easy, and able to be built out of primitives that compose nicely. However, such things have to be built out of what VMs and operating systems provide: threads, atomic instructions (such as CAS), and concurrency control constructs such as mutexes and semaphores. Perl 6 is meant to last for decades, and the coming decades will doubtless bring new ways do do parallel and asynchronous programming that we do not have today. They will still, however, almost certainly need to be built out of what is available. - -Thus, the primitive things should be provided for those who need to work on such hard things. Perl 6 should not hide the existence of OS-level threads, or fail to provide access to lower level concurrency control constructs. However, they should be clearly documented as I<not> the way to solve the majority of problems. - -=head1 Schedulers - -Schedulers lie at the heart of all concurrency in Perl 6. While most users are unlikely to immediately encounter schedulers when starting to use Perl 6's concurrency features, many of them are implemented in terms of it. Thus, they will be described first here to avoid lots of forward references. - -A scheduler is something that does the C<Scheduler> role. Its responsibility is taking code objects representing tasks that need to be performed and making sure they get run, as well as handling any time-related operations (such as, "run this code every second"). - -The current default scheduler is available as C<$*SCHEDULER>. If no such dynamic variable has been declared, then C<$PROCESS::SCHEDULER> is used. This defaults to an instance of C<ThreadPoolScheduler>, which maintains a pool of threads and distributes scheduled work amongst them. Since the scheduler is dynamically scoped, this means that test scheduler modules can be developed that poke a C<$*SCHEDULER> into C<EXPORT>, and then provide the test writer with control over time. - -The C<cue> method takes a C<Callable> object and schedules it. - - $*SCHEDULER.cue: { say "Golly, I got scheduled!" } - -Various options may be supplied as named arguments. (All references to time are taken to be in seconds, which may be fractional.) You may schedule an event to fire off after some number of seconds: - - $*SCHEDULER.cue: in=>10, { say "10s later" } - -or at a given absolute time, specified as an C<Instant>: - - $*SCHEDULER.cue: at=>$instant, { say "at $instant" } - -If a scheduled item dies, the scheduler will catch this exception and pass it to a C<handle_uncaught> method, a default implementation of which is provided by the C<Scheduler> role. This by default will report the exception and cause the entire application to terminate. However, it is possible to replace this: - - $*SCHEDULER.uncaught_handler = sub ($exception) { - $logger.log_error($exception); - } - -For more fine-grained handling, it is possible to schedule code along with a code object to be invoked with the thrown exception if it dies: - - $*SCHEDULER.cue: - { upload_progress($stuff) }, - catch => -> $ex { warn "Could not upload latest progress" } - -Use C<:every> to schedule a task to run at a fixed interval, possibly with a delay before the first scheduling. - - # Every second, from now - $*SCHEDULER.cue: :every(1), { say "Oh wow, a kangaroo!" }; - - # Every 0.5s, but don't start for 2s. - $*SCHEDULER.cue: { say "Kenya believe it?" }, :every(0.5), :in(2); - -Since this will cause the given task to be executed at the given interval ad infinitum, there are two ways to make sure the scheduling of the task is halted at a future time. The first is provided by specifying the C<:times> parameter in the .cue: - - # Every second, from now, but only 42 times - $*SCHEDULER.cue: :every(1), :times(42), { say "Oh wow, a kangaroo!" }; - -The second is by specifying code that will be checked at the end of each interval. The task will be stopped as soon as it returns a True value. You can do this with the C<:stop> parameter. - - # Every second, from now, until stopped - my $stop; - $*SCHEDULER.cue: :every(1), :stop({$stop}), { say "Oh wow, a kangaroo!" }; - sleep 10; - $stop = True; # task stopped after 10 seconds - -The C<.cue> method returns a C<Cancellation> object, which can also be used to stop a repeating cue: - - my $c = $*SCHEDULER.cue: :every(1), { say "Oh wow, a kangaroo!" }; - sleep 10; - $c.cancel; # task stopped after 10 seconds - -Schedulers also provide counts of the number of operations in various states: - - say $*SCHEDULER.loads; - -This returns, in order, the number of cues that are not yet runnable due to delays, the number of cues that are runnable but not yet assigned to a thread, and the number of cues that are now assigned to a thread (and presumably running). -[Conjecture: perhaps these should be separate methods.] - -Schedulers may optionally provide further introspection in order to support tools such as debuggers. - -There is also a C<CurrentThreadScheduler>, which always schedules things on the current thread. It provides the same methods, just no concurrency, and any exceptions are thrown immediately. This is mostly useful for forcing synchrony in places that default to asynchrony. (Note that C<.loads> can never return anything but 0 for the currently running cues, since they're waiting on the current thread to stop scheduling first!) - -=head1 Promises - -A C<Promise> is a synchronization primitive for an asynchronous piece of work that will produce a single result (thus keeping the promise) or fail in some way (thus breaking the promise). - -The simplest way to use a C<Promise> is to create one: - - my $promise = Promise.new; - -And then later C<keep> it: - - $promise.keep; # True - $promise.keep(42); # a specific return value for kept Promise - -Or C<break> it: - - $promise.break; # False - $promise.break(X::Some::Problem.new); # With exception - $promise.break("I just couldn't do it"); # With message - -The current status of a C<Promise> is available through the C<status> method, which returns an element from the C<PromiseStatus> enumeration. - - enum PromiseStatus (:Planned(0), :Kept(1), :Broken(2)); - -The result itself can be obtained by calling C<result>. If the C<Promise> was already kept, the result is immediately returned. If the C<Promise> was broken then the exception that it was broken with is thrown. If the C<Promise> is not yet kept or broken, then the caller will block until this happens. - -A C<Promise> will boolify to whether the C<Promise> is already kept or broken. There is also an C<cause> method for extracting the exception from a C<Broken> C<Promise> rather than having it thrown. - - if $promise { - if $promise.status == Kept { - say "Kept, result = " ~ $promise.result; - } - else { - say "Broken because " ~ $promise.cause; - } - } - else { - say "Still working!"; - } - -You can also simply use a switch: - - given $promise.status { - when Planned { say "Still working!" } - when Kept { say "Kept, result = ", $promise.result } - when Broken { say "Broken because ", $promise.cause } - } - -There are various convenient "factory" methods on C<Promise>. The most common is C<start>. - - my $p = Promise.start(&do_hard_calculation); - -This creates a C<Promise> that runs the supplied code, and calls C<keep> with its result. If the code throws an exception, then C<break> is called with the C<Exception>. Most of the time, however, the above is simply written as: - - my $p = start { - # code here - } - -Which is implemented by calling C<Promise.start>. - -There is also a method to create a C<Promise> that is kept after a number of seconds, or at a specific time: - - my $kept_in_10s = Promise.in(10); - my $kept_in_duration = Promise.in($duration); - my $kept_at_instant = Promise.at($instant); - -The C<result> is always C<True> and such a C<Promise> can never be broken. It is mostly useful for combining with other promises. - -There are also a couple of C<Promise> combinators. The C<anyof> combinator creates a C<Promise> that is kept whenever any of the specified C<Promise>s are kept. If the first promise to produce a result is instead broken, then the resulting C<Promise> is also broken. The cause is passed along. When the C<Promise> is kept, it has a C<True> result. - - my $calc = start { ... } - my $timeout = Promise.in(10); - my $timecalc = Promise.anyof($calc, $timeout); - -There is also an C<allof> combinator, which creates a C<Promise> that will be kept when all of the specified C<Promise>s are kept, or broken if any of them are broken. - -[Conjecture: there should be infix operators for these resembling the junctionals.] - -The C<then> method on a C<Promise> is used to request that a certain piece of code should be run, receiving the C<Promise> as an argument, when the C<Promise> is kept or broken. If the C<Promise> is already kept or broken, the code is scheduled immediately. It is possible to call C<then> more than once, and each time it returns a C<Promise> representing the completion of both the original C<Promise> as well as the code specified in C<then>. - - my $feedback_promise = $download_promise.then(-> $res { - given $res.status { - when Kept { say "File $res.result().name() download" } - when Broken { say "FAIL: $res.cause()" } - } - }); - -[Conjecture: this needs better syntax to separate the "then" policies from the "else" policies (and from "catch" policies?), and to avoid a bunch of switch boilerplate. We already know the givens here...] - -One risk when working with C<Promise>s is that another piece of code will sneak in and keep or break a C<Promise> it should not. The notion of a promise is user-facing. To instead represent the promise from the viewpoint of the promiser, the various built-in C<Promise> factory methods and combinators use C<Promise::Vow> objects to represent that internal resolve to fulfill the promise. ("I have vowed to keep my promise to you.") The C<vow> method on a C<Promise> returns an object with C<keep> and C<break> methods. It can only be called once during a C<Promise> object's lifetime. Since C<keep> and C<break> on the C<Promise> itself just delegate to C<self.vow.keep(...)> or C<self.vow.break(...)>, obtaining the vow before letting the C<Promise> escape to the outside world is a way to take ownership of the right to keep or break it. For example, here is how the C<Promise.in> factory is implemented: - - method in(Promise:U: $seconds, :$scheduler = $*SCHEDULER) { - my $p = Promise.new(:$scheduler); - my $v = $p.vow; - $scheduler.cue: { $v.keep(True) }, :in($seconds); - $p; - } - -The C<await> function is used to wait for one or more C<Promise>s to produce a result. - - my ($a, $b) = await $p1, $p2; - -This simply calls C<result> on each of the C<Promise>s, so any exception will be thrown. - -=head1 Channels - -A C<Channel> is essentially a concurrent queue. One or more threads can put values into the C<Channel> using C<send>: - - my $c = Channel.new; - $c.send($msg); - -The call to C<.send> does not block. - -Meanwhile, other threads can C<.receive> the values: - - my $msg = $c.receive; - -The C<.receive> call does block. Alternatively, the C<.poll> method takes a message from the channel if one is there or immediately returns C<Nil> if nothing is there. Only one call to C<.receive> or C<.poll> returns per call of C<.send>, and which listening thread receives each value is left up to the implementation's scheduler. - -Channels are ideal for producer/consumer scenarios, and since there can be many senders and many receivers, they adapt well to scaling certain pipeline stages out over multiple workers also. [Conjectural: The two feed operators C<< ==> >> and C<< <== >> are implemented using Channel to connect each of the stages.] - -A C<Channel> may be "forever", but it is possible to close it to further sends by telling it to C<close>: - - $c.close(); - -Trying to C<send> any further messages on a closed channel will throw the C<X::Channel::SendOnDone> exception. Closing a channel has no effect on the receiving end until all sent values have been received. At that point, any further calls to receive will throw C<X::Channel::ReceiveOnDone>. The C<closed> method returns a C<Promise> that is kept when a sender has called C<close> and all sent messages have been received. Note that multiple calls to the same channel's C<closed> method return the same promise, not a new one. - -Like C<.close>, calling C<.fail> will close the channel. However this represents an abnormal termination, and so, the method must be provided an exception which should be thrown instead of C<X::Channel::ReceiveOnDone>. - -A C<Promise> may be obtained from a C<Channel> via the C<.closed> method. This C<Promise> will be kept when the C<Channel> is closed or broken if it is failed. - -A C<whenever> clause (described below) on a C<Channel> will fire for each received value, and may also mark the whenever as "done" using the same criteria as C<.closed>, so it can also be used in order to write a reactor to receive from a channel until it is closed: - - react { - whenever $channel { - "Got a $_".say; - } - } - "Done".say; - -A C<whenever> clause on a C<Channel> competes for values inside the scheduler alongside any C<.receive> and C<.poll> -calls on that C<Channel> from other threads. This also is true when the clause is part of a C<supply> block (described -below). - -A C<Channel> in list context will iterate all received values lazily, and stop iterating when the channel is closed: - - for @$channel -> $val { ... } - for $channel.list -> $val { ... } - -Note that this is not a combinator, but a means for transfering data from the reactive realm to the lazy realm. Some reasonable amount of buffering is assumed between the two. Just like all the above constructs, it competes for values in the scheduler against any other readers. - -=head1 Supplies - -Channels are good for producer/consumer scenarios, but because each worker blocks on receive, it is not such an ideal construct for doing fine-grained processing of asynchronously produced streams of values. Additionally, there can only be one receiver for each value. Supplies exist to address both of these issues. - -A C<Supply> pushes or pumps values to one or more receivers who have registered their interest, by (often indirecty) calling the C<.tap> method on the C<Supply>. This returns a C<Tap> object unique to the receiver, which one may then C<.close> to tell the C<Supply> that the receiver is no longer interested. Note that this does B<not> happen automatically if the C<Tap> is thrown away, as the C<Supply> also keeps a reference to the C<Tap>. The C<.tap> method takes up to three callables as arguments, one block and two optional named arguments: - - $supply.tap: -> $value { say "Got a $value" }, - done => { say "Reached the end" }, - quit => { - when X::FooBar { die "Major oopsie" }; - default { warn "Supply shut down early: $_" } - } - -The first unnamed closure is known as the C<emit> closure. It is invoked whenever a value is emitted into the thing that has been tapped. The optional named parameter C<done> specifies the code to be invoked when all expected values have been produced and no more values will be emitted. The optional named parameter C<quit> specifies the code to be invoked if there is an error. This also means there will be no further values. - -For the same reasons that we have C<Vow>s for C<Promise>s, supplies are split into a C<Supply> role and a C<Supplier> role. The C<Supplier> role has a C<.Supply> method used to create a live C<Supply>, and C<emit>, C<done>, and C<quit> methods which send the corresponding events to any C<Supply> objects so created. A C<Supplier> is not tapped directly. The C<Supply> role does not have C<emit>, C<done>, or C<quit> methods, and may be tapped. This allows the provider of a C<Supply>, if they so desire, to be sure that one user cannot inject data to other users of a C<Supply>. Multiple supplies may be created from a C<Supplier>, and all taps of all such supplies receive events sent using said C<Supplier>. - - my $e = Supplier.new; - my $y = $e.Supply; - - my $t1 = $y.tap({ say $_ }); - $e.emit(1); # 1\n - $e.emit(2); # 2\n - - my $t2 = $y.tap({ say 2 * $_ }, - :done({ say "End" })); - $e.emit(3); # 3\n6\n - - $t1.close; - $e.emit(4); # 8\n - $e.done; # End\n - -The above example demonstrates a simple C<live> supply -- note that C<$t2> missed events 1 and 2 because it was not listening at the time they happened. From an outside perspective, a live supply will behave as if it were alive and happily producing values even when it never had taps or all its taps have been closed: - - my $r = Supplier.new; - my $z = $r.Supply; - $r.emit("A tree fell in the woods"); # - -A more common type of supply is an I<on-demand> supply, which creates multiple independent streams of events, starting a new stream each time it is tapped. Each C<Tap> receives only the events emitted on its private stream. For example, the factory method C<Supply.interval> produces a fresh timer with the appropriate interval each time it is tapped, each of which will stop emitting values when its corresponding C<Tap> is closed: - - my $i = Supply.interval(2); - my $tick = $i.tap({ say " tick $_" }); - sleep 3; # tick 0\n tick 1\n - my $tock = $i.tap({ say " tock $_" }); - sleep 3.5; # tock 0\n tick 2\n tock 1\n tick 3\n - $tock.close; - sleep 3; # tick 4\n - $tick.close; - -By default most C<Supply> objects are serial, meaning they will not emit simultaneous events (be they C<emit>, C<done>, or C<quit> events.) Other supplies are entirely asyncronous: it is possible for values to be pumped from an any number of asynchronous workers running on different threads. To tell the difference between the two, the C<.serial> method may be used. Note that calls to a C<Supplier>'s C<.emit>, C<.done>, or C<.quit> methods always block (and may deadlock in the presence of feedback) until all taps have been run -- the difference between a serial and a non-serial C<Supply> is when multiple threads call C<.emit> simultaneously: on a non-serial C<Supply>, multiple taps may run in parallel, one on each thread, each processing values emitted by that thread. On a serial C<Supply>, only one tap may run at the same time, and the threads calling C<.emit> may block on the taps processing each other's values, not just their own. Because of the semantic of "not emit simultaneous events" it is also guaranteed, on a serial C<Supply>, that all taps corresponding to one thread emission will complete before any of the taps from another thread's emission are run. - -The C<Supply> class has various methods that produce more interesting kinds of C<Supply>. These mostly produce serial supplies. Even the C<Supplier.Supply> method produces a serial supply -- to get a fully asyncronous live supply one must use the C<Supplier.unsanitized-supply> method. Most factory methods handle creation/retention/destruction of a C<Supplier> internally, or combine prexisting C<Supply> objects, so their users need only to concern themselves with C<Supply> objects. - -The following methods are class methods which create a new C<Supply> without requiring an existing C<Supply>. The methods C<merge>, C<zip> and C<zip-latest> also have class method forms, documented further below with their instance method counterparts. - -=over 4 - -=item from-list - - my $fl = Supply.from-list(^10); - -Takes a (potentially lazy) list of values, and returns an on-demand C<Supply> that, when tapped, will iterate over the values and invoke the C<Tap>'s C<emit> callable for each of them, and any C<done> callable at the end. If the iteration at some point produces an exception, then the C<Tap>'s C<quit> callable will be invoked to pass along the exception. - -=item interval - - my $e1 = Supply.interval(1); # Once a second, starting now - my $e5i10 = Supply.interval(5, 10); # Each 5 seconds, starting in 10 seconds - -Produces an on-demand C<Supply> that, when tapped, will produce successive integer values at a regular time interval, with the integer values counting up from 0. - -Take the returned tap object and close it to stop the ticks: - - my $e1 = Supply.interval(1).tap(&say); - # ...later... - $e1.close(); - -=back - -Supplies are mathematically dual to iterators, and so it is possible to define the same set of operations on them as are available on lazy lists. The key difference is that, while C<grep> on a lazy list I<pulls> a value to process, working synchronously, C<grep> on a Supply has values I<pushed> through it, and pushes those that match the filter onwards to anything that taps it. - -The following methods are available on an instantiated C<Supply> (C<$s> in these examples). Note that calling most of these methods on an on-demand C<Supply> does not constitute demanding a fresh set of values from the C<Supply> -- a tap is not immediately performed. Instead, tapping the resulting C<Supply> will do so, per C<Tap>. In other words, connected networks of Supplies do not sit around in the background pointlessly feeding each other values internally, they wait until something is listening. (This behavior is generally accomplished via C<whenever> clauses, described below.) - -=over - -=item list - - my @l := $s.list; - -Produces a lazy C<List> with the values of the C<Supply>. - -=item wait - - $s.wait; - -Waits until the specified C<Supply> is C<done> or C<quit>. In the latter case, throws the exception with which the C<Supply> was quit. - -=item Channel - - my $c = $s.Channel; - -Produces a C<Channel> of the values of the given C<Supply>. - -=item Promise - - my $p = $s.Promise; - -Produces a C<Promise> that will be kept when the C<Supply> is done or broken if it is quit. - -=item last - - my $l = $s.last(42); # default: 1 - -Produces a C<Supply> that will only emit the last N values of the given C<Supply> (after that C<Supply> is C<done>). Default is the final value. - -=item grab - - my $g = $s.grab( { .sort } ); # sort the values of a Supply - -Produces a C<Supply> which will cache all values emitted by the given C<Supply> until it is done. It will then call the given closure and then C<.emit> each of the return values of the closure, and then call C<.done> on itself. - -=item flat - - my $f = $s.flat; - -Produces a C<Supply> in which all values of the original supply are flattened then individually emitted. - -=item do - - my $seen; - my $d = $s.do( {$seen++} ); - -Produces a C<Supply> that is identical to the original supply, but will execute the given code for its side-effects, once for each emitted value, before running any taps. Only one thread will ever be executing the side-effect code at a time; others will block behind it. In addition to serializing the side-effect, the resulting supply is also serial, even if the one it was created from is not. The side-effect code is only run for emitted values, not when the original is quit or done. - -=item act - - my $seen; - $s.act( {$seen++} ); - -This is a special case of C<Supply>.do, that will also create a tap on the given C<Supply>, so that you only need to worry about writing the side-effect code. Returns the C<Tap>. - -=item grep - - my $g = $s.grep( * > 5 ); - my $g = $s.grep(Int); - -Produces a C<Supply> that only provides values that you want. Takes either a C<Callable> (which is supposed to return a C<True> value to pass on emitted values) or a value to be smartmatched against. - -=item map - -Analogous to C<List>'s C<.map> method, but produces a C<Supply>. - - my $m = $s.map( * * 5 ); - -Produces a C<Supply> that provides its original's Supply values multiplied by 5. - - my $m2 = $s.map( { $_ xx 2 } ); - -Produces a C<Supply> that provides its original's Supply values twice. - -=item unique - - my $u = $s.unique( :as( {$_} ), :with( &[===] ), :expires(1) ); - -Produces a C<Supply> that only provides unique values, as defined by the optional C<as> and C<with> named parameters (same as L<List.unique>). The optional C<expires> parameter specifies how long to wait (in seconds) before "resetting" and not considering a value to have been seen, even if it's the same as an old value. - -=item squish - - my $q = $s.squish( :as( {$_} ), :with( &[===] ), :expires(1) ); - -Produces a C<Supply> that only provides sequentially different values, as defined by the optional C<as> and C<with> named parameters (same as L<List.squish>). The optional C<expires> parameter specifies how long to wait (in seconds) before "resetting" and not squishing a new value with an old one, even if they are the same. - -=item max - - my $a = $s.max(&by); # default &infix:<cmp> - -Produces a C<Supply> that produces the B<maximum> values of the specified C<Supply>. In other words, from a continuously ascending C<Supply> it will produce all the values. From a continuously descending C<Supply> it will only produce the first value. The optional parameter specifies the comparator, just as with C<Any.max>. - -=item min - - my $i = $s.min(&by); # default &infix:<cmp> - -Produces a C<Supply> that produces the B<minimum> values of the specified C<Supply>. In other words, from a continuously descending C<Supply> it will produce all the values. From a continuously ascending C<Supply> it will only produce the first value. The optional parameter specifies the comparator, just as with C<Any.min>. - -=item minmax - - my $m = $s.minmax(&by); # default &infix:<cmp> - -Produces a C<Supply> that, for each value emitted, produces C<Range>s with the B<minimum> and B<maximum> values seen thus far on the specified C<Supply>. The optional parameter specifies the comparator, just as with C<Any.minmax>. - -=item batch - - my $b = $s.batch( :elems(100), :seconds(1) ); - -Produces a C<Supply> that batches the values of the given Supply by either the number of elements (using the C<elems> named parameter) or the maximum number of seconds (using the C<seconds> named parameter) or both. Values are grouped in a single array element when flushed. - -=item throttle - - my $t = $s.throttle( $elems, $seconds ); - -Produces a C<Supply> that throttles emitting the values of the given Supply on the created C<Supply> by the number of elements (specified by the first parameter) per number of seconds (specified by the second parameter). - -=item elems - - my $e = $s.elems($seconds?); # default: see all - -Produces a C<Supply> that, for each value emitted, produces the number of elements seen thus far in the given C<Supply>. You can also specify an interval to only see the number of elements seen once per that interval. - -=item rotor - - my $b = $s.rotor(@cycle); - -Produces a "rotoring" C<Supply> with the same semantics as List.rotor. - -=item delayed - - my $d = $s.delayed( 3.5 ); # delay supply 3.5 seconds - -Produces a C<Supply> that passes on the values of the given Supply with the given delay (in seconds). - -=item stable - - my $u = $s.stable( $seconds, :$scheduler ); - -Produces a C<Supply> that only passes on a value if it wasn't superseded by another value in the given time (in seconds). Optionally uses another scheduler than the default scheduler, using the C<scheduler> named parameter. - -=item start - - my $t = $s.start( {...} ); - -Takes a closure and, for each supplied value, schedules the closure to run on another thread. It then emits a Supply (resulting in us having a supply of supplies) that will either have a single value emitted and then be done if the async work completes successfully, or quit if the work fails. Useful for kicking off work on the thread pool if you do not want to block up the thread pushing values at you (maybe 'cus you are reacting to UI events, but have some long-running work to kick off). Usually used in combination with C<migrate>. - -=item migrate - - my $m = $t.migrate; - -Produces a continuous C<Supply> from a C<Supply>, in which each value is a C<Supply> which emits a value from the original C<Supply> unchanged. As soon as a new C<Supply> appears, it will close the previously emitted C<Supply> and send the next value from the original C<Supply> to the most recently emitted C<Supply> instead. Can be used in combination with C<schedule-on>. - -=item schedule-on - - my $o = $m.schedule-on( $scheduler ); - -This allows a C<Supply>'s emit/done/quit to be scheduled on another scheduler. Useful in GUI situations, for example, where the final stage of some work needs to be done on some UI scheduler in order to have UI updates run on the UI thread. - -=item reduce - - my $r = $s.reduce( {...} ); - -Produces a C<Supply> that will emit each reduction from the given C<Supply>, much like the triangular reduction metaoperator (C<[\...]>) on C<List>s. - -=item lines - - my $l = $s.lines; # chomp lines - my $l = $s.lines( :!chomp ); # do *not* chomp lines - -Produces a C<Supply> that will emit the characters coming in line by line from a C<Supply> that's usually created by some asynchronous I/O operation. The optional C<:chomp> named parameter indicates whether to remove line separators: the default is C<True>. - -=item words - - my $w = $s.words; - -Produces a C<Supply> that will emit the characters coming in word by word from a C<Supply> that's usually created by some asynchronous I/O operation. - -=item classify - - my $c = $s.classify( {.WHAT} ); # one Supply per type of value - my $h = $s.classify( %mapper ); - my $a = $s.classify( @mapper ); - -Produces a C<Supply> which emits C<Pair>s consisting of a classification value as C<.key>, and a C<Supply> as the C<.value>. That supply will then emit any values from the original C<Supply> which match the classifier. Parameters behave similar to C<List.classify>, but does not support multi-level classification. - -=item categorize - - my $c = $s.categorize( {@categories} ); - my $h = $s.categorize( %mapper ); - my $a = $s.categorize( @mapper ); - -Produces a C<Supply> in which emits C<Pair>s consisting of a classification value as C<.key>, and a C<Supply> as the C<.value>. That supply will then emit any values from the original C<Supply> which match the classification value. Unlike C<.classify>, more than one C<Pair> may be emitted per value emitted from the original C<Supply>. See C<List.categorize> for a description of the behavior of the parameters. - -=item reverse - - my $r = $s.reverse; - -Produces a C<Supply> that emits the values of the given Supply in reverse order. Please note that this C<Supply> will only start delivering values when the given C<Supply> is C<.done>, much like C<.grab>. - -=item sort - - my $o = $s.sort(&by); # default &infix:<cmp> - -Produces a C<Supply> that emits the values of the given Supply in sorted order. Please note that this C<Supply> will only start delivering values when the given C<Supply> is C<.done>. Optionally accepts a comparator C<Block>. - -=back - -There are some combinators that deal with bringing multiple supplies together: - -=over - -=item C<merge> - - my $m = $s1.merge($s2); - - my $m = Supply.merge(@s); # also as class method - -Produces a C<Supply> containing the values produced by given and the specified supply or supplies, and triggering C<done> once all of the supplies have done so. The resulting supply is serial, even if any or all of the merged supplies are not. - -=item C<zip> - - my $z = $s1.zip($s2); # defaults to :with( &[,] ) - - my $z = Supply.zip(@s, :with( &[,] )); # also as class method - -Produces a C<Supply> that pairs together items from the given and the specified supply or supplies, using C<< infix:<,> >> by default or any other user-supplied function with the C<with> named parameter. The resulting supply is serial, even if any or all of the zipped supplies are not. - -=item C<zip-latest> - - my $z = $s1.zip-latest($s2); # like zip, defaults to :with( &[,] ) - - my $z = Supply.zip-latest(@s, :with( &[,] )); # also a method on Supply. - - my $z = Supply.zip-latest( @s, :initial(42,63) ); # initial state - -Produces a C<Supply> that will emit tuples of values as soon as any combined Supply produces a value. Before any tuples are emitted, all supplies have to have produced at least one value. By default, it uses C<< infix:<,> >> to produce the tuples, but the named parameter C<with> can override that. The resulting supply is serial, even if any or all of the merged supplies are not. - -The named parameter C<initial> can optionally be used to indicate the initial state of the values to be emitted. - -=back - -[TODO: plenty more of these: while, until...] - -The above combinators which involve multiple source supplies need care in their implementation, since values may arrive at any point from each source, and possibly at the same time. To help write such combinators, the C<supply> block and C<whenever> clause are used. These, along with the C<react> block, are available for general use as well. - -A C<supply> block is a convenient way to create an on-demand C<Supply>. It is just a declaration and does not run until the C<Supply> is tapped (which may happen multiple times resulting in multiple runs/clones of the block.) Within a C<supply> block, emit can be used to emit values to the tapper, and done can be used to convey that there will be no more values. - - my $s = supply { - emit 'a value!'; - emit 'another!'; - done; - } - -The emit and done can be in nested scopes, and follow the same rules as C<gather> and C<take>, except they look for an enclosing C<supply> or C<react> rather than a C<gather>. There is no corresponding C<quit> statement: instead, any unhandled exception thrown inside of a supply block will be passed onwards using C<.quit>. - -Likewise, a C<whenever> clause also looks around itself lexotically for an enclosing C<supply> or C<react>. A C<whenever> clause takes a predicate which may be a C<Supply>, C<Channel>, C<Promise> or C<Iterable>, followed by a consequent block. These clauses guarantee that only one thread will enter their consequent or that of any other C<whenever> clause inside the same enclosing C<supply> or C<react> block at the same time -- blocking any C<.emit> call on a C<Supply> or leaving any additional values in a Channel's C<.send> queue in the scheduler. - - my $s = Supply.interval(1); - my $c = Channel.new; - my $l := (while $++ < 4 { NEXT { sleep 1 }; Int(now - BEGIN now) }); - my $p = Promise.in(3); - my %contended_hash; - start { - for 0..4 { sleep 1; $c.send($_); LAST { $c.close } } - } - react { - # This is safe, because the whenevers protect %contended_hash - whenever $s { %contended_hash{$_}++; done if $_ > 4 }; - whenever $c { %contended_hash{$_}++ }; - whenever $l { %contended_hash{$_}++ }; - whenever $p { %contended_hash{$_}++ }; - } - %contended_hash.say; # 0 => 3, 1 => 3, 2 => 3, 3 => 3, 4 => 2, 5 => 1, True => 1 - -A whenever with a C<Supply> as a predicate will tap that predicate when the enclosing block is run (assuming control reaches the whenever clause.) It will then offer its consequent block as the emit closure for the resulting C<Tap>. However, it is sometimes best just to think of a C<whenever> as a loop which runs once for each value produced by the predicate C<Supply>, using the produced values as the topic. Following this model, a C<QUIT> or C<LAST> phaser inside the consequent block may be used to provide a quit or done closure (respectively) to the C<Tap>. The resulting C<Tap> itself is ensconced internally, but may also be accessed as the return value of the entire whenever clause. This is not necessary just in order for a whenever to close its own tap: C<last> may be called from within the consequent to do so. Labels may be used as normal to close the taps of outer clauses. Closing the last active tap closes the generated C<Supply>. - -A whenever block with a C<Channel> as a predicate behaves analogously, running the closure once for every value sent to it by the scheduler, as if it were constantly calling C<.receive> on the C<Channel>. A C<Promise> predicate runs the block when the C<Promise> is kept or broken as if it were calling C<await>. An C<Iterable> predicate will start a new iterator when the whenever clause is run, entering the consequent closure for each value pulled from the C<Iterator>. In all such cases, a C<QUIT> block inside the C<whenever> will catch exceptions generated from within the predicate. Handling these exceptions will prevent C<.quit> from being called on the C<Supply> created by the block. - -Note that it is possible for control never to reach a C<whenever> clause when a C<supply> or C<react> block is run. In this case, the whenever clause has no effect. If control reaches a C<whenever> clause more than once (for example, if it is inside a loop) multiple taps on the predicate (which may be different each time) are created. A C<whenever> clause may also be executed later, after a C<supply> block has produced a C<Supply> which has then been tapped, or while waiting for a C<react> block to fall off the bottom. This could happen from inside another C<whenever> clause in response to an event, or from an externally added C<Tap>. This is legal, and dynamically adds a new tap (of the predicate) to the C<Supply> which caused this to happen. That is to say, once active, a C<Supply> may indeed use C<whenever> clauses to self-modify, as long as it was originally syntactically anchored to a C<supply> or C<react> block: - - my $s1 = Supply.interval(1).share; - my $s2 = supply { - whenever $s1 { - emit($_); - done if $_ > 4; - } - }; - $s2.tap({ - if 2 < $_ < 5 { - "MORE $_".say; - whenever $s1 { - "OHAI $_".say; - } - } - }); - sleep 10; - # MORE 3 - # MORE 4 - # OHAI 4 - # OHAI 5 - # OHAI 5 - -Destructuring subsignatures may be used with C<whenever> clause topics via pointy block syntax. - -A C<supply> block containing C<whenever> clauses will call C<done> on itself when all C<whenever> clause predicates (which have executed) have had C<.done>/C<quit>, C<.close>/C<.fail> or C<.keep>/C<.break> called on them, appropriately, or in the case of an C<Iterable> predicate, when the end has been reached. These conditions are equivalent to manually closing the clause with C<last>. - -A C<react> block will not wait to be tapped -- it will immediately run and then wait for a done or quit condition, after which point, control will resume below the C<react> block. - -=head1 System events exposed as Supplies - -System events, such as signals, or mouse events, can be exposed as Supplies. Because of lack of portability, these will most likely be implemented as third-party modules. - -Basic signal support is offered by the C<signal> function, which takes one or more C<Signal> enums, and an optional C<scheduler> named parameter. It produces a C<Supply> which, when tapped, will C<emit> any signal coming in. For example: - - signal(SIGINT).tap( { say "Thank you for your attention"; exit 0 } ); - -would catch Control-C, thank you, and then exit. Of course, you don't need to exit immediately. Here's an example of how you would make sure that an iteration in a loop is completed before exiting: - - for @todo { - state $quitting; - state $tap = signal(SIGINT).tap( { $quitting = True } ); - LAST $tap.close; - LEAVE exit(0) if $quitting; - ... # code to protect - } - -This probably could use some syntactic sugar. - -The list of supported C<Signals> can be found by checking C<Signal::.keys>, as you would any enum. - -=head1 I/O features exposed as Supplies - -Various I/O-related things are also exposed as supplies. For example, it is possible to get notifications on changes to files or files (directly) in a directory, using: - - IO::Notification.watch-path(".").tap(-> $file { - say "$file changed"; - }); - -This is quite a mouthful, so there is a shortcut available with the C<IO> coercer and the C<watch> method: - - ".".IO.watch.tap: -> $file { say "$file changed" }; - -Note that since I/O callbacks are, by default, scheduled on the thread pool, then it's possible that your callback will be executing twice on the same thread. One way to cope is with C<act>: - - ".".IO.watch.act(-> $file { - state %changes; - say "$file changed (change {++%changes{$file}})"; - }); - -It can also take C<done> and C<quit> named parameters; these go to the tap, while the C<emit> closure is put in a C<do>. A C<Tap> is returned, which may be closed in the usual way. (Note that the name C<act> is also a subtle reference to actor semantics.) - -=head1 Inter-Process Communication exposed as Promises and Supplies - -Starting external processes is rather easy: C<shell()>, C<run()> and C<qx//>. Having external processes run asynchronously, is slightly more involved. But not much. The workhorse of asynchronous IPC in Perl 6 is C<Proc::Async>: - - my $proc = Proc::Async.new( $path, @args ); - -If you like to B<send> data to the process, you need to open it with the C<:w> named parameter. - - my $proc = Proc::Async.new( $path, @args, :w ); - -By default, the current environment (as available in C<%*ENV>) will be set for the external process. You can override this with the :ENV named parameter: - - my $proc = Proc::Async.new( $path, @args, :ENV(%hash) ); - -The returned object can then be called whenever needed to start the external process. However, before you do that, one needs to be clear what to do about the output of the external process. Getting information back from the external process's C<STDOUT> or C<STDERR>, is done by a C<Supply> that either gets characters or bytes. - - $proc.stdout.act(&say); # simply pass it on to our $*OUT as chars - $proc.stderr.act(¬e); # and $*ERR as chars, but could be any code - -or: - - $proc.stdout(:bin).act: { # process STDOUT bytes }; - $proc.stderr(:bin).act: { # process STDERR bytes }; - -So, to make sure no information will be lost, you need to create and tap the supplies B<before> the process is started. - -To start the external process, you need to call the C<.start> method. It returns a C<Promise> that becomes C<Kept> (and True) if the process concludes successfully, or C<Broken> (and False) if the process failed for some reason. - - my $done = $proc.start( :$scheduler = $*SCHEDULER ); - -To send data to the running process, you can use the C<.print>, C<.say> and C<.write> methods on the C<Proc::Async> object: - - my $printed = $proc.print( "Hello world\n", :$scheduler = $*SCHEDULER ); - my $said = $proc.say( "Hello world", :$scheduler = $*SCHEDULER ); - my $written = $proc.write( $buffer, :$scheduler = $*SCHEDULER ); - -They all also return a C<Promise> that is C<Kept> when communication with the process was successful. - -Some programs expect their C<STDIN> to be closed to signify the end of their processing. This can be achieved with the C<.close-stdin> method: - - $proc.close-stdin; - -Finally, if your process as going awry, you can stop it with the C<.kill> method: - - $proc.kill; # sends HUP signal to process - $proc.kill("SIGINT"); # send INT signal - $proc.kill(1); # if you just know the signal number on your system - -The parameter should be something that is acceptable to the Kernel.signal method. - -=head1 The Event Loop - -There is no event loop. Previous versions of this synopsis mentioned an event loop that would be underlying all concurrency. In this version, this is not the case. - -=head2 Threads - -VM-level threads, which typically correspond to OS-level threads, are exposed through the C<Thread> class. Whatever underlies it, a C<Thread> should always be backed by something that is capable of being scheduled on a CPU core (that is, it may I<not> be a "green thread" or similar). Most users will not need to work with C<Thread>s directly. However, those building their own schedulers may well need to do so, and there may be other exceptional circumstances that demand such low-level control. - -The easiest way to start a thread is with the C<start> method, which takes a C<Callable> and runs it on a new thread: - - my $thread = Thread.start({ - say "Gosh, I'm in a thread!"; - }); - -It is also possible to create a thread object, and set it running later: - - my $thread = Thread.new(code => { - say "A thread, you say?"; - }); - # later... - $thread.run(); - -Both approaches result in C<$thread> containing a C<Thread> object. At some point, C<finish> should be called on the thread, from the thread that started it. This blocks until the thread has completed. - - say "Certainly before the thread is started"; - my $thread = Thread.start({ say "In the thread" }); - say "This could come before or after the thread's output"; - $thread.finish(); - say "Certainly after all the above output"; - -As an alternative to C<finish>, it is possible to create a thread whose lifetime is bounded by that of the overall application. Such threads are automatically terminated when the application exits. In a scenario where the initial thread creates an application lifetime thread and no others, then the exit of the initial thread will cause termination of the overall program. Such a thread is created by either: - - my $thread = Thread.new(:code({ ... }), :app_lifetime); - -Or just, by using the C<start> method: - - my $thread = Thread.start({ ... }, :app_lifetime); - -The property can be introspected: - - say $thread.app_lifetime; # True/False - -Each thread also has a unique ID, which can be obtained by the C<id> property. - - say $thread.id; - -This should be treated as an opaque number. It can not be assumed to map to any particular operating system's idea of thread ID, for example. For that, use something that lets you get at OS-level identifiers (such as calling an OS API using NativeCall). - -A thread may also be given a name. - - my $thread = Thread.start({ ... }, :name<Background CPU Eater>); - -This can be useful for understanding its usage. Uniqueness is not enforced; indeed, the default is "<anon>". - -A thread stringifies to something of the form: - - Thread<id>(name) - -For example: - - Thread<1234>(<anon>) - -The currently executing thread is available through C<$*THREAD>. This is even available in the initial thread of the program, in this case by falling back to C<$PROCESS::THREAD>, which is the initial thread of the process. - -Finally, the C<yield> method can be called on C<Thread> (not on any particular thread) to hint to the OS that the thread has nothing useful to do for the moment, and so another thread should run instead. - -=head2 Atomic Compare and Swap - -The Atomic Compare and Swap (CAS) primitive is directly supported by most modern hardware. It has been shown that it can be used to build a whole range of concurrency control mechanisms (such as mutexes and semaphores). It can also be used to implement lock-free data structures. It is decidedly a primitive, and not truly composable due to risk of livelock. However, since so much can be built out of it, Perl 6 provides it directly. - -A Perl 6 implementation of CAS would look something like this: - - sub cas($ref is rw, $expected, $new) { - my $seen = $ref; - if $ref === $expected { - $ref = $new; - } - return $seen; - } - -Except that it happens atomically. For example, a crappy non-reentrant mutex could be implemented as: - - class CrappyMutex { - has $!locked = 0; - - method lock() { - loop { - return if cas($!locked, 0, 1) == 0; - } - } - - method unlock() { - $!locked = 0; - } - } - -Another common use of CAS is in providing lock-free data structures. Any data structure can be made lock-free as long as you're willing to never mutate it, but build a fresh one each time. To support this, there is another C<&cas> candidate that takes a scalar and a block. It calls the block with the seen initial value. The block returns the new, updated value. If nothing else updated the value in the meantime, the reference will be updated. If the CAS fails because another update got in first, the block will be run again, passing in the latest value. - -So, atomically incrementing a variable is done thusly: - - cas $a, { $_.succ }; # $a++ - -or more generally for all assignment meta-operators: - - cas $a, { $_ * 5 }; # $a *= 5 - -Another example, implementing a top-5 news headlines list to be accessed and updated without ever locking, as: - - class TopHeadlines { - has $!headlines = []; # Scalar holding array, as CAS needs - - method headlines() { - $!headlines - } - - method add_headline($headline) { - cas($!headlines, -> @current { - my @new = $headline, @current; - @new.pop while @new.elems > 5; - @new - }); - } - } - -It's the programmer's duty to ensure that the original data structure is never mutated and that the block has no side-effects (since it may be run any number of times). - -=head1 Low-level primitives - -Perl 6 offers high-level concurrency methods, but in extreme cases, like if you need to implement a fundamentally different mechanism, these primitives are available. - -=head2 Locks - -Locks are unpleasant to work with, and users are pushed towards higher level synchronization primitives. However, those need to be implemented via lower level constructs for efficiency. As such, a simple lock mechanism - as close to what the execution environment offers as possible - is provided by the C<Lock> class. Note that it is erroneous to rely on the exact representation of an instance of this type (for example, don't assume it can be mixed into). Put another way, treat C<Lock> like a native type. - -A C<Lock> is instantiated with C<new>: - - $!lock = Lock.new; - -The best way to use it is: - - $!lock.protect: { - # code to run with the lock held - } - -This acquires the lock, runs the code passed, and then releases the lock. It ensures the lock will be released even if an exception is thrown. It is also possible to do: - - { - $!lock.lock(); - # do stuff - LEAVE $!lock.unlock() - } - -When using the C<lock> and C<unlock> methods, the programmer must ensure that the lock is unlocked. C<Lock> is reentrant. Naturally, it's easy to introduce deadlocks. Again, this is a last resort, intended for those who are building first resorts. - -=head2 Semaphore - -The C<Semaphore> class implements traditional semaphores that can be initiated with a fixed number of permits and offers the operations C<acquire> to block on a positive number of permits to become available and then reduce that number by one, C<tryacquire> to try to acquire a permit, but return C<False> instead of blocking if there are no permits available yet. The last operation is C<release>, which will increase the number of permits by one. - -The initial number of permits may be negative, positive or 0. - -Some implementations allow for race-free acquisition and release of multiple permits at once, but this primitive does not offer that capability. - -=head1 AUTHORS - - Jonathan Worthington <jnthn@jnthn.net> - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S19-commandline.pod b/S19-commandline.pod deleted file mode 100644 index e3ed7e44..00000000 --- a/S19-commandline.pod +++ /dev/null @@ -1,607 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 19: Command Line Interface - -=head1 VERSION - - Created: 12 Dec 2008 - - Last Modified: 06 Oct 2014 - Version: 28 - -This is a draft document. This document describes the command line interface. -It has changed extensively from previous versions of Perl in order to increase -clarity, consistency, and extensibility. Many of the syntax revisions are -extensions, so you'll find that much of the Perl 5 syntax embedded in your -muscle memory will still work. - -Notable features described in the sections below include: - -=over 4 - -=item * - -A smart default command-line processor in the core - -=item * - -All options have a long, descriptive name for increased clarity - -=item * - -Common options have a short, single-character name, and allow clustering - -=item * - -Extended option syntax provides the ability to set boolean true/false - -=item * - -New C<++> metasyntax allows options to be passed through to subsystems - -=back - -This interface to Perl 6 is special in that it occurs at the intersection of -the program and the operating system's command line shell, and thus is not -accessed via a consistent syntax everywhere. A few assumptions are made here, -which will hopefully stand the test of time: All command-line arguments are -assumed to be in Unicode unless proven otherwise; and Perl is born of Unix, -and as such the syntax presented in this document is expected to work in a -Unix-style shell. To explore the particularities of other operating systems, -see L<Synopsis 25|S25-portability> (TBD). - - -=head1 Command Line Elements - -The command line is broken down into two basic elements: a I<program>, and -I<arguments>. Each command line element is whitespace separated, so elements -containing whitespace must be quoted. The I<program> processes the arguments -and performs the requested actions. For rakudo compiled with both MoarVM and JVM backends, -respectively C<perl6-m> and C<perl6-j>. With one compiled backend, -the command can be shortened to C<perl6> It is followed by zero or more I<arguments>. -The I<program> portion of the command -line is made available at run-time via the C<< PROCESS::<$PROGRAM> >> -variable (normally accessed as C<$*PROGRAM>) as an C<IO::Path>. - -Command line I<arguments> are broken down into I<options> and I<values>. -Each option may take zero or more values. After all options have been -processed, the remaining values (if any) generally consist of the name of a -script for Perl to execute, followed by arguments for that script. If no -values remain, Perl 6 implicitly opens STDIN to read the script. If you wish -to pass arguments to a script read from STDIN, you must specify STDIN by name -(C<-> on most operating systems). - - -=head1 Backward (In)compatibility - -You may find yourself typing your favorite Perl 5 options, even after -Christmas has arrived. As you'll see below, common options are provided -which behave similarly. Less common options, however, may not be available -or may have changed syntax. If you provide Perl with unrecognized command-line -syntax, Perl gives you a friendly error message. If the unrecognized -syntax is a valid Perl 5 option, Perl provides helpful suggestions to allow -you to perform the same action using the current syntax. - - -=head2 Unchanged Syntactic Features - -Several features have not changed from Perl 5, including: - -=over 4 - -=item * - -The most common options have a single-character short name - -=item * - -Single-character options may be clustered with the same syntax and semantics - -=item * - -Many command-line options behave similarly, for example: - - Option... Still means... - -a Autosplit - -c Check syntax - -e *line* Execute - -F *expression* Specify autosplit field separator - -h Display help and exit - -I *directory*[,*directory*[,...]] Unshift CompUnitRepo::Local('s) to @?INC - -n Act like awk - -p Act like sed - -S Search PATH for script - -T Enable taint mode - -v Display version info - -V Display verbose config info - -All of these options have extended syntax, and some may have slightly -different semantics, so see L</"Option Reference"> below for the details. - -=back - - -=head2 Removed Syntactic Features - -Some Perl 5 command-line features are no longer available, either because -there's a new and different way to do it in Perl 6, or because they're -no longer relevant. Here's a breakdown of what's been removed: - -=over 4 - -=item -0 *octal/hex* - -Sets input record separator. Missing due to lack of specification in -L<Synopsis 16|S16-io>. There is a comment about this in the L</"Notes"> -section at the end of this document. - -=item -C *number/list* - -Control Unicode features. Perl 6 has Unicode semantics and assumes a -UTF-8 command-line interface (until proven otherwise, at which point this -functionality may be readdressed). - -=item -d, -dt, -d:foo, -D, etc. - -Debugging commands. Replaced with the C<++BUG> metasyntactic option. - -=item -E *line* - -Execute a line of code, with all features enabled. This is specific to -Perl 5.10, and not relevant to Perl 6, where C<-e> performs this function. - -=item -i *extension* - -Modify files in-place. Haven't thought about it enough to add yet, but -I'm certain it has a strong following. {{TODO review decision here}} - -=item -l - -Enable automatic line-ending processing. This is the default behavior. - -=item -M *module*, -m *module*, etc. - -use/no module. Replaced by C<--use>. - -=item -P - -Run option through C preprocessor. This caused problems for Perl 5, and is completely obsolete now. - -=item -s - -Enable rudimentary switch parsing. By default, Perl 6 parses the -arguments passed to a script using the signature supplied by the user -in the MAIN routine (see L<S06/"Declaring a MAIN subroutine">). - -=item -t - -Enable taint warnings mode. Taint mode needs more thought, but it's -much more likely that the C<-T> switch will take options rather than -use a second command-line flag to implement related behavior. - -=item -u - -Dump the core after parsing the program. This has been deemed obsolete. - -=item -U - -Allow unsafe operations. This is extremely dangerous and infrequently -used, and doesn't deserve its own command-line option. - -=item -w - -Enable warnings. This is the default behavior. - -=item -W - -Enable all warnings. This is infrequently used, and doesn't deserve its -own command-line option. - -=item -X - -Disable all warnings. This is infrequently used, and doesn't deserve its -own command-line option. - -=back - - -=head1 Options and Values - -Command line options are parsed using the following rules: - -=over 4 - -=item * - -Options must begin with one of the following symbols: C<-->, C<->, or C<:>. - -=item * - -Options are case sensitive. C<-o> and C<-O> are not the same option. - -=item * - -All options have a multi-character, descriptive name for increased clarity. -Multi-character option names always begin with C<--> or C<:>. - -=item * - -Common options have a short, one-character name for speed. -Single-character names always begin with C<->. - -=item * - -Single-character options may be clustered. C<-ab> means C<-a -b>. When a -single-character option which requires a value is clustered, the option may -appear only in the final position of the cluster. - -=item * - -Options may be negated with C</>, for example C<--/name>, C<:/name>, C<-/n>. -Negated single-character options cannot appear in a cluster. In practice, -negated options are rare anyway, as most boolean options default to False. - -=item * - -Option names follow Perl 6 identifier naming convention, except C<'> is not -allowed, and single-character options may be any character or number. - -=item * - -The special option C<--> and C<< -e <program> >> signal the parser to stop -option processing. Arguments following a bare C<--> (with no identifier) -or a C<-e> are always parsed as a list of values, even if they look like -valid options. - -=back - - -Delimited options allow you to transparently pass one or more options through to -a subsystem, as specified by the special options that delimit those options. -They are parsed according to the following rules: - -=over 4 - -=item * - -The opening and closing delimiters begin with two or more plus characters, -for example C<++>. You'll usually use two plus characters, but more are -allowed to avoid ambiguity when nesting delimited options. - -=item * - -Opening and closing delimited option names follow option identifier naming -convention, defined above. - -=item * - -If the closing delimiter is omitted, the rest of the command line is consumed. - -=item * - -Inside a delimited option, the C<--> option does not suppress searching for -the closing delimiter. That is, only the rest of the arguments within -the delimiters are treated as values. - -=item * - -Eager matching semantics are used, so the first closing delimiter found -completes the match. - -=item * - -Delimited options cannot be negated. However, the final delimiter takes -a slash indicating the termination of the delimited processing, much -like a closing HTML tag. - -=back - -These options are made available in dynamic variables matching their name, -and are invisible to C<MAIN()> except as C<< %*OPTSZ<><name> >>. For example: - - ++PARSER --setting=Perl6-autoloop-no-print ++/PARSER - -is available inside your script as C<< %*OPTSZ<><PARSER> >>, and contains -C<--setting=Perl6-autoloop-no-print>. Since eager matching is used, if you -need to pass something like: - - ++foo -bar ++foo baz ++/foo ++/foo - -you'll end up with - - %*OPTS<foo> = '-bar ++foo baz'; - -which is probably not what you wanted. Instead, add extra C<+> characters - - +++foo -bar ++foo baz ++/foo +++/foo - -which will give you - - %*OPTS<foo> = '-bar ++foo baz ++/foo'; - -allowing you to properly nest delimited options. - -The actual storage location of C<%*OPTS> may be either in C<< PROCESS::<%OPTS> >> -or C<< GLOBAL::<%OPTS> >>, depending on how the process sets up its interpreters. - - -Values are parsed with the following rules: - -=over 4 - -=item * - -Values are passed to options with the following syntax C<--option=value> -or C<--option value>. - -=item * - -Values containing whitespace must be enclosed in quotes, for example -C<-O="spacey value"> - -=item * - -Multiple values are passed by specifying multiple instances -of the option, as in C<--option=val1 --option='val 2'>. - -=back - -=head2 Remaining arguments - -Any remaining arguments to the Perl 6 program are placed in the C<@*ARGS> array. - -=head1 Option Reference - -Perl 6 options, descriptions, and services. - -=head2 Synopsis - - multi sub perl6( - Bool :a($autoloop-comb), - Bool :c($check-syntax), - Bool :$doc, - :e($execute), - :F($autoloop-delim), - Bool :h($help), - :I(@include), - :L($language), - Bool :n($autoloop-no-print), - :O($output-format), - Bool :p($autoloop-print), - Bool :S($search-path), - Bool :T($taint), - :u($use), - Bool :v($version), - Bool :V($verbose-config), - Bool :x($extract-from-text), - ); - -=head2 Reference - -=over 4 - -=item --autoloop-comb, -a - -When used with C<-n> or C<-p>, implicitly combs input and assigns the -result to C<@_> within the loop produced by the C<-n> or C<-p>. - -The default pattern is C</\S+/>, an alternate pattern for comb may be -specified with C<--autoloop-pattern>, a.k.a. C<-F>. - -=item ++CMD --command-line-parser *parser* ++/CMD - -Add a command-line processor. When this option is parsed, it immediately -triggers an action that affects or replaces the command-line parser. -Therefore, it is a good idea to put this option as early as possible in the -argument list. - -=item --check-syntax, -c - -Check syntax, then exit. Desugars to C<-e 'CHECK { compiles_ok(); exit; }'>. - -=item --doc - -Lookup Perl documentation in Pod format. Desugars to -C<-e 'CHECK { compiles_ok(); dump_perldoc(); }'>. C<@*ARGS> contains the -arguments passed to C<perl6>, and is available at C<CHECK> time, so -C<dump_perldoc()> can respond to command-line options. - -{{TODO may create a ++DOC subsystem here. also, may use -d for short name, -even though it clashes with perl 5}} - -=item ++BUG [*switches*, *flags*] ++/BUG - -Set switches and flags for the debugger. - -Note: The debugger needs further specification. - -=item --execute, -e *line* - -Execute a single-line program in lax mode. - -If you don't wish to run in lax mode, but with strictures and warnings enabled, -pass 'use strict;' at the -e on the command line, -like C<-e 'use strict; my $x = 42'>. - -=item --autoloop-delim, -F *expression* - -Pattern to split on (used with -a). Substitutes an expression for the default -split function, which is C<{split ' '}>. Accepts Unicode strings (as long as -your shell lets you pass them). Allows passing a closure -(e.g. -F "{use Text::CSV}"). Awk's not better any more :) - -=item --help, -h - -Print summary of options. Desugars to C<++CMD --print-help --exit ++/CMD>. - -=item --include, -I location[,Class=location[,...]] - -Prepend C<CompUnitRepo>'s to @?INC, for ad hoc module searching. The -L<CompUnitRepo::Local::File> class will be assumed if no class has been -specified. Any class specified should adhere to the L<CompUnitRepo> interface. -In any Searching the standard library follows the policies laid out in -L<Synopsis 11|S11-modules>. - -=item --language, -L *dsl* - -Set the domain specific language for parsing the script file. (That is, -specify the I<setting> (often known as the prelude) for the program.) -C<++PARSER --setting=*dsl* ++/PARSER>. - -=item --autoloop-no-print, -n - -Act like awk. Desugars to -C<++PARSER --setting=Perl6-autoloop-no-print ++/PARSER>. - -=item --output-format, -O *format* - -Emit compiler output to STDOUT in the specified format, rather than invoking -the compiled code immediately. This option is implementation-specific, so -consult the documentation for your Perl 6 implementation for further details. - -=item --autoloop-print, -p - -Act like sed. Desugars to -C<++PARSER --setting=Perl6-autoloop-print ++/PARSER>. - -=item --search-path, -S - -Use PATH environment variable to search for script specified on command-line. - -=item --taint, -T - -Turns on "taint" checking. See L<Synopsis 23|S23-security> for details. -Commits very early. Put this option as early on the command-line as possible. - -=item --use, -u *module* - -C<--use *module*> and C<-u *module*> desugars to C<-e 'use *module*'>. -Specify version info and import symbols by appending info to the module name: - - -u'Sense:auth<cpan:JRANDOM>:ver<1.2.1> <common @horse>' - -You'll need the quotes so your shell doesn't complain about redirection. -There is no special command-line syntax for C<'no *module*>, use C<-e>. - -=item --version, -v - -Display program name, version, patchlevel, etc. Desugars to -C<++CMD -v ++/CMD ++PARSER -v ++/PARSER ++BUG -v ++/BUG>. - -=item --verbose-config, -V - -Display configuration details. Desugars to -C<++CMD -V ++/CMD ++PARSER -V ++/PARSER ++BUG -V ++/BUG>. - -=item --extract-from-text, -x - -Run program embedded in Unicode text. Scan for the first line starting -with C<#!> and containing the word C<perl>, and start there instead. -This is useful for running a program embedded in a larger message. -(In this case you would indicate the end of the program using the C<=END> -block, as defined in L<Synopsis 26|S26-documentation/"The =END block">.) - -Desugars to C<--PARSER --Perl6-extract-from-text --/PARSER>. - -=back - - -=head1 Metasyntactic Options - -Metasyntactic options are a subset of delimited options used to pass arguments -to an underlying component of Perl. Perl itself does not parse these options, -but makes them available to run-time components via the C<%*META-ARGS> dynamic -variable. - -Standard in Perl 6 are three underlying components, C<CMD>, C<PARSER>, -and C<BUG>. Implementations may expose other components via this -interface, so consult the documentation for your Perl 6 implementation. - - On command line... Subsystem gets... - ++X a -b ++/X a -b - - # Nested options - +++X a -b ++X -c ++/X -d e +++/X a -b ++X -c ++/X -d e - - # More than once (both are valid, but the second form is preferred) - ++X a -b ++/X -c ++X -d e ++/X a -b -d e - +++X a -b +++/X -c ++X -d e ++/X a -b -d e - - -=head1 Environment Variables - -Environment variables may be used to the same effect as command-line -arguments. - -=over 4 - -=item PATH - -Used in executing subprocesses, and for finding the program if the -S switch -is used. - -=item PERL6LIB - -A list of directories in which to look for ad hoc Perl library files. - -Note: this is speculative, as library loading is not yet specified, -except insofar as S11 mandates various behaviors incompatible with -mere directory probing. - -=item PERL6OPT - -Default command-line arguments. Arguments found here are prepended to the -list of arguments provided on the command-line. - -=back - - -=head1 References - -=over 4 - -=item L<http://perldoc.perl.org/perlrun.html> - -=item L<http://search.cpan.org/dist/Getopt-Long/lib/Getopt/Long.pm> - -=item L<http://search.cpan.org/dist/Getopt-Euclid/lib/Getopt/Euclid.pm> - -=item L<http://design.perl6.org/S06.html#Declaring_a_MAIN_subroutine> - -=item L<http://search.cpan.org/dist/Perl6-Pugs/docs/Pugs/Doc/Run.pod> - -=item L<http://haskell.org/ghc/docs/latest/html/users_guide/using-ghc.html> - -=item L<http://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html> - -=back - - -=head1 Notes - -I'd like to be able to adjust the input record separator from command line, -for instance to specify the equivalent of perl 5's C<$/ = \32768;>. So far, -I don't have a solution, but perhaps pass a closure that evaluates to an Int? -This should try to use whatever option does the same thing to a new -filehandle when S16 is further developed. - -=begin consideration - -[probably a setter method on $*IN of some sort? --law] - -Sandboxing? maybe -r - -Env var? maybe -E. -Could be posed in terms of substituting a different setting. - -=end consideration - -=head1 AUTHORS - - Jerry Gay <jerry.gay@rakudoconsulting.com> - Moritz Lenz <moritz@cpan.org> - -=for vim:set expandtab sw=4: diff --git a/S21-calling-foreign-code.pod b/S21-calling-foreign-code.pod deleted file mode 100644 index 2a8a8285..00000000 --- a/S21-calling-foreign-code.pod +++ /dev/null @@ -1,322 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 21: Calling Foreign Code - -=head1 VERSION - - Created: 27 Feb 2009 - - Last Modified: 23 Nov 2012 - Version: 2 - -The document is a draft. - -=head1 SYNOPSIS - - use NativeCall; - - sub native_function(int arg) is native('libsomething') { * } - sub short_name() is native('libsomething') is symbol('long_and_complicated_name') { * } - - native_function(42); - -=head1 DESCRIPTION - -Perl 6 has a standard foreign function interface, NativeCall. The only -libraries NativeCall is able to interface with are those written in C. -Languages like Fortran and C++ require name mangling, which is -compiler-specific and thus falls well beyond the scope of this specification. - -Hypotheticals: - -=over - -=item -This is likely not an exhaustive list of showstoppers for C++/Fortran compat; -also, some platforms may be tricky simply in terms of C interop as well - -=back - -=head2 Calling foreign code - -A sub is marked as a native routine with the C<is native> trait. A native sub -must have an attached signature, which is used to specify the native-level -argument structure of the function. If the return type of the function is -C<Mu> the native function returns no value, any other return type must be -compatible with the types specified in the next section. - -=head3 The C<is native> trait - - sub trait_mod:<is>(Routine $r, :$native!) is export(:DEFAULT, :traits) { ... } - -The C<is native> trait is the main gateway used to access C libraries. A -routine with this trait applied will not be a normal Perl 6 callable, but will -call into the function with the same name in the specified library. - -The library name passed to C<is native> is passed unmodified to -L<man:dlopen(3)> or the platform's equivalent and the symbol is the looked for -in the handle returned from the call to C<dlopen>. If the library name is an -undefined value or the empty string, the symbol will be searched for in the -currently loaded libraries of the process; that is, behaviour consistent with -C<dlsym(RTLD_DEFAULT, symbol)> in C. - -Hypotheticals: - -=for item -Perl 6 allows a greater range of characters in identifiers than C. Should we -look for cases where the identifier isn't legal in C? - -=for item -This is rather UNIX-centric. Other platforms may very well complicate things. - -=head3 The C<is symbol> trait - - sub trait_mod:<is>(Routine $r, :$symbol!) is export(:DEFAULT, :traits) { ... } - -Since all symbols in a C library share a single namespace with all other -libraries, it is common practice to prefix externally visible symbols with a -library prefix so as not to interfere with other libraries. In Perl 6 this may -be a nuisance, and the C<is symbol> trait lets a user specify a different -symbol name to search for than the name of the sub. - -A native sub also adorned with C<is symbol> will search for the symbol -specified in the symbol trait, rather than the name of the subroutine itself. - -=head3 The C<is nativeconv> trait - - sub trait_mod:<is>(Routine $r, :nativeconv!) is export(:DEFAULT, :traits) { ... } - -Native code typically supports several different calling conventions. If a -convention different than the default one is needed, it is specified with C<is -nativeconv($convention)>. The conventions supported are platform-specific. - -=head3 The C<is encoded> trait - - sub trait_mod:<is>(Routine $r, :encoded!) is export(:DEFAULT, :traits) { ... } - sub trait_mod:<is>(Parameter $p, :encoded!) is export(:DEFAULT, :traits) { ... } - -Input arguments and return values that are strings may be returned in any of a -multitude of encodings. If the value is encoded differently from UTF-8, it -must be stated explicitly. - -=head3 Global variables - -Caveat emptor: This whole section is conjectural. - -Just like functions exported by a library, global variables are accessed with -the C<is native> trait; after all, all exported symbols are the same from the -point of view of the linker: a pointer to something. The C<is symbol> and -C<is encoding> (for strings) traits also apply to variables. - -=head2 Marshalling and demarshalling of Perl 6 data - -The raw internal representation of most Perl 6 objects can't be expected to -work sensibly with native code. To specify how to marshal and demarshal -complex Perl 6 objects, representation polymorphism is most frequently used, -but some classes are provided for frequent use cases. - -For pointer types, the type object associated with the Perl 6 class represents -the null pointer. - -=head3 Numeric types - -Numeric types, both native types and not, have obvious marshalling semantics -(as long as they are not arbitrary-precision types). A NativeCall -implementation should support the following types: - -=over - -=item C<int8>, C<uint8> signed and unsigned byte - -=item C<int16>, C<uint16> signed and unsigned two-byte integer - -=item C<int32>, C<uint32> signed and unsigned four-byte integer - -=item C<int64>, C<uint64> signed and unsigned eight-byte integer - -=item C<int>, C<uint> signed and unsigned machine word - -=item C<Int> largest available integer type - -=item C<num32> four-byte floating point number - -=item C<num>, C<num64> eight-byte floating point number - -=back - -Hypotheticals: - -=over - -=item -This is a wider range of native types than what S02 mandates. We'll either -want to expand that list of natives, or find some other way of specifying -sizes. - -=item -There is no obvious mirror of C<Int> for largest available I<unsigned> type. - -=item -Should C<Num> be a synonym for C<num>/C<num64>? - -=item -If the Int or Num type object is passed, should it be silently converted to a -zero value, or cause an exception? - -=item -How should overflows be handled? - -=back - -=head3 Strings - - multi explicitly-manage(Str $x is rw, :$encoding = 'utf8') is export(:DEFAULT, :utils) { ... } - -By default, a string passed to a native sub wil be marshalled to a C<char *> -appropriately encoded as specified with the C<is encoded> trait. The memory -allocated to the C string is freed when the function returns. If a C<Str> -object should have a persistent C<char *> associated with it, this can be -signalled by calling C<explicitly-manage($str, $encoding)>. The buffer -allocated will never be freed. - -A string-valued native sub's return value will be unmarshalled according to -the C<is encoded> trait, and the C pointer is not freed as deciding whether -the caller or callee owns the data can't be decided automatically, and freeing -by default risks causing later code to access freed memory. - -Hypotheticals: - -=over - -=item -We need better facilities for signaling when it's appropriate to free data. -The current facilities have the benefit that it won't cause memory-related -errors later on, but on the flip side, it will leak memory over time. - -=back - -=head3 The C<OpaquePointer> class - - class OpaquePointer is repr('CPointer') { } - -The C<OpaquePointer> type is the simplest possible way to interface with C -pointers, and can be seen as similar to the C<void *> type in C. An -C<OpaquePointer> offers no way to inspect the pointer or manipulate it; it can -only be passed around in the program and back to C. - -=head3 The C<CPointer> REPR - - typedef struct _magic magic; - magic *magic_new(void); - void magic_perform(magic *m); - - class Magic is repr('CPointer') { - my Magic sub magic_new() is native('libmagic') { * } - my sub magic_perform(Magic $m) is native('libmagic') { * } - - method new() { magic_new(); } - method perform() { magic_perform(self); } - } - -The C<CPointer> REPR enables types that are similar to C<OpaquePointer> in -that they cannot be introspected or mutated, but different in that they can -have methods. This makes it easy to interface with "object-oriented" C code -that returns an opaque pointer handle that encapsulate the resources used by -the library and lets us implement this naturally using Perl 6 OO. - -A C<CPointer> object can not have attributes. - -=head3 The C<CArray> class - - class CArray[::Type] does Positional[Type] is export(:DEFAULT, :types) { ... } - -General Perl 6 arrays support features such as laziness, which means that they -can not easily be marshalled into a C representation. Thus, NativeCall -provides the CArray type which supports a set of array features compatible -with marshalling to and from C. The C<Type> parameter is, of course, mandatory -as the exact layout of the array in memory depends on the type of the elements. - -A C<Carray> that has been marshalled from a value returned from C cannot, -given how arrays work in C, know the bounds of the array. Thus, it is the -I<user's> responsibility to ensure that all accesses are within the bounds of -the array. NativeCall will make no attempt to figure this out, and requests -for array elements outside of the array is likely to result in death by -segmentation fault. - -If the C<CArray> has been created in Perl 6, the bounds of the array are -known, and operations can be bounds-checked and the array grown appropriately. -Note, however, that growing an array may result in its C representation being -moved to a different memory location. Thus, if a piece of C code has stored -the location of an array and it is later on moved due to operations on the -Perl side, strange bugs and segfaults are likely to ensue. - -=head3 The C<CStruct> REPR - - class StructObject is repr('CStruct') { ... } - -Structs are an important part of most non-trivial C APIs; using the C<CStruct> -REPR, arbitrary structs can be accessed just like ordinary Perl 6 classes. - -=head3 Callable objects - -Callback arguments are, in essence, no different from normal data. They are -declared as callables (typically with the C<&> sigil) and also have an -attached signature. The signature is important as the callback handling code -needs this information to get the function's arguments off the stack. - -Callbacks returned from C are specified identically, but as return values -rather than parameters (note: callbacks returned from C NYI). - -=head3 Complex data value types - -Caveat emptor: This section, like the one on global variables, is all -conjecture. Nothing is implemented. - -In Perl 6 the distinction between value type and reference is intrinsic to the -type. In C, on the other hand, any type can be used both as a value and -reference type, depending on how it's used. Thus, NativeCall needs some -mechanism to duplicate this. One possible source of inspiration for this is -C#. C# distinguishes between value and reference types similarly to Perl 6 and -also has a well-supported foreign function interface. - -=head3 Varargs -To be determined. This section is hypothetical. - -One option is an API similar to the C99 C<stdarg.h> macros and explicitly get -arguments off an opaque object. For example C<my $arg = va_arg($args, Type)>. - -=head2 Miscellaneous helper functions - -=head3 Refreshing outdated objects - - multi refresh($obj) is export(:DEFAULT, :utils) { { ... } - -To avoid unmarshalling data from the C representation whenever data is -accessed, an efficient implementation is going to want to cache unmarshalled -data. Whenever a complex object is passed to a native subroutine, the -implementation should make sure the cache data isn't out of date. However, if -the C code saves a pointer passed to it and a later invocation mutates the -data pointed to, NativeCall can't magically detect this. In cases like this, -the user will have to use C<refresh> to invalidate any outdated objects in the -cache. - -Hypotheticals: - -=over - -=item -Sometimes it will be necessary to reinterpret a pointer-valued object as a -different kind of pointer. One way to provide this would be a function a la: -C<my $val = reinterpret($ptr, Type)>. - -=back - -=head1 AUTHORS - - Arne Skjærholt <arnsholt@gmail.com> - Jonathan Worthington <jnthn@jnthn.net> - -=for vim:set expandtab sw=4: diff --git a/S22-package-format.pod b/S22-package-format.pod deleted file mode 100644 index e5afbfc3..00000000 --- a/S22-package-format.pod +++ /dev/null @@ -1,863 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 22: Distributions, Recommendations, Delivery and Installation - -=head1 VERSION - - Created: 15 March 2014 - - Last Modified: 27 September 2015 - Version: 6 - -=head1 TERMINOLOGY - -Because many of the concepts used in this document may be overloaded by -other concepts in the mind of the reader, it seems like a good idea to define -some terminology first. Please note that these definitions only apply within -the context of Perl 6. - -=head2 compilation unit - -A piece of code that can be compiled as a unit. It can either exist in a -file (and be compiled using C<use> or C<require>), or be presented as a stream -of characters for compilation with C<EVAL>. An example of a compilation unit -in a file: - - lib/JSON/Fast.pm6 - -=head2 distribution - -A distribution is an archive of some form that can be used to install zero -or more compilation units (each stored in a separate file), with any possibly -associated files needed for execution. For example: - - lib/JSON/Fast.pm6 - lib/JSON/PurePerl.pm6 - -It has a name for identification, which may or may not coincide with the -compilation units in the distribution. An example of a distribution name: - - JSON-Fast - -It also has a version, to distinguish it from other distributions with the -same name. For instance: - - 1.23 - -Which, together, are used to create the filename of the distribution, for -instance: - - JSON-Fast.1.23.tar.gz - -Please note that by changing the C<::> from the module specification to a -C<-> for the filename of the archive, we are effectively disallowing an owner -to upload a distribution for "JSON-Fast" and "JSON::Fast" at the same time. -This seems unlikely to become a problem. - -A Perl 6 distribution B<must> contain a configuration file named C<META6.json>, -containing JSON-encoded information about the contents of the distribution. - -=head2 owner - -The owner of a distribution is responsible for the development of a -distribution. This can either be a single person, or a (semi-)official -organisation. The owner of a distribution has a (mnemonic) name, e.g.: - - JRANDOM - -Please note that the owner is not necessarily the developer of a distribution, -although if the owner is a single individual, this is pretty likely. - -=head2 content storage - -A service to which an owner can upload a distribution to and other people can -download B<specific> distributions from. This is most likely some online -web-service, but it does not need to be. It has a logical name that is -essentially a URL. An example would be: - - cpan - -The (mnemonic) name of the owner usually coincides with the userid or login -name used to upload distributions, but does not need to be. - -=head2 auth - -The C<auth> of a distribution, is a globally unique identifier for a person -or organization. It can be constructed from the name of a content storage -and the name of the owner, separated by a colon. For example: - - cpan:JRANDOM - -Please note that this is B<not> an authority, merely an indication of the -location where the distribution for that owner was obtained. Typically the -auth of a distribution is used to try to load compilation units of already -installed distributions, such as in: - - use JSON::Fast:auth<cpan:JRANDOM>; - -=head2 identity - -The identity of a distribution, is the combination of name of the content -storage, the name of the owner, name and version of a distribution, separated -by colons. For example: - - cpan:JRANDOM:JSON-Fast:1.23 - -There should really be only one unique distribution for a given identity in the -world. - -The content storage should accept an identity and either directly return the -archive for that distribution, or return a URL from which that distribution -can be downloaded. - -=head2 recommendation manager - -A service that will translate a request for a compilation unit (with optional -owner and/or version and/or content storage specification, like a C<use> -statement) into a list of zero or more identities of distributions that match -the request. - -The recommendation manager is only used during the installation process of -the distribution for a wanted compilation unit. - -A recommendation manager can be run by a community (like the current Perl 6 -ecosystem or the packages list for Perl 5 on CPAN), or by company (for use -inside the company itself), or by any reviewing / grading service (for use -by anybody wanting to use that service), or by any other person willing to -put in the effort. - -A request for: - - JSON::PurePerl - -would yield the identity: - - cpan:JRANDOM:JSON-Fast:1.23 - -because the compilation unit C<JSON::PurePerl> is part of the C<JSON::Fast> -distribution. - -However, a request for: - - JSON::Fast:auth<github:JRANDOM> - -would not find anything, because it has the wrong content storage specification -("github" instead of "cpan"). - -Please note that a recommendation manager does not need to be bound to a single -content storage. In fact, a recommendation manager would be best if being able -to supply identities from the best of B<all> worlds. And potentially be -able to recommend identities responding to more natural language queries, but -that is probably outside the scope of this specification. - -A bundle of distributions is basically just a collection of identities that -listen to a name (such as C<Rakudo *>). A recommendation manager may provide -bundles as part of its service. And packagers may use this information as the -source for bundling distributions in their specific packaging system. - -=head1 DISTRIBUTION - -A Perl 6 distribution consists of an archive of some form (presumably a -.tar.gz, .tar.bz2 or .zip file) which is expected to at least contain a file -called "META6.json". The existence of this file indicates that this -distribution is a Perl 6 distribution. This is important for those archive -networks that also serve as a content-distribution system for other types -of distributions (such as PAUSE / CPAN), so that they can adapt the processing -of the contents, or decide to ignore any processing at all (such as CPAN-testers -not being able to test Perl 6 distributions (yet)). - -=head2 META6.json - -The META6.json file is a JSON-file that must at least contain a C<perl>, -C<name>, C<version> and C<description> section. - -=head3 meta-version - -Required. The version of the META6.json schema in use, as a quoted Version -literal (without the "v" prefix). This document describes version 1. - -=head3 perl - -Mandatory. The minimal perl version for which this distribution can be -installed. Specified as a version string. So: - - "perl" : "6.d" - -would not allow installation on Perl version 6.c - -=head3 name - -Mandatory. The name identifying this distribution. This is usually the name -of the main module that this distribution provides. An example of this would -be: - - "name" : "JSON::Fast" - -=head3 version - -Mandatory. The version literal for this distribution. An example of this -would be: - - "version" : "1.23" - -=head3 description - -Mandatory. A one line description of this distribution. So, for instance: - - "description" : "Providing fast JSON encoding/decoding" - -=head3 authors - -Optional. A list of (mnemonic) names of people who work / have worked on this -distribution. For informational purposes only. An example: - - "authors" : [ - "Janet Random", - "Sam Helpedwithit" - ] - -Please note that for identification purposes, only the owner (who uploaded -the distribution to the content storage) should be used. - -=head3 provides - -Mandatory. A list of module - local filename pairs that this distribution makes -available to be C<use>d. For example: - - "provides" : { - "JSON::Fast" : "lib/JSON/Fast.pm6", - "JSON::PurePerl" : "lib/JSON/PurePerl.pm6" - } - -Please note that the filenames specified only indicate the names of the files -in the B<distribution>. The installer may need to mangle filenames to be able -support file systems that do not support the file names given (e.g. when they -contain Unicode characters where the file system does not support them). This -also implies that any installer needs to keep a local database that is able to -convert from the module names given, to the actual associated file). - -=head3 depends - -Optional. A list of run-time dependencies, specified as C<use> strings. To -indicate alternatives, it is possible to specify an object with an C<any> key -and a list of C<use> strings as a value, instead of just a single use string. -So: - - "depends" : [ - "Sereal:auth<cpan:*>:ver(1..*)", - {"any": ["Archive::Compress", "Archive::Zlib"]} - ] - -would indicate a dependency on Sereal, and either Archive::Compress or -Archive::Zlib. An alternative itself may again be a list which in turn may -again contain alternatives, i.e. the dependencies form a fully recursive -tree. - -The dependencies may also be split between different phases, e.g. build time -dependencies are only needed on the machine where a package is built, not -on the one where it's installed. - - "depends": { - "runtime": { - "requires": [ - "Sereal:auth<cpan:*>:ver(1..*)", - "JSON::Fast" - ], - "recommends": [ - "JSON::Pretty" - ] - }, - "build": { - "requires": [ - "System::Info" - ] - }, - "test": { - "requires": [ - "File::Temp" - ] - } - } - -An installer has the option to automatically install any dependencies, if the -user has so indicated. Dependencies and alternatives should be tried in the -order they are specified. In the case of alternatives, the first one -for which the recommendation manager returns an identity should be installed. -Failure of installation of an alternative may allow automatic attempts on other -alternatives. - -Please note that the C<use> strings of compilation units are specified. It -is the responsibility of the recommendation manager to turn these into -identities of distributions that can be downloaded. - -Dependencies need not be Perl 6 only. By using the C<:from> adverb on the C<use> -string, dependencies external to Perl 6 can be specified. These could be Perl 5 -modules like C<Mojolicious:from<Perl5>>. Two names are reserved: - -=head4 :from<bin> - -With C<curl:from<bin>> one can specify on a C<curl> executable be available at -the given stage. The installer may only check the availability of this dependency, -or it may try to provide this, e.g. by installing the appropriate package to the -system. - -=head4 :from<native> - -A dependency like C<curl:from<native>> tells the installer, that the system -library with the given name must be present. The name is expanded following the -same rules as NativeCall uses, e.g. C<curl> will be expanded to C<libcurl.so> -on UNIX-like systems and C<curl.dll> on Windows. - -=head4 System specific values - -All information in C<build> and C<depends> is subject to system specific -collapsing, i.e. at any point one can specify an object with a -C<by-something.property> key and an object as the value. The "somethings" in the -key may be C<env>, C<env-exists> for checking environment variables or -C<distro>, C<kernel>, C<raku>, C<vm> for Raku's C<$*DISTRO>, C<$*KERNEL>, -C<$*RAKU> and C<$*VM> objects respectively. - -The value object is structured like a C<switch> statement with possible values -and/or a default value (the empty string) as the key and the value to replace the -whole object with on a match. - -An example where the name of the only dependency is picked by the currently -running VM: - - "depends" : { - "name" : { - "by-vm.name": { - "moar": "Low::Level::Backend::MoarVM", - "jvm": "Low::Level::Backend::JVM", - "": "Low::Level::Backend::Generic", - } - } - } - -Dynamically determined values may appear anywhere in the dependency -specification. e.g. the whole C<depends> section may depend on the distro name. -Or just the version of one of the dependencies may depend on the VM backend. - -=head4 Dependency hints - -The META data may provide hints to the installer for how to satisfy the -dependency. So if there's a location where a library can be obtained from -for a certain system, this information may be provided as a dependency hint: - - "depends": [ - { - "name": "archive:from<native>", - "hints": { - "by-kernel.name": { - "win32": { - "url": "http://www.p6c.org/~jnthn/libarchive/libarchive.dll", - "checksum": {"sha-256": "E6836E32802555593AEDAFE1CC00752CBDA"}, - "target": "resources/libraries/" - } - "": { } - } - } - } - ] - -The installer would download the library from the specified C<url> and store it -in the C<resources> directory of the build tree. This resource will also -automatically added to the C<resources> section of the meta data so it can be -accessed through C<%?RESOURCES>. - -If the library needs to be built, additional build information can be supplied. -The same infrastructure as for the distribution itself can be used. - - "depends": { - "runtime": [ - { - "name": "svm:from<native>", - "hints": { - "source": { - "builder": "Distribution::Builder::MakeFromJSON", - "build": { - "src-dir": "src", - "makefile-variables": { - "VERSION": "3.22", - "svm": {"resource": "libraries/svm"} - } - } - } - } - ] - } - -=head3 emulates - -Optional. A hash in which the key is the compunit (provided by the -distribution) to be aliased, and the value is the use string that should match -to get that compilation unit. An example of this would be: - - "emulates" : { - "JSON::Fast" : "JSON::XS:auth<cpan:MLEHMANN>" - } - -If then later, a program would say: - - use JSON::XS; - -it would in fact load the C<JSON::Fast> compunit, but make it appear as a -C<JSON::XS> compunit, but only if there was no "real" C<JSON::XS> compunit -installed that would match the C<use> specification. In other words: if the -real thing is available, then it will be used. If it is not, it will fall back -to the indicated compilation unit. And it will look like you are using the -thing you asked for. - -Conversely, if one would do a: - - use JSON::Fast; - -then later doing a: - - use JSON::XS:auth<cpan:MLEHMANN>; - -in the same scope would become a no-op, just as if the compunit had already -been loaded. - -Please note that it is responsibility of the emulating compunit to actually -provide a compatible interface with emulated compunit. - -=head3 supersedes - -Optional. Has the same meaning as "emulates" for the L</CompUnit::Repository>. -But has additional meaning for external packagers: it indicates a potential -superseding of the indicated compilation unit from the packagers point of -view. See L</superseded-by>. - -=head3 superseded-by - -Optional. Has the reverse meaning of "emulates" for the L</CompUnit::Repository>. -It is a hash in which the key is compunit provided by the distribution, and -the value is the C<use> string of the compunit it should be aliased to if -that compunit is available. So in this case: - - "superseded-by" : { - "JSON::Fast" : "SuperJSON:ver(v1.0 .. *)" - } - -it would mean that if a program attempts to load the C<JSON::Fast> compunit -of this distribution, it should instead use any C<SuperJSON> compunit that is -installed that has a version of 1.0 or higher. In other words: please don't -use my compunit, unless you really have to. - -This tag has additional meaning for packagers: if a packager detects a valid -C<supersedes> and C<superseded-by> pair in its collection of distributions to -be packaged, the packager may decide to only supply the distribution providing -the C<superseded-by> compilation unit. - -Please note that C<superseded-by> has no meaning as a C<depends>, so an -installer should probably not automatically install any C<superseded-by> -compunits. - -=head3 excludes - -Optional. A hash in which the key is a compilation unit provided by this -distribution, and the value is a C<use> string of all compilation units that -will be disallowed when attempted to be loaded in the same lexical scope. -An example of this would be: - - "excludes" : { - "JSON::PurePerl" : "JSON::Slow:auth<cpan:*>:ver(1..*)" - } - -So, if a lexical scope loads C<JSON::PurePerl> from this distribution, then -attempting to load C<JSON::Slow> will cause a Failure. Please note that this -has B<no> meaning for packagers: it is simply a way to provide a better error -message if a collision of some sort will occur when both modules are loaded -in the same lexical scope. - -=head3 build-depends - -Deprecated. A list of build-time dependencies, specified as C<use> strings. An -example of this would be: - - "build-depends" : [ - "Archive::Zip" - ] - -=head3 test-depends - -Deprecated. A list of test-time dependencies, specified as C<use> strings. An -example of this would be: - - "test-depends" : [ - "Test:auth<cpan:OVID>" - ] - -=head3 resources - -Optional. A list of file names, each of them corresponding to a file -in the "resources" directory in the distribution. At build time any -not-yet existing files should be created. The installer will install -all files into a location at its discretion (taking care of file-system -case-insensitivity and Unicode-support issues), and make the files -available through the L</%?RESOURCES> hash. - -=head3 support - -Optional. A hash of key-value pairs regarding support for this distribution. -Possible names are: C<email>, C<mailinglist>, C<bugtracker>, C<source>, -C<irc>, C<phone>. - -=over 4 - -=item email - -The email address of the owner of this distribution, if any. - -=item mailinglist - -The mailinglist of users of this distribution, if any. - -=item bugtracker - -The bugtracker of this distribution, if any. - -=item source - -The URL of the source of this distribution, if any. - -=item irc - -The URL of the IRC channel where this distribution can be discussed, if any. - -=item phone - -A fully qualified phone number (with potential cost indication) that can be -used with queries about this distribution. - -=back - -=head3 production - -Optional. A Boolean to indicate whether or not this is a distribution intended -to be used in production. For instance: - - "production" : true - -By default, a distribution is not ready for production. If a distribution -is not ready for production, then it will never be recommended. - -Please note that this section is only to be used by B<installers>, giving them -the opportunity to decide whether or not to install that distribution. Once -a distribution is installed, it can be loaded just like any other distribution. - -=head3 license - -Recommended, even if the license status is unknown, or there is none -(see below). -The L<SPDX|https://spdx.org/licenses> license identifier that the -package is distributed under. - -I<"By providing a short identifier, users can efficiently refer to a license without -having to redundantly reproduce the full license".> ― spdx.org - -SPDX license identifiers are meant to be interoperable and are the most widely -used standardized identifiers for licenses. - - "license" : "Artistic-2.0" - -If the license isn't on the SPDX standardized list, it is highly recommended to -include a URL to the text of the license under the support key in addition to -the name of the license: - - "license" : "Artistic-2.0", - "support": { - "license": "http://www.perlfoundation.org/artistic_license_2_0" - }, - -In the case that it is known that the author has choosen no license, C<NONE> -should be used: - - "license" : "NONE" - -In the event that a distributor or some other person does not know the license, -and therefore makes no assertion about whether the project is or is not licensed, -C<NOASSERTION> should be used: - - "license" : "NOASSERTION”" - -=head3 tags - -Optional. A list of general purpose tags. For instance: - - "tags" : [ - "json", - "perl6" - ] - -It has no meaning other than the meaning B<you> assign to it. - -=head2 Special directories - -A distribution may contain several directories that will be handled -specially. - -=head3 bin - -Any file inside this directory, will be installed as a callable shell -application. - -=head3 t - -All C<.t> files in this directory, will be tested in alphabetical order, -possibly in parallel. - -=head3 hooks - -All files in this directory should contain executable Perl 6 code, to be -executed at various stages of the install process of this distribution. - -=head2 Installation - -Distributions can be installed with an installer. This may be a command-line -script, or be some kind of GUI. The installer needs the user to (implicitly) -select the C<CompUnit::Repository> in which the distribution should be installed, and -the recommendation manager that should be used to convert requests for a -compilation unit into an identity of a distribution to be downloaded. - -=head1 CLASSES - -=head2 CompUnit::Repository - -Base class (interface, really) for the object living in the L</@?INC> array. -Used both for installing compunits, as well as finding a certain compunit by -way of its from, longname, auth and ver information. - -=head3 Specifying a CompUnit::Repository - -The specification of a CompUnit::Repository can happen at various places: in a -configuration file, on the command-line when starting (with C<-I>), and in -code when trying to create a CompUnit::Repository object programmatically. - -Each specification consists of a CompUnit::Repository class specification (either -explicitly, implicitly, or the short-hand form using the L</short-id> -identifier), optional named parameters and a location indicator (usually a -path or a URL). - -Some examples (where CUR is short for CompUnit::Repository): - - /foo/bar simple CUR::FileSystem in /foo/bar - file#/foo/bar (same) - inst#/installed simple CUR::Installation in /installed - inst#name<work>#/installed (same) but also set %?CUSTOM_LIB<work> - inst#name[work]#/installed (same) but more CLI-friendly - inst#name{work}#/installed (same) alternate CLI-friendly way - CompUnit::Repository::Installation#/installed (same) but with full class name - CompUnit::Repository::GitHub#masak/html-template get it from GitHub - -Multiple specifications may be concatenated with C<,>. If no class is -specified on subsequent specifications, then the previous class specification -will be assumed. So: - - /foo/bar,/foo/baz both use CUR::FileSystem - inst#/installed,/also both use CUR::Installation - /foo/bar,inst#/installed first CUR::FileSystem, second CUR::Installation - -=head3 new - - my $repo = CompUnit::Repository.new( $specification ); - -Create a new CompUnit::Repository-like object with the given specification, either -for inclusion in L</@?INC>, or to install a distribution. Returns the -instantiated object. - -Please note that for a given C<specification>, there should always only be -one C<CompUnit::Repository> object in a process. - -=head3 short-id - - say CompUnit::Repository::FileSystem.short-id; # "file" - -Returns a short C<\w+> identifier string (a C<tag> if you will) to identify -the use of this repo, e.g. in strings provided with the C<-I> command line -parameter. It should be unique for all of the CompUnit::Repository subclasses loaded. -The following C<short-id>'s are pre-defined: - - file CompUnit::Repository::FileSystem - inst CompUnit::Repository::Installation - -=head3 install - - my $installed = $repo.install( $dist ); - -Install the compilation units of a L</Distribution> in the appropriate way -for this CompUnit::Repository-like object. May cause a fatal exception if this -repository does not support installing. The parameter contains the -L</Distribution> object to be installed. Returns True if the distribution -was installed, or a C<Failure> if it didn't. - -Of course, any implementation of L<CompUnit::Repository>'s C<install> interface, may -decide to accept additional meta-information and store this and make available -for later introspection. - -=head3 uninstall - - my $removed = $repo.uninstall( $dist ); - -The opposite of L</install>. - -=head3 candidates - - my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? ); - -Return L<CompUnit> candidates given the matching credentials. - -=head2 CompUnit::Repository::FileSystem - -The simplest, default case for locating compilation units on a file system. -The module name specified should directly map to a file, similar to how -Perl 5 this does. Mainly intended to be used in development situations -to allow developers to have modules to be available without them having to be -installed. - -=head3 install - -Will fail unconditionally: installing compilation units is done by putting -files in the right location. - -=head2 CompUnit::Repository::Installation - -The default case for installed compilation units. Similar to the way Perl 5 -installs modules, but with meta-information per object, rather than globally -in a C<packlist>. This should be used by installers such as C<panda>. - -=head3 install - - my $installed = $repo.install( $dist ); - -Install the given L</Distribution> object in this repo. - -=head2 Distribution - -The class for installing distributions using -L</CompUnit::Repository::Installation>. Basically provides the API to access -the C<META6.json> file of a distribution. It should at least contain the -following methods: - -=head3 meta - - my $meta = $dist.meta; - -Return a Hash with the representation of the meta-data, constructed the same -way as in the C<META6.json> specification. Please note that an actual -META6.json file does not need to exist, just a representation in that format. - -=head3 content - - my $content = $dist.content( <provides JSON::Fast lib/JSON/Fast.pm6> ); - - my $content = $dist.content( <resource images fido.png> ); - -Return the octet-stream as specified by the given keys, navigating through -the C<META6.json> hash. - -=head2 Distribution::Local::Tar - -An implementation of the C<Distribution> API for locally stored C<.tar> files. - -=head2 CompUnit - -The object that describes a compilation unit. Contains as much meta-data -as possible, e.g. from the C<Distribution> object it came from. - -=head3 new - - my $compunit = CompUnit.new( $path ); - -Create a new CompUnit object with the given specification. Returns the -instantiated object, or C<Failure> if it could not find the C<path>. - -Please note that for a given C<path>, there should always only be one -C<CompUnit> object in a process. This to prevent reloading the same -compilation unit more than once. - -=head3 load - - my $loaded = @candidates[0].load(...); - -Returns True if loading of the C<CompUnit> was successful, or a C<Failure> -if something went wrong. - -=head3 loaded - - my $loaded = $compunit.loaded; - -Return whether the compunit has been loaded. - -=head3 precomp - - my $precompiled = $compunit.precomp; - -Create a pre-compiled version of the CompUnit. Optionally takes an output -file argument (default: the same path as the source, with an extension -identifying it is a precompiled version), an optional named argument C<:INC> -(with default C<@?INC>) and an optional named argument C<:force> to force -creation even if the output file already exists. - -=head1 SYSTEM VARIABLES - -Several dynamic variables are available. - -=head2 %?RESOURCES - -This hash provides compile and runtime access to files associated with the -L</Distribution> of the current compilation unit. - -So, if the C<META6.json> file contains this C<resources> section: - - "resources" : [ - "images/fido.png", - "images/zowie.png", - "libraries/inline_helper - ] - -then the C<Distribution> is supposed to contain the files -C<resource/images/fido.png> and C<resources/images/zowie.png>. After -installation, IO objects of such a file would be available through - - %?RESOURCES<images><fido.png> - -The absolute path could be obtained with: - - %?RESOURCES<images><fido.png>.absolute - -and a handle could be obtained with: - - %?RESOURCES<images><fido.png>.open - -without there being any guarantee that this path has anything to do with the -path as specified in the distribution. Please also note that the installer -will probably mangle filenames of actually installed files. - -This means you can have files with Unicode characters in upper/lower case, -and still be able to access them when installed on a file system that does -not support Unicode. - -=head2 CompUnit::RepositoryRegistry - -This class manages the repositories. Use -C<CompUnit::RepositoryRegistry.repository-for-name('site')> to get the -C<CompUnit::Repository::Installation> instance for the "site" repository. - -=head2 $*REPO - -This is the head of the linked list of C<CompUnit::Repository> objects that will be -queried in turn whenever an attempt should be made to load a compilation unit (be that at -compile time with C<use>, or at runtime with C<require>. - -The C<CompUnit::Repository> object pointed to by C<$*REPO> will either satisfy a -given dependency itself, or hand the request off to it's C<.next-repo>. - -=head1 AUTHORS - - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S24-testing.pod b/S24-testing.pod deleted file mode 100644 index c416e405..00000000 --- a/S24-testing.pod +++ /dev/null @@ -1,236 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 24: Testing - -=head1 VERSION - - Created: 30 Dec 2010 - - Last Modified: 14 August 2014 - Version: 8 - -=head1 SYNOPSIS - - use Test; - - plan 6; # not needed when using "done" - - ok True, 'True is a true value'; - nok False, 'False is a false value'; - is 'ab'.uc, 'AB', 'successful string comparison'; - diag "we may have some mathematical issues" - if !is-approx 2.sqrt, 1.4142135623, 'Approximate numeric comparison'; - dies-ok { die "yes"}, 'exceptions'; - dies-ok '1 1', 'two terms in a row are a parse error'; - - done; # not needed when doing "plan" - -=head1 DESCRIPTION - -Perl 6 comes with a standard testing module, C<Test>. It is the testing module -used by the official spectest suite. - -The testing functions emit output conforming to the Test Anything -Protocol. See L<http://testanything.org>. - -For the purposes of this document, a I<test file> is a file that does -C<use Test>. - -All of the following functions are exported by default: - - # planning number of tests - plan($number-of-tests) - done() - - # unconditional passing/failing/notification - pass($desc?) - flunk($desc?) - diag($desc) - - # skipping - todo($reason, $count = 1) - skip($reason, $count = 1) - skip-rest($reason?) - - # evaluates $cond in boolean context - ok(Mu $cond, $desc?) - nok(Mu $cond, $desc?) - - # comparisons - is(Mu $got, Mu $expected, $desc?) - isnt(Mu $got, Mu $expected, $desc?) - cmp-ok(Mu $got, $op, Mu $expected, $desc?) - - # structural comparison with infix:<eqv> - is-deeply(Mu $got, Mu $expected, $desc?) - - # numeric comparison with 1e-5 - is-approx(Mu $got, Mu $expected, $desc?) - - # class membership testing - isa-ok(Mu $var, Mu $type, $desc?) - - # grouping of tests, ok only if all ok - subtest(&subtests, $desc?) - - # exception testing - dies-ok($code, $desc?) - lives-ok($code, $desc?) - throws-like($code, $exception-type, $desc?, *%matcher) - -=head1 Test plans - - sub plan($number-of-tests) is export { ... }; - sub done() is export { ... }; - -In order to determine whether a test file ran all its tests, a C<plan()> function -call can be made somewhere in the test file, providing a count of the total -number of tests. A TAP harness can then flag an error condition when the number -of tests actually run doesn't match. - -If C<plan()> isn't called, C<done()> can be called at the end of the test -file to output an automatically computed tally. - -A TAP harness will consider it an error if neither C<plan()> nor -C<done()> was called, or if there was more than one call in the test -file, or if the call occurred between calling two test functions -(rather than at the beginning or at the end). - -=head1 Test functions - -All test functions take an optional description argument, which -will be printed along with the C<ok> or C<not ok> result and the test -number. Note that what is displayed as optional parameters in the list -below might as well be implemented by some other mechanism, such as -several C<multi sub>s. Such details are left as implementation-dependent. - -The names of positional parameters are non-normative, so supplying the -positional arguments to these test files by name is discouraged. - -=head2 pass(), flunk() - - sub pass($desc?) is export { ... } - sub flunk($desc?) is export { ... } - -The C<pass()> function marks a test as passed. The C<flunk()> function marks a -test as B<not> passed. - -=head2 diag() - - sub diag($message) is export { ... } - -The C<diag()> function allows specific diagnostic information to be printed -in a TAP-compatible manner on C<$*ERR>. It is usually used when a particular -test has failed to provide information that the test itself did not provide. -Or it can be used to provide visual markers on how the testing of a test-file -is progressing (which can be important when doing stress testing). - -=head2 todo(), skip(), skip-rest() - - sub todo($reason, $count = 1) is export { ... } - sub skip($reason, $count = 1) is export { ... } - sub skip-rest($reason?) is export { ... } - -The C<todo()> function can be called before running other test functions, and -marks the next C<$count> tests as TODO. - -The C<skip()> function is called I<instead> of the some tests (usually because -they would die), and emits C<$count> SKIP markers in the TAP output. - -The C<skip-rest()> function can be called conditionally to C<skip($remaining)> -all of the remaining tests. - -The C<todo()> and C<skip()> functions are generally automatically generated -by some sort of source code fudging program. - -=head2 ok(), nok() - - sub ok(Mu $cond, $desc?) is export { ... } - sub nok(Mu $cond, $desc?) is export { ... } - -The C<ok()> function marks a test as passed if the given condition evaluates -to C<True>. The C<nok()> function marks a test as passed if the given -condition evaluates to C<False>. - -=head2 is(), isnt(), cmp-ok() - - sub is(Mu $got, Mu $expected, $desc?) is export { ... } - sub isnt(Mu $got, Mu $expected, $desc?) is export { ... } - sub cmp-ok(Mu $got, $op, Mu $expected, $desc?) is export { ... } - -The C<is()> function marks a test as passed if the obtained and expected values -are the same. If C<$expected> is a type object, then C<$got> is compared -using C<===>. If C<$expected> is a defined value, then C<$got> is compared -using C<eq>. The C<isnt()> function marks a test as passed if the obtained -and expected values are B<not> the same (using the same logic as with C<is()>). - -The C<cmp-ok()> function compares two values with the given operator and passes -the test if the comparison yields a C<True> value. For ease of use, operators -may be passed as strings, such as C<'=='> or C<'~~'>. Note that you can also -pass a custom operator, for special types of comparisons. - -These functions are typically used to check scalar values. - -=head2 is-deeply() - - sub is-deeply(Mu $got, Mu $expected, $desc?) is export { ... } - -The C<is-deeply()> function marks a test as passed if the obtained and expected -values are C<eqv>. This is the best way to check for equality of (deep) data -structures. - -=head2 is-approx() - - sub is-approx(Mu $got, Mu $expected, $desc?) is export { ... } - -The C<is-approx()> function marks a test as passed if the obtained and -expected numerical values are within C<1e-5> of each other. - -=head2 isa-ok() - - sub isa-ok(Mu $object, Mu $type, $desc?) is export { ... } - -The C<isa-ok()> function marks a test as passed if the given object is, or -inherits from the given type. For convenience, types may also be specified -as a string. - -=head2 subtest() - - sub subtest(&subtests, $desc?) is export { ... } - -The C<subtest()> function executes the given block, consisting of usually more -than one test, possibly including a C<plan()> or C<done()>. It will pass the -test only if B<all> tests in the block, pass. - -=head2 dies-ok(), lives-ok(), throws-like() - - sub dies-ok(Callable $code, $desc?) is export { ... } - sub lives-ok(Callable $code, $desc?) is export { ... } - sub throws-like($code, $exception-type, $desc?, *%matcher) is export { ... } - -The C<dies-ok()> passes the test if the given code throws an exception. -The C<lives-ok()> passes the test if the given code B<does not> throw an -exception. - -The C<throws-like()> function checks whether the given code (specified as either -something C<Callable>, or as a something to be C<EVAL>led) throws a specific -exception (either specified as a Type object, or as a string). If an -exception was thrown, it will also try to match the matcher hash, in which -the key is the name of the method to be called on the exception, and the -value is the value it should have to pass. - -Please note that you can only use the C<EVAL> form if you are not referencing -any symbols in the surrounding scope. If you are, you should encapsulate -your string with a block and an EVAL. For instance: - - throws-like { EVAL q[ fac("foo") ] }, X::TypeCheck::Argument; - -=head1 AUTHORS - - Moritz Lenz <moritz@faui2k3.org> - Carl Mäsak <cmasak@gmail.com> - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S27-perl-culture-draft.pod6 b/S27-perl-culture-draft.pod6 deleted file mode 100644 index 79493962..00000000 --- a/S27-perl-culture-draft.pod6 +++ /dev/null @@ -1,134 +0,0 @@ -=begin pod - -=TITLE Synopsis 27: Perl Culture [DRAFT] - -=AUTHORS - Faye Niemeyer - japhb - -=begin SYNOPSIS - -For years the Perl 6 community has had a reputation for friendliness towards -all those who come along, and we've found this to work quite well. In the -interest of making sure everybody knows how we do things around here, we've -written down what's helped us make the community what it is. - -What's discussed in this document boils down to this: - -=item # We aim to be actively welcoming, friendly, respectful, and helpful to - everyone interested in Perl 6 and our shared community. - -=item # We don't discriminate on any basis other than ability to be a kind, - positive member of our community. - -=item # Our standard of behavior is "awesome". If your behavior is LTA (Less - Than Awesome), we will call you on it. - -=item # There is no form of negative behavior that will impress us or gain you - favor in our community. - -=item # We try to hug trolls where possible, but if that doesn't work, we eject - them. The health and happiness of our community comes first. - -The rest of this document lays out a deeper explanation of these points. - -=end SYNOPSIS - -=head1 The Basics - -The core element of how we behave here is simply this: B<Be kind to everyone.> -Yes, everyone. Including that troll over there, be kind to them too. The rest of -this document builds off of that core element. - -The general mood in the Perl 6 community is a positive one. Being a negative -force is discouraged, and is unlikely to do much for us. The kinder you are, the -more receptive the community will be to you. - -=head2 No Discrimination - -A major part of behaving decently is making sure you do not discriminate against -anyone. Here we consider B<X<discrimination>> to be treating someone differently -based on some aspect of who they are or what they believe. Judge ideas on the -merit of the idea alone, and judge people only by their behavior. - -We won't provide an explicit list of things not to judge someone on, since such -a list could never be exhaustive, and chances are you're already aware of what -these things are. Simply, if you could judge someone for it, don't. - -(Note: for those who think judging people only by their behavior still counts -under our definition of discrimination, but who realize this is necessary for an -enforcable policy of this nature, will have noticed the kind of circularity that -also occurs in the implementation of Perl 6 ☺) - -=head2 Civil Discussions - -When we talk about being kind, we aren't talking about being agreeable with -everything and everyone all the time. Disagreement is necessary to make sure -Perl 6 is the best it can be, instead of being the first idea someone comes up -with. We only ask that your are kind and civil in discussions wherein you -disagree with someone else on the matter at hand. - -In any discussion, it's natural to feel frustrated with the fact that the -discussion is still continuing. In these cases it's important to refrain from -personal attacks on anyone holding opposing views. It's better to do something -that lessens your frustration, including walking away from it. Even mentioning -that the discussion is becoming frustrating is better than letting your -frustration control your part in the discussion. - -=head1 Handling Trolls - -Here we consider a B<X<troll>> to be someone whose behavior is meant to be a -negative force on the community, especially after attempts by the community to -help a troll be less of one. - -We handle trolls by being nice to them. Genuinely and civilly make the case -against their negative influence. People who are actually trolls will quickly -reveal themselves by their refusal to take into account the things you are -saying. When these trolls are conclusively identified, the community as a whole -will be quick to wish them well and escort them out the door. - -We take this approach because lots of times, people have genuine misconceptions -about the issue they bring up. When our default is to help people understand -their misconceptions, we'll find a lot more friendly faces for our -community. And, as a bonus side effect, doing everything we can to help trolls -not be so troll-like helps us build a stronger case against those trolls, since -it leaves less possibility that they had genuine concerns after all. - -As an aside: thankfully, almost all trolls in the Perl 6 community are there to -attack the language for a wide variety of now mostly historical reasons. When a -troll enters the Perl 6 community, they are more likely to try and get a -negative reaction on the basis of the language rather than the basis of any one -person's characteristics. This doesn't mean we take a diminished stance on -personal attacks, however; it's simply a statement of what kind of trolling -you're most likely to see around here. - -=head1 Handling Attacks Against Yourself - -If you are on the receiving end of a troll's discriminatory behavior, the best -thing to do would be to handle said troll with kindness (see the previous -section, L<#Handling Trolls>). It's best not to engage on their terms. - -If you have been unable to sway a troll, or you are otherwise not able to handle -a discussion with the troll, your best course of action would be to ask the rest -of the community for help. (Lots of times, the Perl 6 community will already be -helping with the discussion!) We always strive to make sure trolls are forced to -leave before you are. - -The most important thing to remember in these situations is simply: B<Don't -Panic!> Rash behavior will never help the situation. - -=head1 Final Words - -The Perl 6 community has kept itself a shining example of a friendly community -for years. These rules are not meant to change how we operate, only to set down -how we do things, for the benefit of every newcomer to Perl 6. You can see this -in the fact that this document isn't a lawyer-like enumeration of every possible -social interactionN<This should not be surprising for a group based around a -high-level language :P>. We've set out these rules so that you don't have to -worry about doing the right thing beyond being kind towards and respectful of -everyone around you. - -So now that you know how we run as a community, come on in and have the -appropriate amount of fun! - -=end pod diff --git a/S28-special-names.pod b/S28-special-names.pod deleted file mode 100644 index 3b9a7f1f..00000000 --- a/S28-special-names.pod +++ /dev/null @@ -1,406 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -[DRAFT] Synopsis 28 - Special Names [DRAFT] - -=head1 VERSION - - Created: 23 Feb 2009, created by Tim Nelson from miscellaneous documents lying around - - Last Modified: 8 September 2014 - Version: 13 - -=head1 Special Variables - -=head2 Introduction - -This document serves as a collection point -for what is known about special variables -in Perl 6 and correlates them with the changes from Perl 5. - -If you are trying to find the Perl 6 equivalent of a Perl 5 special -variable you know, try searching this file for the Perl 5 version. -Each main entry is followed by a note containing the corresponding -Perl 5 variable(s). The list of main entries is also followed by -a table showing the 5 and 6 variables side-by-side. - -=head2 Overview - -=head3 Secondary Sigils (also known as "twigils") - -A quick reminder of the relevant twigils from S02: - - $?foo # Compiler constants (fixed at compile time) - $*foo # Context variable, default global (run time) - $=foo # File-scoped Pod data - -The various C<$?foo> variables are determined at compile time, and are -not modifiable at run time. This does not mean that the variable has the -same value everywhere; for instance, C<$?LINE> is different on every line -of the program. - -The C<$*foo> variables function both as dynamically scoped variables -and as globals. Globalness is relative, in other words. Any dynamic -scope may modify the set of globals visible via the C<$*foo> notation. -Most of the standard globals listed below actually live either in -the C<PROCESS> or the C<GLOBAL> package, where C<PROCESS> contains -globals belonging to the entire process, while C<GLOBAL> contains the -globals belonging to the current interpreter, since a process may be -running more than one interpreter. Unless otherwise indicated below, -the outermost definition of these variables are kept in the C<PROCESS> -package. - -Please note that an implementation may decide to populate these variables -lazily on the first access to <$*foo>. So checking for existence of these -variables in the C<PROCESS> or C<GLOBAL> package may give a false negative. - -The C<$=foo> variables are related to the C<$?foo> variables -insofar as the text of the program is known at compile time, so the -values are static. However, the different twigil indicates that the -variable contains Pod data, which is primarily under user control -rather than compiler control. The structure of these variables will -be fleshed out in S26. - -=head3 Named variables - - Variable Spec Type Description - -------- ---- ---- ----------- - - @_ # ??? (FIX) - $! S04 # Current Exception object - $/ S05 Match # Last match - $0, $1, $2 S05 Str # First captured value from match: $/[0] - @*ARGS S06 Array of Str # command-line arguments - $*ARGFILES S02 IO::Handle # The magic command-line input handle - &?BLOCK S06 Block # current block (itself) - ::?CLASS S12 Class # current class - $?CLASS S02 Class # current class - @=COMMENT (S26) # All the comment blocks in the file - %?CONFIG Hash of XXX # configuration hash XXX What does this do? - $*CWD S16 IO::Path # current working directory - $=data (S26) IO # data block handle (=begin data ... =end) - %?DEEPMAGIC S13 Hash of XXX # Controls the mappings of magical names to sub definitions - $?DISTRO S02 Systemic # Which OS distribution am I compiling under - $*DISTRO S02 Systemic # Which OS distribution am I running under - $*EGROUP +Int,~Str # effective $*GROUP - %*ENV S02 Hash of Str # system environment variables - $*ERR S16 IO::Handle # Standard error handle - $*EUSER +Int,~Str # effective $*USER - $?COMPILER IO::Path # location of the compiler executable - $*SHEBANG IO::Path # location of the interpreter executable (usually eqv $?COMPILER) - $?FILE S02 Str # current filename of source file - $?GRAMMAR S02 Grammar # current grammar - $*GROUP +Int,~Str # group id (numeric) or name (string) - $*IN S16 IO::Handle # Standard input handle; is an IO object - @?INC S11 # where to search for user modules (but not std lib!) - %?LANG S02 Hash of Grammar # What is the current set of interwoven languages? - $*LANG S02 Str # LANG variable from %*ENV that defines what human language is used - $?LINE S02 Int # current line number in source file - %*META-ARGS S19 Hash of XXX # Meta-arguments - $?MODULE S02 Module # current module - %*OPTS S19 Hash of XXX # Options from command line - %*OPT... S19 Hash of XXX # Options from command line to be passed down - $?KERNEL Systemic # operating system compiled for - $*KERNEL Systemic # operating system running under - $*OUT S16 IO::Handle # Standard output handle - $?PACKAGE S02 Package # current package - $?PERL S02 Systemic # Which Perl am I compiled for? - $*PERL S02 Systemic # perl version running under - $*PID Int # system process id - $=pod S02 # POD6 data - $*PROGRAM S19 IO::Path # location of the Perl program being executed - %*PROTOCOLS S16 Hash of Method # Stores the methods needed for the uri() function - ::?ROLE Str # current role (as package or type name) - $?ROLE S02 Role # current role - &?ROUTINE S06 Routine # current sub or method (itself) - $?SCOPE S02 # Current "my" scope (XXX unnecessary?) - $*TMPDIR S16 IO::Path # system temporary directory - $*TZ S32 # Local time zone - $?USAGE S06 Str # Default usage message generated at compile time (EDIT: was renamed to $*USAGE) - $*USER +Int,~Str # user id (numeric) or name (string) - $?VM S02 Systemic # Which virtual machine am I compiling under - $?XVM S02 Systemic # Which virtual machine am I cross-compiling for - -Note that dynamic variables such as C<$*OUT> may have more than -one current definition in the outer dynamic context, in which case -the innermost dynamic scope in which it is defined determines the meaning. For instance, -C<$PROCESS::OUT> is the stdout for the entire process, but each -interpreter can set its own C<$GLOBAL::OUT> to make C<$*OUT> mean -whatever it wants independently of other interpreters. Any dynamic -scope may also declare a local meaning of C<$*OUT> that applies only -to called code. Likewise each thread could log its own errors -to its own C<$*ERR>, since a thread is a dynamic scope. - -The C<Systemic> role collects a few common features of some of the special -variables such as C<$*PERL>, C<$?VM>, C<$*KERNEL>, etc. It in turn relies -on the C<Universal> role that all cosmically unique entities must support -in order to have a unique name. - - role Universal { - has Str $.name; - has Str $.auth; - has Version $.version; - has Blob $.signature; # optional? - } - role Systemic does Universal { - has $.desc; # uname-ish version-like information goes here - ... - } - -=head3 Perl 5 to Perl 6 special variable translation - -If a column has a "-" in it, it means that item is unavailable in that version of Perl. - - Perl 5 Perl 6 Comment - ----------- ----------- ----------------------- - STDIN $*IN See S16; actual variable is $PROCESS::IN - STDOUT $*OUT See S16; actual variable is $PROCESS::OUT - STDERR $*ERR See S16; actual variable is $PROCESS::ERR - $_ $ARG $_ More lexically aware - $_[1],$_[2].. $^a,$^b.. - $a,$b - No special meaning whatsoever - - $/ Object with results of last regex match - $1,$2,$3... $0,$1,$2... Match capture variables start at 0 - $& $MATCH ~$/ - $` $PREMATCH substr based on $/.from - $' $POSTMATCH substr based on $/.to - $+ - But info can now be retrieved from $/ - $^N $*MOST_RECENT_CAPTURED_MATCH ...or some such. - or $/[*-$n] ...or omit - @- $1.from, etc - @+ $1.to, etc. - %! - - $[ - This feature has been removed - $* - Deprecated long ago - $# - Deprecated long ago - $^H - These were only ever internal anyway - %^H - - - $! Current exception (see L<S04>) - $! $ERRNO $OS_ERROR - Use shiny new $! - $? $CHILD_ERROR - Use shiny new $! - $@ $EVAL_ERROR - Use shiny new $! - $^E - Use shiny new $! - $^S - - $. $NR $*IN.ins() - $/ $RS $*IN.input-line-separator() - $| $*OUT.autoflush() - $, $OFS $*OUT.output-field-separator() - $\ $*OUT.output-record-separator() - $" $LIST_SEPARATOR - - $; $SUBSEP - - $$ $PID $*PID - $< $UID $*UID Real UID (User ID) - $( $GID $*GID Real GID (Group ID) - $> $EUID $*EUID Effective UID - $) $EGID $*EGID Effective GID - $0 $PROGRAM_NAME $*PROGRAM-NAME - $^C $COMPILING $*COMPILING - $^D $DEBUGGING $*DEBUGGING - $^F $SYS_FD_MAX $*SYS_FD_MAX ...or some such - $^I $INPLACE_EDIT $*INPLACE_EDIT ...or some such - $^M $*EMERGENCY_MEMORY ...or some such (or omit) - $^O $OSNAME $*KERNEL.name (or $*DISTRO.name or $*VM.name) - $^P $PERLDB $*PERLDB ...or some such - $^R $*LAST_REGEXP_CODE_RESULT ...or some such. Or omit. - $^T $BASETIME $*INITTIME A Temporal::Instant object - $^V $] $?PERL.version - $^W $*WARNINGS (if any dynamic control needed) - ${^WARNING_BITS} $?WARNINGS - $^X $?COMPILER or $*SHEBANG (plus stringification) - ARGV $*ARGFILES Note the P6 idiom for this handle: - for lines() { - # each time through loop - # proc a line from files named in ARGS - } - @ARGV @*ARGS - ARGVOUT TBD - $ARGV TBD - @F @_ - %ENV %*ENV - @INC @?INC (but not for std library modules) - %INC no equivalent, encapsulated in CompUnitRepo object - %SIG event filters plus exception translation - $SIG{__WARN__} $*ON_WARN - $SIG{__DIE__} $*ON_DIE - ${^OPEN} - This was internal; forget it - -=head2 SPECIAL VARIABLES MORE IN DEPTH - -=head3 $?KERNEL / $*KERNEL - -Contains a C<Kernel> class instance that does C<Systemic>. It further -provides the following methods: - -=over - -=item release - -The release information of this kernel. - -=item arch - -Processor architecture. - -=item bits - -Number of bits used by architecture (typically 32 or 64 bits). - -=item hardware - -The processor hardware, if known. - -=item signals - -An C<Array> of C<Signal>s that are supported by this C<Kernel>, in which the -ordinal number matches the lower level signal value. - -=item signal - - my $int = $*KERNEL.signal(SIGHUP); - my $int = $*KERNEL.signal("HUP"); # or "SIGHUP" - my $int = $*KERNEL.signal(1); # just pass through for bare Ints - -Convert the given C<Signal> Enum value, or a string representing that signal, -to the internal value that this C<Kernel> uses to send to a process. - -=back - -=head3 $?DISTRO / $*DISTRO - -Contains a C<Distro> class instance that does C<Systemic>. It further -provides the following methods: - -=over - -=item release - -The release information of this distribution. - -=item is-win - -True if this is a Windows-like distribution. - -=item path-sep - -The character that is used to separating paths in specifications, usually in -environment variables such as C<PATH>. - -=back - -=head3 $?VM / $*VM - -Contains a C<VM> class instance that does C<Systemic>. It further -provides the following methods: - -=over - -=item config - -The configuration hash that was used to build the virtual machine. - -=item precomp-ext - -The extension used by pre-compiled module files. - -=item precomp-target - -The name of the compilation stage to produce pre-compiled module files -(typically used as "--target=xxx"). - -=back - -=head3 $?PERL / $*PERL - -Contains a C<Perl> class instance that does C<Systemic>. It further -provides the following methods: - -=over - -=item VMnames - -A list of C<$?VM.name> / C<$*VM.name> values known. - -=item DISTROnames - -A list of C<$?DISTRO.name> / C<$*DISTRO.name> values known to have been seen -with the current C<$?VM.name> / C<$*VM.name>. - -=item compiler - -Contains a C<Compiler> class instance that does C<Systemic>. It further -provides the following methods: - -=over - -=item release - -The release information of this version of Perl. - -=item build-date - -The C<DateTime> this version of Perl was built. - -=item codename - -The codename of this version of Perl. - -=back - -=back - -=head2 NOT YET DEFINED - -The following items are not yet defined, but will need to be defined. - -XXX Don't remove this line until this section is completely blank. - -The $?LANG and $*LANG variables are also confusing (both in S02). - -=head3 Form.pm - -These go in the Perl 5 to Perl 6 conversion table: - - Perl 6 Perl 5 - ------ ----------------------------------------- - - $% $FORMAT_PAGE_NUMBER - - HANDLE->format_page_number(EXPR) - - - $= $FORMAT_LINES_PER_PAGE - - HANDLE->format_lines_per_page(EXPR) - - - $- $FORMAT_LINES_LEFT - - HANDLE->format_lines_left(EXPR) - - - $~ $FORMAT_NAME - - HANDLE->format_name(EXPR) - - - $^ $FORMAT_TOP_NAME - - HANDLE->format_top_name(EXPR) - - - $: $FORMAT_LINE_BREAK_CHARACTERS - - IO::Handle->format_line_break_characters - - - $^L $FORMAT_FORMFEED - - IO::Handle->format_formfeed - - - $^A $ACCUMULATOR - -=head3 S15-unicode.pod - -${^ENCODING} variable -- S32/Str.pod implies this is $?ENC -$?NF -- Unicode normalization form -${^UNICODE} variable - -=head3 Infectious trait spec - -${^TAINT} variable, which is pending, among other things, infectious trait spec - -=head1 AUTHORS - - Larry Wall <larry@wall.org> - Tim Nelson <wayland@wayland.id.au> - Lyle Hopkins <webmaster@cosmicperl.com> - Carl Mäsak <cmasak@gmail.com> - -=for vim:set expandtab sw=4: diff --git a/S29-functions.pod b/S29-functions.pod deleted file mode 100644 index 9110ca9e..00000000 --- a/S29-functions.pod +++ /dev/null @@ -1,1019 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 29: Builtin Functions - -=head1 VERSION - - Created: 12 Mar 2005 - - Last Modified: 24 April 2015 - Version: 63 - -The document is a draft. - -=head1 Notes - -In Perl 6, all builtin functions belong to a named package (generally a -class or role). Not all -functions are guaranteed to be imported into the CORE scope. -In addition, the list of functions imported into C<CORE> will be -subject to change with each release of Perl. Authors wishing to -"Future Proof" their code should either specifically import the -functions they will be using, or always refer to the functions by their -full name. - -After 6.0.0 comes out, global aliases will not be removed lightly, -and will never be removed at all without having gone through a -deprecation cycle of at least a year. In any event, you can specify -that you want the interface for a particular version of Perl, and -that can be emulated by later versions of Perl to the extent that -security updates allow. - -Where code is given here, it is intended to define semantics, not to -dictate implementation. - -=head2 Operators vs. Functions - -There is no particular difference between an operator and a function, -but for the sake of documentation, only functions declared without -specifying a grammatical category or with a category of C<term:> -(see L<S02/"Bits and Pieces">) will be described as "functions", -and everything else as "operators" which are outside of the scope -of this document. (See S03 for operators.) - -=head2 Multis vs. Functions - -In actual fact, most of the "functions" defined here are multi -subs, or are multi methods that are also exported as multi subs. -The Setting is responsible for importing all the standard multi subs -from their various packages into the CORE lexical scope. See S02. - -=head1 Type Declarations - -The following type declarations are assumed: - -=over - -=item Matcher - - subset Matcher of Mu where * !=== any(Bool,Match,Nil) - -Used to supply a test to match against. Assume C<~~> will be used against it. -Booleans are forbidden because they almost always indicate a programming -error where the argument has been evaluated too soon against the wrong C<$_>. -For instance: - - grep $_ == 1, 1,2,3; # evaluating wrong $_, so forbidden - grep { $_ == 1 }, 1,2,3; # okay - grep * == 1, 1,2,3; # okay - - -=item Ordering - - subset KeyExtractor of Code where { .signature === :(Any --> Any) }; - subset Comparator of Code where { .signature === :(Any, Any --> Int ) }; - subset OrderingPair of Pair where { .left ~~ KeyExtractor && .right ~~ Comparator }; - - subset Ordering where Signature | KeyExtractor | Comparator | OrderingPair | Whatever; - -Used to handle comparisons between things. Generally this -ends up in functions like C<sort()>, -C<min()>, C<max()>, etc., as a $by parameter which provides -the information on how two things compare relative to each other. - -=over - -=item Comparator - -A closure with arity of 2, which for ordering returns -negative/zero/positive, signaling the first argument should -be before/tied with/after the second. aka "The Perl 5 way". - -For equivalence the closure returns either not 0 or 0 indicating -if the first argument is equivalent or not to the second. - -=item KeyExtractor - -A closure with arity of 1, which returns the "key" by which -to compare. Values are compared using C<cmp> for orderings -and C<eqv> for equivalences, which in Perl 6 do different -comparisons depending on the types. (To get a Perl 5 string -ordering you must compare with C<leg> instead.) - -Internally the result of the KeyExtractor on a value should -be cached. - -Note that it is very easy to generate a simple C<KeyExtractor> -using C<~*> for strings and C<+*> for numbers, since with most -simple operators C<*> returns a closure of one argument. - - @sorted = sort +*, @unsorted; #ascending numeric - @sorted = sort -*, @unsorted; #descending numeric - -=item OrderingPair - -A combination of the two methods above, for when one wishes -to take advantage of the internal caching of keys that is -expected to happen, but wishes to compare them with something -other than C<eqv> or C<cmp>, such as C<E<lt>=E<gt>> or C<leg>. - -=item Signature - -If a signature is specified as a criterion, the signature is -bound to each value and then each parameter does comparisons -in positional order according to its type, as modified by -its traits. Basically, the system will write the body of -the key extraction and comparison subroutine for you based on -the signature. - -For ordering the list of positional parameter comparisons is -reduced as if using [||] but all comparisons do not need to be -performed if an early one determines an increasing or decreasing -order. For equivalence the list is reduced as if using [&&]. - -=item Whatever - -An ordering of C<*> does the default comparison for the operator: - - @sorted = sort *, @unsorted; - -=back - -=back - -=head1 Function Packages - -=head2 Context - -=over - -=item caller - -See L<S06/"The C<callframe> and C<caller> functions">. - -=item callframe - -See L<S06/"The C<callframe> and C<caller> functions">. - -=item EVAL - - macro EVAL ( Str|Buf $code, Grammar :$lang = CALLER::<$?PARSER>) - -Execute C<$code> as if it were code written in C<$lang>. If C<$code> -is of type C<Buf>, the same decoding techniques are applied as a compiler -for C<$lang> would usually do to input files. - -The default for C<$lang> is the language in effect at the exact -location of the C<EVAL> call. - -Returns whatever C<$code> returns, or fails when the compilation fails. - -Note that unlike in Perl 5's C<eval>, C<EVAL> does not catch any exceptions or control -exceptions. - -=item EVALFILE - - multi EVALFILE (Str $filename ; Grammar :$lang = Perl6) - -Behaves like, and replaces Perl 5 C<do EXPR>, with optional C<$lang> -support. - -=item exit - - multi exit (Int $status = 0) - -Stops all program execution, and returns C<$status> to the calling environment. - -An exit runs all appropriate scope-leaving blocks such as C<LEAVE>, C<KEEP>, -and C<UNDO>, followed by all C<END> blocks, followed by all C<DESTROY>s that -do more than just reclaim memory, and so cannot be skipped because -they may have side effects visible outside the process. If run from -an embedded interpreter, all memory must also be reclaimed. - -Exit can also be called from an C<END> block: in that case only the C<$status> -to be returned to the calling environment, is changed. This does end the -execution of the END block in question, but will still execute any remaining -C<END> blocks. - -Any threads started with the C<:app_lifetime> parameter (which is basically -any asynchronous action started with primitives other than C<Thread.new>), -will be terminated on exit. - -=item sleep - - multi sleep ( Real $for --> Nil ) - multi sleep ( Whatever --> Nil ) - -Attempt to sleep for up to C<$for> seconds, or forever when the argument is C<*>. -Implementations are obligated -to support sub-second resolutions if that is at all possible. You may pass -any of C<Int>, C<Num>, C<Rat>, or C<Duration> types as an argument, since those -all do C<Real>, but regardless of which type you use, they are always scaled to -seconds. (An implementation is allowed to provide access to a platform-specific -function based on, say, nanoseconds, but Perl 6 does not presume to know -how much resolution clocks will have in the future, so requires everything to -be specified in fractional seconds.) - -This function returns nothing; use C<sleep-timer> if you wish it to -return how much time is remaining on the specified sleep. However, -if you really just want to keep rolling over in bed until your alarm -goes off at a particular time, use C<sleep-till> instead, since it -is not subject to relative clock drift. - -All of these sleep functions work only on the current thread. - -=item sleep-timer - - multi sleep-timer ( Real $for --> Duration ) - -Just like C<sleep>, but returns the amount of time remaining to sleep -as a C<Duration> (which will be 0 if the call was not interrupted). -Depending on the platform and the system call involved, this may or -may not require emulation by interrogating the clock before and after. -For those systems whose system call returns the remaining time, this -can be more efficient than interrogating the clock twice yourself, -However, the optimizer is encouraged to change this to a bare C<sleep> -in sink context. (But then, you might as well just write that in -the first place.) - -=item sleep-till - - multi sleep-till ( Instant $till --> Bool ) - -Just like C<sleep>, but checks the current time and goes back to -sleep if accidentally woken up early, to guarantee waiting until the -specified time. Returns True if the function actually waited, or if -the specified time happens to be the present moment. Returns False -if you asked to sleep until a time in the past. - -=item die - - multi die (@LIST) - -Throws a fatal Exception. The default exception handler prints each element of -the list to $*ERR (STDERR). - -=item fail - - multi fail (Str $message) - -Can only be called inside a routine and causes the routine to C<return> an -unthrown exception; a C<Failure> object which stringifies to C<$message>. -If C<use fatal> is in effect where the routine was called from, it throws -the exception. - -=back - - -=head2 Conversions - -=over - -=item bless - - method bless(*@protos, *%init_args ) - -Calling C<bless> on any invocant (but typically a type object) to create a new -object with the same class as the invocant. - -The C<.bless> method takes the first positional argument indicating a -candidate to bless. If absent, the object builder implicitly asks the -representation what its preferred, er, representation is. - -C<bless> automatically creates an object appropriate to the -representation of the class, then calls all appropriate C<BUILD> -routines for the current class, which initializes the object in -least-derived to most-derived order. See L<S12/Objects> for more -detailed information on object creation. - -=item chrs - -=item ords - -=item chr - -=item ord - - multi sub chrs( Int *@grid --> Str ) - multi method ords( Str $string: --> List of Int ) is export - multi method chr( Int $grid: --> Str ) is export - multi method ord( Str $string: --> Int ) is export - -C<chrs> takes zero or more integer grapheme ids and returns the -corresponding characters as a string. If any grapheme id is used -that represents a higher abstraction level than the current -lexical scope supports, that grapheme is converted to the -corresponding lower-level string of codepoints/bytes that would -be appropriate to the current pragmatic context, just as any other Str -would be downgraded in context. - -C<ords> goes the other direction; it takes a string value and returns -character values as integers. The definition of character is pragma dependent. -Normally it's a grapheme id, but under codepoints or bytes scopes, -the string is coerced to the appropriate low-level view and interpreted -as codepoints or bytes. Hence, under "use bytes" you will never see a -value larger than 256, and under "use codepoints" you will probably never see a -value larger than 0x10ffff. The only guarantee under "use graphemes" -(the default) is that the number returned will correspond to the -codepoint of the precomposed codepoint representing the grapheme, if -there is such a codepoint. Otherwise, the implementation is free to -return any negative unique 32-bit id. (The C<chr> function -will know how to backtranslate such ids properly to codepoints or -bytes in any context. Note that we are assuming that every codepoint's -context knows its normalization preferences, and every byte's context -also knows its encoding preferences. (These are knowable in the -lexical scope via the $?NF and $?ENC compile-time constants).) - -The C<chr> and C<ord> variants are restricted to processing a single -character. As is customary, you may pass a longer string to C<ord>, -but only the first character will be translated. - -=item item - - multi item ( $item --> Item ) - -Forces generic Item context on its argument, and returns it. - -=item list - - multi list ( Iterable $item --> List ) { $item.iterator.list } - multi list ( List \iter --> List ) { iter } - -Almost a no-op; just makes sure that $item can be iterated. - -=item flat - - multi flat ( *@list --> List ) - -Forces flat context on its arguments, and returns them. -The heavy work is done by the C<*@> binding. - -=item lol - - multi lol ( **@list --> List ) - -Forces the argument list to be evaluated in lol ("list of lists") context. -(Subscripts treat such a list of lists as a multidimensional slice.) -Any sublist within the top level of the outer list will be transformed into an item (Scalar). -The work is actually done by the binding to the C<**@> parameter. -See also the more general C<.tree> method, which defaults to itemizing every level. - -=item hash - -The C<hash> contextualizer - - multi hash ( *@list --> Hash ) - -Forces the argument list to be evaluated in hash context. -The expression is evaluated in list context (flattening any C<Capture>s), -then a hash will be created from the list, taken as a list of C<Pair>s. -(Any element in the list that is not a C<Pair> will pretend to be a key -and grab the next value in the list as its value.) Equivalent to -C<%()> (except that empty C<%()> means C<%($/)>, while -empty C<hash()> means an empty hash). - -=item gist - - multi gist( |item --> Str ) - multi method gist( Mu $item: --> Str ) - -Produces an informal string coercion, something a human might want -to see if debugging, for instance. Each type may decide its own -gist representation. C<Mu.gist> just calls C<.perl>, but any type's -C<gist> method may override this to remove metainfo that a human -would find to be cluttery or redundant, or to format a composite value -with suitable whitespace to tell the bits apart, or to trim down an -infinite list to something slightly shorter. - -C<gist> is used as a last-ditch string coercion on each individual -argument of various human-facing output routines, specifically -C<say>, C<note>, C<warn>, and any non-exceptional arguments to C<die>. -The C<print> function is specifically excluded, since it's outputting -to a printer. C<:-)> - -=item :16, :8, :2, :10 - - multi prefix:<:16> ( Str $hexstr --> Num ) - multi prefix:<:8> ( Str $octstr --> Num ) - multi prefix:<:2> ( Str $binstr --> Num ) - multi prefix:<:10> ( Str $decstr --> Num ) - etc. - -Interprets string as a number, with a default -hexadecimal/octal/binary/decimal radix. Any radix prefix (0b, 0d, 0x, 0o) -mentioned inside the string will override this operator (this statement is true: -10 == :8("0d10")), except 0b and 0d will be interpreted as hex digits by :16 -(C<hex("0d10") == :16 "0d10">). C<fail>s on failure. - -These aren't really functions, syntactically, but adverbial forms that -just happen to allow a parenthesize argument. But more typically you'll -see - - :4<222> - :16<deadbeef> - -and such. - -Replaces Perl 5 C<hex> and C<oct>. - - -=back - - -=head2 OS - -=over - -=item gethost - - multi gethost( --> OS::Name ) - multi gethost( Str $name, OS::Addfamily :$type --> OS::Name ) - multi method gethost( OS::Addr $addr: --> OS::Name ) is export - multi method gethost( URI $uri: --> OS::Name ) is export - -The C<gethost> function operates on host naming or address information -and returns an C<OS::Name>. An C<OS::Name> is, minimally: - - class OS::Name { - has Str $.name; - has OS::Addr $.addr; - has Array of Str @.aliases; - has Array of OS::Addr @.addrs; - } - -Such names can apply to anything which has a name that maps -to an address, however, in this case the name is a hostname -and the address is some sort of network identifier (e.g. -an IPV4 address when resolving hosts that have IPV4 addresses). - -When stringified, an C<OS::Name> yields its name. When -stringified, an C<OS::Addr> yields its address in an -appropriate text format (e.g. "10.1.2.3" for an IPV4 address). - -The optional C<type> adverb can be passed when resolving a hostname, -and will filter the result to only those addresses that are of -the appropriate address family. This feature may be supported by -the underlying operating system, or Perl may emulate it. - -Examples: - - say "Connection from {$socket.peer.gethost}"; - my $address = gethost("foo.example.com").addr; - my $hostname = gethost(:addr<"10.1.2.3">); - -=item chroot - - multi chroot ( Str $path = CALLER::<$_> --> Bool ) - -On POSIX systems, changes the process context of the current process such -that the "root" directory becomes C<$path> and all rooted paths -(those that begin with a leading path separator) are relative to -that path. For security reasons, many operating systems limit -this functionality to the superuser. The return value will be -true on success. - -=item getlogin - - multi getlogin ( --> Str ) - -Returns the username of the account running the program. This may -not be as secure as using C<getpwuid> on some platforms. - -=item kill - - multi kill ( OS::Signal $signal, Bool :$group, *@pids --> Bool ) - multi method kill ( Proc::PID $pid: OS::Signal $signal?, Bool :$group --> Bool ) - -Sends the given C<$signal> to the process(es) given and returns a boolean -value indicating success (true) if all of the processes existed and were -sent the signal and failure (false) if any of the processes did not exist -or the signal could not be delivered to them. - -The C<$signal> can be initialized from an integer signal number or a -string. Common signals are: - - KILL - stop the process, do not allow it to exit gracefully - TERM - stop the process, allow it to exit gracefully - HUP - Hangup, often used as a request to re-run from scratch - STOP - Pause execution - CONT - Continue after a STOP - -Consult your operating system documentation for the full list -of signal names and numbers. For compatibility, a signal name -may be prefixed with "SIG". - -The method form may omit the signal. In this case, the default signal is -C<'TERM'>. - -If the C<:group> named parameter is passed, C<kill> will attempt to -send the signal to a process I<group> rather than a single process. -This functionality is platform-specific. - -The special signal C<0> can be sent which does not actually deliver a -signal at all, and is used to determine if processes are still running: - - say "Still running" if $proc.kill(0); - -=item run - -=item shell - - - multi shell ( $expression, :$cwd = $CWD, :%env = %*ENV --> Proc ) - multi run ( *$cmd, *@args, :$cwd = $CWD, :%env = %*ENV --> Proc ) - -C<shell> and C<run> execute an external program, and return control to -the caller once the program has exited. - -C<shell> goes through the system shell (C<cmd> on windows, C</bin/sh> -on Unixish systems), thus interpreting all the usual shell meta characters. - -C<run> treats the first argument as an executable name, and the rest of the -positional arguments as command line arguments that are passed to the -executable without any processing (except that it encodes Strings to buffers -first, as does C<shell>). - -Both return a C<Proc> object, which boolifies to C<True> if the program had -a successful exit and C<False> otherwise. The C<status> method on a C<Proc> -provides the exit code. If a C<False> C<Proc> is sunk, an exception will be -thrown of type C<X::Proc::Unsuccessful>. - -If you want to execute an external program asynchronously (as in, not waiting -for it to be finished), you will need C<Proc::Async>, as specced in -L<S17-concurrency>. - -=item runinstead - - multi runinstead ( ; Str $path, *@args ) - multi runinstead ( ; Str $command ) - -Identical to C<run> except that it never returns. The executed program -replaces the currently running program in memory. - -=item syscall - -=back - -=head2 Concurrency - -There are higher-level models of concurrency management in Perl (see -L<S17/Concurrency>). These functions are simply the lowest level -tools - -=over - -=item fork - - sub Processes::fork( --> Proc ) - -Creates a copy of the current process. Both processes return from -C<fork>. The original process returns -the I<child> process as a C<Proc> object. The newly created process -returns the I<parent> process as a C<Proc> object. As with -any Proc object, the child process object numifies to the -process ID (OS dependent integer). However, the parent process object -numifies to C<0> so that the child and parent can distinguish each other. - -Typical usage would be: - - if !defined(my $pid = fork) { - die "Error calling fork: $!"; - } elsif $pid == 0 { - say "I am the new child!"; - exit 0; - } else { - say "I am the parent of {+$pid}"; - wait(); - } - -=item wait - - multi method wait( Proc $process: *%options --> Proc::Status ) - - multi wait ( Proc $process = -1, *%options --> Proc::Status ) - -Waits for a child process to terminate and returns the status -object for the child. This status object will numify to the process -ID of the child that exited. - -Important Proc::Status methods: - - .exit - Numeric exit value - .pid - Process ID - .signal - Signal number if any, otherwise 0 - -For historical reasons there is a C<.status> method which is equal to: - - ($status.exit +< 8) +| $status.signal - -If C<$process> is supplied, then wait will only return when the given process -has exited. Either a full C<Proc> object can be passed, or just a -numeric process ID. A C<-1> explicitly indicates that wait should return -immediately if any child process exits. - -When called in this way, the returned C<Proc::Status> object -will have a C<.pid> of C<-1> (which is also what it numifies to) if -there was no such process to wait for. - -The named options include: - -=over - -=item blocking - -Defaults to true. If set to false, this forces wait to return immediately. - -=item WNOHANG - -Exists for historical compatibility. C<WNOHANG => 1> is identical to -C<blocking => False>. - -=back - -=back - -=head2 Pending Apocalypse - -The following functions are classified by Apocalypse/Synopsis numbers. - -=over 4 - -=item A/S??: OS Interaction - -chroot crypt getlogin /[get|set][pw|gr].*/ kill setpgrp setpriority -times - -... These are probably going to be part of POSIX, automatically imported to GLOBAL B<if> the platform is the right one - -=back - -=head2 Default Functions - -These functions are exported into the default namespace - -=over - -=item all -- see S32-setting-library/Containers.pod - -=item any -- see S32-setting-library/Containers.pod - -=item cat -- see S32-setting-library/Containers.pod - -=item categorize -- see S32-setting-library/Containers.pod - -=item classify -- see S32-setting-library/Containers.pod - -=item defined -- see S32-setting-library/Basics.pod - -=item grep -- see S32-setting-library/Containers.pod - -=item first -- see S32-setting-library/Containers.pod - -=item join -- see S32-setting-library/Containers.pod - -=item keys -- see S32-setting-library/Containers.pod - -=item kv -- see S32-setting-library/Containers.pod - -=item map -- see S32-setting-library/Containers.pod - -=item max -- see S32-setting-library/Containers.pod - -=item min -- see S32-setting-library/Containers.pod - -=item none -- see S32-setting-library/Containers.pod - -=item one -- see S32-setting-library/Containers.pod - -=item pairs -- see S32-setting-library/Containers.pod - -=item pick -- see S32-setting-library/Containers.pod - -=item print -- see S32-setting-library/IO.pod - -=item printf -- see S32-setting-library/IO.pod - -=item reduce -- see S32-setting-library/Containers.pod - -=item reverse -- see S32-setting-library/Containers.pod - -=item roundrobin -- see S32-setting-library/Containers.pod - -=item say -- see S32-setting-library/IO.pod - -=item shape -- see S32-setting-library/Containers.pod - -=item sort -- see S32-setting-library/Containers.pod - -=item srand -- see S32-setting-library/Numeric.pod - -=item undefine -- see S32-setting-library/Basics.pod - -=item uri -- see S32-setting-library/IO.pod - -=item values -- see S32-setting-library/Containers.pod - -=item warn -- see S32-setting-library/Any.pod - -=item zip -- see S32-setting-library/Containers.pod - -=back - -=head2 Non-default Functions - -These functions which existed in Perl 5 still exist but are not part of the default -namespace any more. - -=head3 Container - -The following functions can now be found in or replaced by something in the Container -modules. - -delete, exists, pop, push, shift, splice, unshift - -=head3 Numeric - -See L<S32/Numeric>. - -=head3 IO - -The following functions can now be found in or replaced by something in the IO -modules. - -accept, bind, binmode, chdir, chmod, chown, close, closedir, connect -eof, fcntl, fileno, flock, getc, getsockname, getsockopt, glob, ioctl, link, listen -lstat, mkdir, open, opendir, pipe, print, printf, read, readdir, readline, readlink -readpipe, recv, rename, rewinddir, rmdir, say, seek, seekdir, select, send, setsockopt -shutdown, socket, socketpair, stat, symlink, sysopen, sysread, sysseek -syswrite, tell, telldir, truncate, umask, unlink - -=head3 Temporal - -The following functions can now be found in or replaced by something in the Temporal -modules. - -gmtime, localtime, time - -=head3 String - -The following functions can now be found in or replaced by something in the String -module. - -chop, chomp, index, lc, pack, rindex, split, sprintf, substr, uc, -ucfirst, unpack - -=head2 Obsolete Functions - -Some of these are obsoleted only as general functions, and are still available by using -the right packages. Others are obsoleted in that they're keywords, rather than functions -(these are in their own section, below). - -=over 4 - -=item % - - $num1 % $num2 - -Does a floating point modulo operation, i.e. 5.5 % 1 == 0.5 and 5 % 2.5 == 0. - -=item dbmopen, dbmclose - - use DB_File; - -=item dump - -Dumped. Restoring from core dumps is in any event not very useful on modern -virtual-memory operating systems. Startup acceleration should be accomplished -using a precompiler of some kind (details will be very implementation specific), -or a pre-forking daemon such as Perl 5's App::Persistent (which will be an -external module when it is ported). - -=item each - -See .pairs() method, above. - -=item endpwent, endgrent, endservent, endprotoent, endnetent, endhostent - -The NameServices role in S16 covers most of these. - -=item format, formline - -See Exegesis 7. - -=item getgrgid, getgrnam, getpwnam, getpwuid - -The User and Group roles in S16 cover most of these. - -=item getpwent, getgrent, getservent, getnetent, gethostent - -The NameServices role in S16 covers most of these. - -=item length() - -This word is banned in Perl 6. You must specify units. In practice, this probably means -you want Str.chars(), although it could be Str.bytes(), or even something else. See -S32-setting-library/String for details. - -=item lcfirst - -Retired due to lack of use case - -=item msgctl, msgget, msgrcv, msgsnd - -See IPC::SysV - -=item local - -Replaced by C<temp> which, unlike C<local>, defaults to not changing the value. - -=item lock - -See L<S17/Concurrency>. C<lock> has been replaced by C<Lock.new> and methods -on the C<Lock> object. - -=item quotemeta - -Because regex escaping metacharacters can easily be solved by quotes -(L<S05/Simplified lexical parsing of patterns>), and variables are not -automatically interpolated (L<S05/Variable (non-)interpolation>), C<quotemeta> -is no longer needed. - -Shell escaping should be handled by passing arguments to L<run>, or with code -that speaks the language of a specific shell. - -=item pos - -There is no C<pos> function in Perl 6 because that would not allow a string -to be shared among threads. Generally you want to use C<$/.to> for that now, -or keep your own position variable as a lexical. - -=item prototype - - &func.meta.signature; - &func.^signature; - -=item ref - -There is no ref() any more, since it was almost always used to get -the type name in Perl 5. If you really want the type name, you can -use C<$var.WHAT.perl>. If you really want P5 ref -semantics, use C<Perl5::p5ref>. - -But if you're just wanting to test against a type, you're likely better off -performing an C<isa> or C<does> or C<can>, or just C<$var ~~ TYPE>. - -=item reset - -Was there a I<good> use for this? - -=item semctl, semget, semop - -See IPC::SysV; - -=item setpwent, setgrent, setservent, setprotoent, setnetent, sethostent - -The NameServices role in S16 covers most of these. - -=item shmctl, shmget, shmread, shmwrite - -See IPC::SysV; - -=item study - -Algorithm was too Anglo-centric. Could be brought back if generalized somehow. - -=item tie, tied - -These are replaced by container types. The compiler is free to assume -that any lexical variable is never going to change its container type -unless some representation is made to that effect in the declaration. -Note: P5's tied() is roughly replaced by P6's variable(). - -XXX Examples? - -my $foo is ....? is tie -the meta operation on the container type for 'rebless' - -macro tie ( $var, $class, *@args ) { CODE { variable($var).meta.rebless( $class, *@args ) } } ) - -endXXX - -=item untie - -See notes on "tie", above, but basically these are replaced with container classes. - -=item vec - -Should replace C<vec> with declared buffer/array of C<bit>, C<uint2>, -C<uint4>, etc. - -=item waitpid - -C<wait> can now be called with or without an optional process/pid. - -=item write - -See Exegesis 7. - -=back - -=head3 Keywords - -The following were listed in Perl 5's perlfunc, but should now be considered keywords -rather than functions. - -last, my, next, no, our, package, return, sub, use - -=head1 Default Export Questions - -Not sure whether these are exported by default or not. Also, many may no longer exist; if -so, they should be entered in the "Obsolete" section. - -=over - -=item Signal-related - -alarm -kill - -=item OS or library related - - chroot - crypt - getlogin - getpeername -- should this go on Pipe? - -OS objects: - - --Process - getpgrp - getppid - getpriority - setpgrp - setpriority - - --Service - getservbyname - getservbyport - - --Protocol - getprotobyname - getprotobynumber - - --Network - getnetbyaddr - getnetbyname - - --Host - gethostbyaddr - gethostbyname - -=item Flow control - -succeed -proceed -redo - -=item Other - -caller -chr -die -do -EVAL -exec -exit -fork -goto -hex -import -int -oct -ord -require -scalar -sleep -state -syscall -system -times -utime -wait - -=back - -=head1 AUTHORS - - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Carlin Bingham <carlin@theintersect.org> - Elizabeth Mattijsen <liz@wenzperl.nl> - Brent Laabs <bslaabs@gmail.com> - -=for vim:set expandtab sw=4: diff --git a/S31-pragmatic-modules.pod b/S31-pragmatic-modules.pod deleted file mode 100644 index 921bd54e..00000000 --- a/S31-pragmatic-modules.pod +++ /dev/null @@ -1,70 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -[DRAFT] Synopsis 31: Pragmatic Modules - -=head1 VERSION - - Created: 24 Feb 2009 - - Last Modified: 24 Feb 2009 - Version: 1 - -The document is a draft. - -=head1 Overview - -It is a general policy in Perl 6 that any pragma designed to influence -the surface behavior of a keyword is identical to the keyword itself, unless -there is good reason to do otherwise. On the other hand, pragmas designed -to influence deep semantics should not be named identically, though of -course some similarity is good. - -All floating point IEEE modes must be lexically available via pragma except in cases -where that would entail heroic efforts to bypass a braindead platform. - -XXX FIX: I (Tim Nelson) have no clue as to what the above entails, so the spec does not -reflect this XXX - -=head1 Pragmata - -=over - -=item use autoindex -- see S09-data.pod - -=item use bytes -- see S05-regex.pod - -=item use chars -- see S05-regex.pod - -=item use codes -- see S05-regex.pod - -=item use graphs -- see S05-regex.pod - -=item use m :foo -- see S05-regex.pod - -=item use MONKEY-TYPING -- see S12-objects.pod - -=item use PDL -- see S09-data.pod - -=item use regex :foo -- see S05-regex.pod - -=item use rule :foo -- see S05-regex.pod - -=item use rx :foo -- see S05-regex.pod - -=item use s :foo -- see S05-regex.pod - -=item use token :foo -- see S05-regex.pod - -=item use oo :closed :final -- see S12-objects.pod - -=back - -=head1 AUTHORS - - Tim Nelson <wayland@wayland.id.au> - Larry Wall <larry@wall.org> - -=for vim:set expandtab sw=4: diff --git a/S32-setting-library/Basics.pod b/S32-setting-library/Basics.pod deleted file mode 100644 index ab33af6b..00000000 --- a/S32-setting-library/Basics.pod +++ /dev/null @@ -1,209 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Basics - -=head1 VERSION - - Created: 19 Mar 2009 extracted from S29-functions.pod - - Last Modified: 29 June 2012 - Version: 5 - -The document is a draft. - -=head1 Roles - -=head2 Mu - -The following are defined in the C<Mu> class: - - class Mu { - multi method defined ($self: --> Bool:D ) is export {...} - multi method defined ( $self: ::role --> Bool:D ) is export { ... } - multi method new(*%opts) { ... } - - method not() {...} - method so() {...} - - } - -=over - -=item defined - - multi method defined ( $self: --> Bool:D ) is export - multi method defined ( $self: ::role --> Bool:D ) is export - -C<defined> returns true if the parameter has a value and that value is -considered defined by its type, otherwise false is returned. - -Same as Perl 5, only takes extra optional argument to ask if value is defined -with respect to a particular role: - - defined($x, SomeRole); - -A value may be defined according to one role and undefined according to another. -Without the extra argument, defaults to the definition of defined supplied by -the type of the object. - -=item new - - multi method new(*%attrs) { } - -Creates a new object of the same type as the object is called on, -setting attributes with public accessors to the values provided -by the named arguments to C<new>. - -=item undefine - - multi undefine( Any $thing is rw --> Any ) - -Takes any variable as a parameter and attempts to "remove" its -definition. For simple scalar variables this means assigning -the undefined value to the variable. For objects, this is equivalent -to invoking their undefine method. For arrays, hashes and other -complex data, this might require emptying the structures associated -with the object. - -In all cases, calling C<undefine> on a variable -should place the object in the same state as if it was just -declared. - -=item not - - method not() {...} - -=item so - - method so() {...} - -XXX Copied from S02 -- should it be deleted from there? - -The definition of C<.Bool> for the most ancestral type (that is, the -C<Mu> type) is equivalent to C<.defined>. Since type objects are -considered undefined, all type objects (including C<Mu> itself) -are false unless the type overrides the definition of C<.Bool> -to include undefined values. Instantiated objects default to true -unless the class overrides the definition. Note that if you could -instantiate a C<Mu> it would be considered defined, and thus true. -(It is not clear that this is allowed, however.) - -=back - -=head2 Any - -The following are defined in the C<Any> class: - - class Any is Mu { - multi method clone (::T $self:, *%attributes --> T ) {...} - - multi method can ($self:, Str $method --> Callable ) {...} - multi method does ($self:, $type --> Bool ) {...} - multi method isa ($self:, $type --> Bool ) {...} - multi method perl ( Mu $o: --> Str ) is export {...} - multi method warn ( Mu $o: --> Any ) is export {...} - } - -=over - -=item can - - multi method can ($self:, Str $method --> Callable ) - -If there is a multi method of name C<$method> that can be called on -C<$self>, then a closure is return which has C<$self> bound to the position -of the invocant. - -Otherwise an undefined value is returned. - -=item clone - - multi method clone (::T $self --> T --> Any ) - multi method clone (::T $self, *%attributes --> T --> Any ) - -The first variant returns an independent copy of C<$o> that is equivalent -to C<$o>. - -The second variant does the same, but any named arguments override an -attribute during the cloning process. - -=item does - - multi method does ($self:, $type --> Bool ) - -Returns C<True> if and only if C<$self> conforms to type C<$type>. - -=item isa - - multi method isa ($self:, $type --> Bool ) - -Returns C<True> if a the invocant an instance of class C<$type>, or -of a subset type or a derived class (through inheritance) of C<$type>. - -=item perl - - multi method perl ( Mu $o: --> Str ) is export - -Returns a perlish representation of the object, so that calling C<EVAL> -on the returned string reproduces the object as accurately as possible. - -=item warn - - multi method warn ( Mu $o: --> Any ) is export - -Throws a resumable warning exception, which is considered a control -exception, and hence is invisible to most normal exception handlers. -The outermost control handler will print the warning to C<$*ERR> -(which usually finds C<$PROCESS::ERR>; see C<Synopsis 16: IPC / -IO / Signals> for details). After printing the warning, the exception -is resumed where it was thrown. To override this behavior, catch the -exception in a CONTROL block. A quietly {...} block is the opposite of a -try {...} block in that it will suppress any warnings but pass fatal -exceptions through. - -To simply print to C<$*ERR>, please use C<note> instead. C<warn> -should be reserved for use in threatening situations when you don't -quite want to throw an exception. - -=back - -=head2 Pattern - - role Pattern { - method ACCEPTS($self:, $other) {...} - } - -=over - -=item ACCEPTS - -Used in smartmatching; see S03. - -=back - -=head2 Scalar - -C<Scalar> provides the basic tools for operating on undifferentiated -scalar variables. All of the following are exported by default. - -=over - -=item VAR - -This is not really a method, but some kind of macro. See L<S12> for details. - -=back - -=head1 AUTHORS - - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - diff --git a/S32-setting-library/Callable.pod b/S32-setting-library/Callable.pod deleted file mode 100644 index 4328a71f..00000000 --- a/S32-setting-library/Callable.pod +++ /dev/null @@ -1,135 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Callable - -=head1 VERSION - - Created: 26 Feb 2009 - - Last Modified: 5 Nov 2013 - Version: 3 - -The document is a draft. - -This document documents Code, Block, Signature, Capture, Routine, Sub, Method, Submethod, -and Macro. - -=head1 Callable - - role Callable {...} - -The C<Callable> role implies the ability -to support C<< postcircumfix:<( )> >>. - -=head1 Code - - class Code does Callable {...} - -Base class for all executable objects. - -=over - -=item signature - - method signature( --> Signature ) - -=item assuming - - method assuming( Code $executable: *@curried_positionals, *%curried_named --> Code) - -C<assuming> primes C<$executable>, returning a C<Code> object that, -when executed, will use curried arguments as well as any additionally -supplied arguments. See L<S06/Priming>. - -=item defined - - method defined( --> Bool ) - -For C<Code>, the C<.defined> method returns whether a body has -been defined. A body consisting only of C<...>, C<!!!>, or C<???> -(with optional message arguments) does not count as defined. - -To test if a name has been declared, look up the symbol in the -appropriate symbol table. - -=back - -=head1 Block - - # Executable objects that have lexical scopes - class Block is Code does Callable { - method next() {...} - method last() {...} - method redo() {...} - method leave() {...} - method labels() {...} - method as() {...} # See L<S12/Introspection> and L<S02/Value types> - } - -=head1 Signature - - class Signature {...} - -The C<Signature> class is used for function parameters, as the left-hand -side of a binding, and for the argument to declarators like C<my>. -See L<S02/Signature objects>, L<S06/Signatures>, and L<S06/Signature Introspection> - -=head1 Capture - - class Capture does Positional does Associative {...} - -The C<Capture> class is used for the arguments of function calls -and the right-hand side of a binding. -See L<S02/Lists, parameters, and Captures> - -=head1 WrapHandle - - class WrapHandle {...} - -=head1 Routine - - class Routine is Block { - method wrap(Code $code --> WrapHandle ) {...} - method unwrap(Wraphandle $original --> Routine ) {...} - method name( --> Str ) {...} - method multi( --> Bool ) {...} - } - -=over - -=item unwrap - -See L<S06/Wrapping>. - -=item wrap - - method wrap(Code $code) {...} - -See L<S06/Wrapping>. - -=back - -=head1 Sub - - class Sub is Routine {...} - -=head1 Method - - class Method is Routine {...} - -=head1 Submethod - - class Submethod is Routine {...} - -=head1 Macro - - class Macro is Routine {...} - -=head1 AUTHORS - - Tim Nelson <wayland@wayland.id.au> - Larry Wall <larry@wall.org> - diff --git a/S32-setting-library/Containers.pod b/S32-setting-library/Containers.pod deleted file mode 100644 index 2515a7f3..00000000 --- a/S32-setting-library/Containers.pod +++ /dev/null @@ -1,1547 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Containers.pod - -=head1 VERSION - - Created: 19 Feb 2009 extracted from S29-functions.pod - - Last Modified: 23 Apr 2015 - Version: 51 - -=head1 Function Roles - -=head2 Positional - - role Positional {...} - -The C<Positional> role implies the ability to support C<< postcircumfix:<[ ]> >>. - -=head2 Iterable - - role Iterable {...} - -The C<Iterable> role implies the ability to support sequential access through -iterators. There is also limited support for en-passant use of -C<< postcircumfix:<[ ]> >>, but since some Iterables may only be iterated -once, not all Iterables are considered Positional. - -=head2 Associative - - role Associative {...} - -The C<Associative> role implies the ability to support C<< postcircumfix:<{ }> >>. - -=over - -=item cat - - multi cat( **@list --> Cat ) - -C<cat> reads arrays serially rather than in parallel as C<zip> does. It -returns all of the elements of the containers that were passed to it -like so: - - cat(@a;@b;@c); - -Typically, you could just write C<(@a,@b,@c)>, but sometimes -it's nice to be explicit about that: - - @foo := [[1,2,3],[4,5,6]]; say cat(||@foo); # 1,2,3,4,5,6 - -In addition, a C<Cat> in item context emulates the C<Str> interface lazily. - -[Conjecture: Cats should maybe just do the lazy strings, and leave flattening -to other operators.] - -=item roundrobin - - multi roundrobin( **@list --> Seq ) - -C<roundrobin> is very similar to C<zip>. The difference is that -C<roundrobin> will not stop on lists that run out of elements but -simply skip any undefined value: - - my @a = 1; - my @b = 1..2; - my @c = 1..3; - for roundrobin( @a; @b; @c ) -> $x { ... } - -will get the following values for C<$x>: C<1, 1, 1, 2, 2, 3> - -=item zip - - multi zip ( **@list --> Seq ) - multi infix:<Z> ( **@list --> Seq ) - -zip takes any number of arrays and returns one tuple for every index. -This is easier to read in an example: - - for zip(@a;@b;@c) -> $nth_a, $nth_b, $nth_c { - ... - } - -Mnemonic: the input arrays are "zipped" up like a zipper. - -The C<zip> function defaults to stopping as soon as any of its lists -is exhausted. This behavior may be modified by conceptually extending -any short list using C<*>, which replicates the final element. - -If all lists are potentially infinite, an evaluation in C<eager> -context will automatically fail as soon as it can be known that all -sublists in the control of iterators of infinite extent, such as -indefinite ranges or arbitrary replication. If it can be known at -compile time, a compile-time error results. - -C<Z> is an infix equivalent for zip: - - for @a Z @b Z @c -> $a, $b, $c {...} - -In lol context a list of C<List> is returned instead of a flat list. - -=back - -=head2 List - -The following are defined in the C<List> class: - - class List does Positional {...} - -=over - -=item new - - multi method new(*@args --> List ) - -Constructs an C<List> that can visit all iterable elements of all the arguments. - -=item list - - sub list(*@args --> List ) - -Constructs a C<List> that can visit all iterable elements of all the arguments. - -=item cat - - multi cat ( @values --> Cat ) - -Returns a C<Cat> object, a concatenated version of the list that does the C<Str> -interface, but generates the string lazily to the extent permitted -by the pattern of access to the string. Its two primary uses are -matching against an array of strings and doing the equivalent of a -C<join('')>, except that C<join> is always eager. However, a C<Cat> -in an interpolative context is also effectively eager, since the -interpolator needs to know the string length. List context is lazy, -though, so a C<cat> of a C<cat> is also lazy, and in fact, you just -get a flat cat because C<cat> in a list context is a no-op. The C<Cat> -interface also lets you interrogate the object at a particular string -position without actually stringifying the element; the regex engine -can make use of this to match a tree node, for instance, without -serializing the entire subtree. - -Accessing a filehandle as both a filehandle and as a C<Cat> is undefined, -because lazy objects are not required to be as lazy as possible, but may -instead choose to precalculate values in semi-eager batches to maximize -cache hits. - -=item classify - - multi method classify ( @values: &mapper --> Hash ) - multi method classify ( @values: %mapper --> Hash ) - multi method classify ( @values: @mapper --> Hash ) - multi classify ( &mapper, *@values --> Hash ) - multi classify ( %mapper, *@values --> Hash ) - multi classify ( @mapper, *@values --> Hash ) - -C<classify> transforms a finite list or array of values into a hash -representing the classification of those values according to a mapper; -each hash key represents the classification for one or more of the -incoming list values, and the corresponding hash value contains -an array of those list values classified by the mapper into the category -of the associated key. For example: - - @list = (1, 2, 3, 4); - (:@even, :@odd) := @list.classify: { $_ % 2 ?? 'odd' !! 'even' }; - (:@even, :@odd) := classify { $_ % 2 ?? 'odd' !! 'even' }, @list; # same - -In this example, @even will contain all even numbers from C<@list> -and C<@odd> will contain all odd numbers from C<@list>. Please note that -for performance reasons, an implementation is free to C<bind> values to the -resulting arrays. So you should consider these arrays to be immutable. - -To simply transform a list into a hash of arrays: - - %cars_by_color := @cars.classify: { .color }; - %cars_by_color := classify { .color }, @cars; # same - red_car_owners(%cars_by_color<red>.map:{.owner}); - -A mapper may be any unary function, hash, or array. -Values that have no mapping will be classified under an undefined -failure key (whatever is returned by the mapper in use). [Conjecture: -if a hash comes with a default value, it can map anything.] - -C<classify> always assumes that the mapper returns a single value. However, -this may also be a L<List> to indicate a multi-level classification. In -such a case, only the classification of the lowest level, will actually yield -a Hash of Lists. All higher up classifications, will necessarily always be a -Hash of Hashes. Please note that all Lists must have the same number of -elements. - -To categorize values into multiple categories, see C<categorize>. - -=item categorize - - multi method categorize ( @values: &mapper --> Hash ) - multi method categorize ( @values: %mapper --> Hash ) - multi method categorize ( @values: @mapper --> Hash ) - multi categorize ( &mapper, *@values --> Hash ) - multi categorize ( %mapper, *@values --> Hash ) - multi categorize ( @mapper, *@values --> Hash ) - -Like C<classify>, C<categorize> transforms a finite list or array of values -into a hash representing the categorizations of those -values according to a mapper; each hash key represents one possible -categorization for one or more of the incoming list values, and -the corresponding hash value contains an array of those list values -categorized by the mapper into the category of the associated key. -Please note that for performance reasons, an implementation is free to C<bind> -values to the resulting arrays. So you should consider these arrays to be -immutable. - -Unlike C<classify>, C<categorize> always assumes that the return -value of the mapper is a list of categories that are appropriate to -the current value. Hence, if the mapper returns C<()>, the value -is discarded rather than being stored under any key. On the -other hand, if the mapper returns a list of categories, the value in -question will be pushed into multiple hash locations (while C<classify> -would merely make a key out of the list returned from the mapper). However, a -category may also be a L<List> to indicate a multi-level categorization. In -such a case, only the categorization of the lowest level, will actually yield -a Hash of Lists. All higher up categorizations, will necessarily always be a -Hash of Hashes. Please note that all Lists must have the same number of -elements. - -=item grep - - multi method grep ( @values: Matcher $test --> Iterable ) - multi grep ( Matcher $test, *@values --> Iterable ) - -C<grep> takes a list, array, or sequence of values and returns a lazily -evaluated sequence comprised of all of the values from the original list for -which the C<$test> smart-matches as true, maintaining their relative order. - -Here is an example of its use: - - @friends = @coworkers.grep: { .is_friend }; - @friends = grep { .is_friend }, @coworkers; # same - -This takes the array C<@coworkers>, checks every element to see -which ones return true for the C<.is_friend> method, and stores -the resulting sequence's values into C<@friends>. - -Note that, unlike in Perl 5, a comma is required after the C<Matcher> -in the multi form. - -Note that C<grep> is an implicit loop, so C<next> and C<last> without -an argument will iterate or terminate the C<grep> itself, not some -loop surrounding the statement containing the C<grep>. Use a label -if you mean the other thing. - -=item first - - multi method first ( @values: Matcher $test ) - multi first ( Matcher $test, *@values ) - -C<first> searches exactly like C<grep> but stops testing at the first match -and returns just that value. Returns C<Nil> if no match is found. - -=item pick - - multi method pick ( -> Mu ) - multi method pick ( @values: Int $num --> Iterable ) - multi method pick ( @values: Whatever --> Iterable ) - multi pick ( Int $num, *@values --> Iterable ) - multi pick ( Whatever, *@values --> Iterable ) - -C<pick> takes a list, array, or sequence of values and returns a sequence -of random elements from the list (selected without replacement; -see C<roll> for dice roll aka replacement semantics). If C<*> -is specified as the number (or if the number of elements in -the list is less than the specified number), all the available -elements are returned in random order: - - @team = @volunteers.pick(5); - @shuffled = @deck.pick(*); - -A C<.pick> call without arguments returns a single element instead -of an iterable container of one element. - -=item roll - - multi method roll ( --> Mu ) - multi method roll ( @values: Int $num --> Iterable ) - multi method roll ( @values: Whatever --> Iterable ) - multi roll ( Int $num, *@values --> Iterable ) - multi roll ( Whatever, *@values --> Iterable ) - -C<roll> takes a list, array, or sequence of values and returns a -random sequence of elements from the list, like rolling N independent -dice, where each list element corresponds to one side of your dice. -This is also known as "pick with replacement", that is, like pulling -one marble out of a bag and putting it back, and doing this N times; -see C<pick> for the non-replacement semantics. If C<*> is specified -as the number, C<*> provides an infinite list of random choices from -C<@values>: - - @byte = (0,1).roll(8); # 8d2 - for (1..20).roll(*) -> $die_roll { ... } # 1d20 xx * - -A C<.roll> call without arguments returns an element of -the invocant list instead of a one-element sequence. - -Note that C<roll 1, 6> is not the same as a 1d6, but always returns -C<6> as a degenerate one-sided die. Use C<roll 1, 1..6> to simulate -a six-sided die. - -=item join - - multi method join ( @values: Str $separator = '' --> Str ) - multi join ( Str $separator = '', *@values --> Str ) - -C<join> returns a single string comprised of all of the elements -of C<@values>, separated by C<$separator>. - -Given an empty list, C<join> returns the empty string. - -The separator defaults to the null string. To join with space, -just coerce to C<Str>. - -=item map - - multi method map ( @values: Code *&expression --> Iterable ) - multi map ( Code $expression, *@values --> Iterable ) - -C<map> returns a lazily evaluated sequence of values which is -comprised of the return value of the expression, evaluated once -for every one of the C<@values> that are passed in. - -The actual return value is a multislice containing one slice per -map iteration, unless the expression returns a C<Slip>, in which -case the resulting sequence may not be the same length as the -number of values that were passed. - -Note that C<map> is an implicit loop, so C<next> and C<last> without -an argument will iterate or terminate the C<map> itself, not some -loop surrounding the statement containing the C<map>. Use a label -if you mean the other thing. - -=item duckmap - - multi method duckmap ( @values: Code *&expression --> Iterable ) - multi duckmap ( Code $expression, *@values --> Iterable ) - -Like C<map>, C<duckmap> evaluates the expression for each of the -values that is passed in. Unlike C<map>, if the evaluation produces -an undefined value, a failover looks to see if this element actually -contains subelements, and if so, reapplies the duckmap recursively, -returning the structured result for that element, so that the -structure of the original is (largely) retained in the result. -Unlike C<deepmap>, it does not guarantee the same structure, since -the mapping expression takes precedence over structure in cases where -either would succeed. - -Because C<duckmap> is defined as a recursive implicit loop, loop -controls apply only to the current level of the tree. - -=item deepmap - - multi method deepmap ( @values: Code *&expression --> Any ) - multi deepmap ( Code $expression, *@values --> Any ) - -Like C<map> and C<duckmap>, C<deepmap> evaluates the expression for -each of the values you give it. Unlike C<map> and C<duckmap>, an -element is considered a value only if it does not do the C<Iterable> -role. If the element is iterable, the algorithm recurses to produce -an identical structure to its input. Elements that are not iterable -are considered leaf values and mapped through the supplied expression. - -Because C<deepmap> is defined as a recursive implicit loop, loop -controls apply only to the current level of the tree. - -=item reduce - - multi method reduce ( @values: Code *&expression ) - multi reduce ( Code $expression ;; *@values ) - -C<reduce> takes a sequence of values, accumulates enough values from -that sequences to apply C<&expression> to, then feeds that result back -into C<&expression> followed by enough additional values taken from -subsequent values in the sequence. It repeats this process until no -more values are available. The result from the last evaluation of -C<&expression> is then returned. - -If C<&expression> is an operator known to have right associativity, values are -pulled in reverse order from the sequence. - -If an empty sequence is provided and C<&expression> has a known identity -value, it is returned. If the identity value is known and the sequence -is not empty, but contains one less than enough values, those values are -returned (as if C<&expression> had been called with the identity value -and those values, but usually without actually evaluating C<&expression>.) - -If an identity value is not known, and there are not enough values -to evaluate C<&expression> once, an empty sequence is usually returned. - -If a sequence does not produce enough values to perform the last evaluation -of C<&expression> the stray values are usually ignored. - -Note that C<reduce> is an implicit loop, so C<next> and C<last> without -an argument will iterate or terminate the C<reduce> itself, not some -loop surrounding the statement containing the C<reduce>. Use a label -if you mean the other thing. - -=item reverse - - multi method reverse ( @values: --> Iterable ) is export - multi reverse ( *@values --> Iterable ) - -Given a sequence of values, C<reverse> presents a sequence with the -same values in the opposite order. If the sequence is not already -reified, this usually involves reifying and retaining the values. - -Note that "reversing" strings is done with C<flip>. - -=item rotate - - multi method rotate ( @values is copy: Int $n = 1 --> Iterable ) is export - -Produces a new sequence with the same elements as the input sequence, -rotated by the specified amount. See Array::rotate for more -info. - -=item sort - - multi method sort( @values: *&by --> Iterable ) - multi method sort( @values: Ordering @by --> Iterable ) - multi method sort( @values: Ordering $by = &infix:<cmp> --> Iterable ) - multi sort( Ordering @by, *@values --> Iterable ) - multi sort( Ordering $by, *@values --> Iterable ) - -Returns C<@values> sorted, using criteria C<$by> or C<@by> for -comparisons. C<@by> differs from C<$by> in that each criterion is -applied, in order, until a non-zero (tie) result is achieved. - -If C<$by> is a code object of arity zero or one, it is applied on each item -of C<@values>, and C<@values> is sorted by comparing the result values with -C<< &infix:<cmp> >> (Schwartzian Transform). - -C<Ordering> is as described in L<S29/Type Declarations>. Any -C<Ordering> may receive either or both of the mixins C<descending> -and C<canon(Code $how)> to reverse the order of sort, or -to adjust the case, sign, or other order sensitivity of C<cmp>. -(Mixins are applied to values using C<but>.) If a C<Signature> -is used as an C<Ordering> then sort-specific traits such as C<is -canon($how)> are allowed on the positional elements. - -If all criteria are exhausted when comparing two elements, sort should -return them in the same relative order they had in C<@values> (it is -an "order preserving" sort.) - -To sort an array in place use the C<.=sort> mutator form. - -See L<http://www.nntp.perl.org/group/perl.perl6.language/16578> -for more details and examples (with C<is insensitive> meaning -C<is canonicalized(&lc)>.) - -=item unique - - multi method unique(:@as --> Iterable) - multi sub unique(*@values, :&as --> Iterable) - -Returns a list of unique values from the invocant/argument list, such -that only the first occurrence of each duplicated value remains in the -result list. C<unique> uses C<< &infix:<===> >> semantics to compare whether -two objects are the same. The order of the original list is preserved even as -duplicates are removed. - - say <a a b b b c c>.unique # a b c - say <a b b c c b a>.unique # a b c - -(Use C<squish> instead if you know the input is sorted such that identical -objects are adjacent.) - -The optional C<:as> parameter allows you to normalize/canonicalize the elements -before unique-ing. The values are transformed for the purposes of comparison, -but the original values are still emitted in the resulting sequence: - - say <a A B b c b C>.unique(:as(&lc)) # a B c - -This makes it possible to effectively compare with other comparison operators, -too. For example, if you want to compare with C< infix:<==> > semantics, this -might work for you: - - say +unique 100, 100e0, 200/2, :as(*.Num) # 1 - -=item squish - - multi method squish(:&as --> Iterable) - multi sub squish(*@values, :@as --> Iterable) - -Returns a list of values from the invocant/argument list where runs -of more than one value are replaced with only the first instance. -Like C<unique>, C<squish> uses C<< &infix:<===> >> semantics to compare -whether two objects are the same. Unlike C<unique>, this function only -removes adjacent duplicates; identical values further apart are still -kept. The order of the original list is preserved even as duplicates -are removed. - - say <a a b b b c c>.squish # a b c - say <a b b c c b a>.squish # a b c b a - -The optional C< :as > parameter, just like with C< unique >, allows values -to be temporarily transformed before comparison. - -=item min - - multi method min( @values: *&by --> Any ) - multi method min( @values: Ordering @by --> Any ) - multi method min( @values: Ordering $by = &infix:<cmp> --> Any ) - multi min( *@values, Ordering :@by --> Any ) - multi min( *@values, Ordering :$by --> Any ) - -Returns the earliest (i.e., lowest index) minimum element -of C<@values> , using criteria C<$by> or C<@by> for -comparisons. C<@by> differs from C<$by> in that each criterion -is applied, in order, until a non-zero (tie) result is achieved. - -C<Ordering> is as described in L<S29/Type Declarations>. Any -C<Ordering> may receive the mixin C<canonicalized(Code $how)> to -adjust the case, sign, or other order sensitivity of C<cmp>. -(Mixins are applied to values using C<but>.) If a C<Signature> -is used as an C<Ordering> then sort-specific traits such as C<is -canonicalized($how)> are allowed on the positional elements. - -For a C<min> function that does not require an ordering, see the -C<[min]> reduction operator. - -=item max - - multi method max( @values: *&by --> Any ) - multi method max( @values: Ordering @by --> Any ) - multi method max( @values: Ordering $by = &infix:<cmp> --> Any ) - multi max(*@values, Ordering :@by, --> Any ) - multi max(*@values, Ordering :$by, --> Any ) - -Returns the earliest (i.e., lowest index) maximum element -of C<@values> , using criteria C<$by> or C<@by> for -comparisons. C<@by> differs from C<$by> in that each criterion -is applied, in order, until a non-zero (tie) result is achieved. - -C<Ordering> is as described in L<S29/Type Declarations>. Any -C<Ordering> may receive the mixin C<canonicalized(Code $how)> to -adjust the case, sign, or other order sensitivity of C<cmp>. -(Mixins are applied to values using C<but>.) If a C<Signature> -is used as an C<Ordering> then sort-specific traits such as C<is -canonicalized($how)> are allowed on the positional elements. - -For a C<max> function that does not require an ordering, see the -C<[max]> reduction operator. - -=item minmax - - multi method minmax( @values: *&by --> Any ) - multi method minmax( @values: Ordering @by --> Any ) - multi method minmax( @values: Ordering $by = &infix:<cmp> --> Any ) - multi minmax( *@values, Ordering :@by --> Any ) - multi minmax( *@values, Ordering :$by --> Any ) - -Returns a C<Range> from the minimum element of C<@values> to the maximum -element, using criteria C<$by> or C<@by> for comparisons. C<@by> differs from -C<$by> in that each criterion is applied, in order, until a non-zero (tie) -result is achieved. C<Range> elements in C<@values> are treated as if their -minimum and maximum values were passed individually, except that if the -corresponding C<excludes> flag is set in Range, the excludes flag is also set -in the returned C<Range>. - -C<Ordering> is as described in L<S29/Type Declarations>. Any -C<Ordering> may receive the mixin C<canonicalized(Code $how)> to -adjust the case, sign, or other order sensitivity of C<cmp>. -(Mixins are applied to values using C<but>.) If a C<Signature> -is used as an C<Ordering> then sort-specific traits such as C<is -canonicalized($how)> are allowed on the positional elements. - -For a C<minmax> function that does not require an ordering, see the -C<[minmax]> reduction operator. - -=item any - - multi method any( @values: --> Junction ) - multi any( *@values --> Junction ) is export - -Returns a junction with all the values of the list C<|>-ed together. The -junction will only match against another value if at least one of the -values in the list matches. - -=item all - - multi method all( @values: --> Junction ) - multi all( *@values --> Junction ) is export - -Returns a junction with all the values of the list C<&>-ed together. The -junction will only match against another value if all of the values in the -list match. - -=item one - - multi method one( @values: --> Junction ) - multi one( *@values --> Junction ) is export - -Returns a junction with all the values of the list C<^>-ed together. The -junction will only match against another value if exactly one of the values -in the list matches. - -=item none - - multi method none( @values: --> Junction ) - multi none( *@values --> Junction ) is export - -Returns a junction which will only match against another value if none of -the values in the list matches. - -=item comb - - multi method comb ( Regex $matcher, Int $limit = * ) - multi method comb ( Str $matcher, Int $limit = * ) - -Treats a sequence values as a string (by simply C<join>ing them together), -and calls C<.comb> on that string with the same parameters. See C<Str::comb>. - -=item combinations - - multi method combinations ( Int $of ) - multi method combinations ( Range $of = 0 .. * ) - multi combinations ( $n, $k ) - -Returns all combinations of the list taken N at a time (specified -by the C<$of> parameter). If the range option is taken, then the -range is iterated, and for each integer N in the range, appends all -combinations taken N at a time to the resulting list. If the max of -the range is greater than the size of the list, iteration stops at -the size of the list. Hence, if the default of C<0..*> is taken, the -first return value will be an empty array, and the final return value -will be an array containing every value in the list. - -The return value is a sequence or container of (presumably immutable) values. -(Note: When used on actual sets and other iterable structures, -specialized versions of this method are allowed to bypass turning it into -a list first. Also, the return values are allowed to be specialized to -any non-flattening container, so that subsets of sets can actually be -a set of sets. If the ordering of the input doesn't matter, neither -does the ordering of the subsets.) - -Note that, without an argument, the first returned combination will -always be the empty list, and the last combination will always -be the entire list. - -It is erroneous to ask for the combinations of any infinite list. -The compiler is allowed to complain if it notices, however. - -The functional form assumes it is working on a list of integers C<^$n> -taken C<$k> at a time. - -=item permutations - - multi method permutations ( ) - multi permutations ( $n ) - -Similar to C<combinations>, but returns permutations instead. (Types such as -C<Range> are converted to a list of individual values before permuting them.) - -The functional form assumes it is working on a list of integers C<^$n>. - -=item rotor - - multi method rotor ( *@cycle, :$partial ) - -Takes multiple cyclical slices of a sequence as specified by -C<@cycle>, which you can think of as a rotory cutter that punches out -multiple slices depending on the arrangement of the blades (or teeth, if -you prefer a gear analogy). Since it's cyclical, you may apply a rotor -to an infinite list lazily. Each specifier in the cycle specifies how -many elements to take (the "slice") and, optionally, how many to omit -(the "gap"). The cycle repeats if C<@cycle> runs out before the sequence -does. The rotor stops if the sequence runs out first, that is, if there are -insufficient values remaining to create the entire next slice (ignoring -any associated gap). If :partial is specified, the final partial slice -is returned at the end, if it is not empty. Here we slice the alphabet -into alternating slices of size 2 and 3: - - my @list = 'a'...'z'; - @list.rotor(2,3) # ab, cde, fg, hij...uv, wxy - @list.rotor(2,3, :partial) # ab, cde, fg, hij...uv, wxy, z - -It is allowed to specify an infinite cycle, in which case it will never -repeat, at least not internally. The supplied list may of course repeat -itself instead. Hence these two calls produce the same result: - - @list.rotor(2,3) - @list.rotor((2,3) xx *) - -Each slice specifier may be either an integer or a pair. If it is a pair, -the key is taken as the number of elements to take in the slice, and the value -is taken as the size of the gap. If the specifier is an integer, it is taken -as the size of the slice, and the gap is taken as 0. In other words, these -are equivalent: - - @list.rotor(3) - @list.rotor(3 => 0) - -A non-zero gap or overlap may be specified only via the pair form: - - @list.rotor(2 => 1) # take two, skip one - @list.rotor(2 => -1) # take two, back up one - -=item pairup - - multi method pairup ( ) - -Turns a sequence of mixed keys, values, and pairs into a sequence of pairs in -the same way that a hash composer does, only without creating the hash. -While there is more to process, the next value is examined. If it -is a Pair, it is passed through unchanged. Otherwise a second value is -also taken from the list and those two values together are turned into -a pair. It is an X::Pairup::OddNumber error if there is no next value. -(It is not an error if the second value happens be a pair; if so, it -merely becomes the value paired with the key of the first value.) - -Obviously you cannot create pairs where the keys are Pairs using this -function. Use a map or some such for that. - -=item invert - - multi method invert ( --> Iterable ) is export { - self.map: -> $p { $.value »=>» $.key } - } - -Produces a backmapping of values to keys, expanding list values -into multiple pairs. (The C<< »=>» >> expands the value if it is a list.) - -The invocant must be a list containing only Pairs, and throws an error if -anything that is not a Pair is passed. To invert key/value lists, use -C<.pairup> first: - - @kv.pairup.invert - -Likewise if you wish to invert the implicit indices of an array or list, you -must call C<.pairs> first: - - <a b c>.pairs.invert # ('a' => 0, 'b' => 1, 'c' => 2) - -(You may call C<.invert> directly on a hash, because a hash naturally listifies -to a list of pairs.) - -=back - -=head2 Array - -All these methods are defined in the C<Array> role/class. - - role Array does List {...} - -=over - -=item new - - multi method new(*@args --> Array ) - -Constructs a new C<Array> containing the arguments passed to C<new>. - -=item shape - - method shape (@array: --> List ) is export - -Returns the declared shape of the array, as described in S09. - -=item end - - method end (@array: --> Any ) is export - -Returns the final subscript of the first dimension; for a one-dimensional -array this simply the index of the final element. For fixed dimensions -this is the declared maximum subscript. For non-fixed dimensions (undeclared -or explicitly declared with C<*>), the index of the actual last element is used. -So that the degenerate case of an empty range works correctly, C<-1> is returned -if the array is empty. (If you actually try to index with C<-1>, you'll get a -failure.) - -=item elems - - method elems (@array: --> Int ) is export - -Returns the length of the array counted in elements. - -=item delete (DEPRECATED) - -The "delete" method is considered to be a deprecated internal method: the -normal way to mark an element as deleted, is to apply the C<:delete> adverb -to a subscripting operation. - -=item :delete - -This adverb may be applied to any subscripting operation. The operation -returns the elements normally, but reads them out destructively. - -=item exists (DEPRECATED) - -The "exists" method is considered to be a deprecated internal method: the -normal way to test for existence is to apply the C<:exists> adverb to a -subscripting operation. - -=item :exists - -This adverb may be applied to any subscripting operation. The -operation returns true if specified element exists. If a slice -is specified by the subscript, a C<List> of C<Bool> is returned, -which can be processed using junctions. - -=item pop - - multi method pop ( @array: --> Scalar ) is export - -Remove the last element of C<@array> and return it. -If C<@array> is empty returns a failure. - -=item push - - multi method push ( @array: *@values --> Array ) is export - -Adds all the values to the end of C<@array> eagerly. Returns the modified -array. - -=item plan - - multi method plan ( @array: *@list --> Array ) is export - -Adds the list to the end of C<@array> lazily as a kind of "lazy push". -(That is, the reified part of the array is not modified, but the list -is appended to the not-yet-reified specifications for how to -extend the array on demand, if it is subscripted or shifted beyond the -currently reified elements.) Returns the modified array. - -Note that the semantics of these are different: - - @ro := (0,1,*+*...*); - @rw.plan(0,1,*+*...*); - -In the first case, C<@ro> is bound directly to the list, so its -values are memoized but not considered mutable. In contrast, C<@rw> -allows modification of any reified element; new elements are merely -initialized to the fibonacci sequence. If you try to modify a -non-reified element, the array will be reified to that point before -the modification is attempted. - -For all external purposes, the array considers that its plan is -part of the array. If you ask for C<.elems>, for instance, it will -try to reify the entire array, which might take a long time in the -case of infinite arrays (though a list may return C<Inf> if it can -determine this). Methods such as C<.splice> can refer to the rest of -the list in the abstract, and need only reify those elements necessary -to perform the operation in question. (Hence, there is no need for -an C<.unplan> method, since the plan of an array may be thrown away -by using C<splice> without the risk of memory exhaustion.) - -=item rotate - - multi method rotate ( @array is copy: Int $n = 1, Int *@n --> Array ) is export - -Produces a new array with the same elements as the old array, -rotated by the specified amount. A positive rotation of 1 is defined as: - - @array.push(@array.shift); - -A negative rotation of 1 is defined as: - - @array.unshift(@array.pop); - -If the magnitude of C<$n> is larger than the number of elements, -the rotational semantics must be equivalent to doing: - - @array.rotate(sign($n)) for ^abs($n) - -The new array to be returned contains nothing but aliases for -the old array's elements; however, you can use this to get -any of three different semantic behaviors: - - @a.=rotate # @a is rotated in place - @b = @a.rotate # @b contains copied elements of rotated @a - @b := @a.rotate # @b contains aliased elements of rotated @a - -If additional rotations are specified via the slurpy, they are -applied to subdimensions of multidimensional arrays. (To perform -a flat rotation on a shaped array requires flattening to a list -and rotating that instead.) - -=item shift - - multi method shift ( @array: --> Scalar ) is export - -Remove the first element from C<@array> and return it. -If C<@array> is empty returns a failure. - -=item splice - - multi method splice( @array is rw: $offset = 0, $size = Inf, *@values --> Any ) is export - -C<splice> fills many niches in array-management, but its fundamental behavior -is to remove zero or more elements from an array and replace them with a -new (and potentially empty) list. This operation can shorten or lengthen -the target array. - -C<$offset> is the index of the array element to start with. A WhateverCode -whose argument is the number of elements in the C<@array> may also be used. - -C<$size> is the number of elements to remove from C<@array>. A WhateverCode -similar to C<$offset> may be used instead (note that this specifies a position, -not an actual number of elements to remove). - -The slurpy list of values (if any) is then inserted at C<$offset>. - -Calling splice with a traditional parameter list, you must define C<$offset> -and C<$size> if you wish to pass a replacement list of values. To avoid -having to pass these otherwise optional parameters, use the piping operator(s): - - splice(@array,10) <== 1..*; - -which replaces C<@array[10]> and all subsequent elements with an infinite -sequence starting at C<1>. - -If C<@array> is multidimensional, C<splice> operates only on the first -dimension, and works with Array References. - -C<splice> returns a C<List> of the deleted elements, which behaves as -expected in either list or item context. - -C<$offset> and C<$size> will be treated as C<Int>. The function fails if -either parameter is negative, or undefined. - -Either of C<$offset> or C<$size> may be specified relative to the length of the -array using a WhateverCode whose argument will be the number of elements in -the array. - -While it is illegal for the offset to be larger than the size of -the array, it is allowed for the final position to be off the end of the array; -in this case the entire rest of the array is spliced, whatever is available. - -=item unshift - - multi method unshift ( @array: *@values --> Array ) is export - -C<unshift> adds the values onto the start of the C<@array> and -returns the modified array. - -=item keys - -=item kv - -=item pairs - -=item antipairs - -=item enums - -=item values - - multi method keys ( @array: ) is export - multi method kv ( @array: ) is export - multi method pairs ( @array: ) is export - multi method antipairs ( @array: ) is export - multi method enums ( @array: ) is export - multi method values ( @array: ) is export - -Iterates the elements of C<@array>, in order. - -What is returned at each element of the iteration varies with function. -C<values> returns the value of the associated element; C<kv> returns -a 2 element list in (index, value) order, C<pairs> a C<Pair(index, value)>. -With C<pairs> the values are references back to the original containers, -while with C<enums> a snapshot of those values is taken. That is, C<.pairs> -returns a C<PairMap> while C<enums> returns an C<EnumMap>. - -If C<@array> is declared to be multi-dimensional, the keys returned may -in fact be slice lists. (Arrays that are effectively multi-dimensional -by containing other arrays or hashes are treat with their declared -dimensionality, not their effective dimensionality.) - -Note that C<kv @array> returns the same as C<zip(^@array; @array)> - -=back - -=head2 Hash - -The following are defined in the C<Hash> class. - - class Hash is EnumMap {...} - -=over 4 - -=item delete (DEPRECATED) - -The "delete" method is considered to be a deprecated internal method: the -normal way to remove a key from a hash, is to apply the C<:delete> adverb -to a subscripting operation. - -=item :delete - -This adverb may be applied to any subscripting operation. The operation -returns the elements normally, but reads them out destructively. - -=item exists (DEPRECATED) - -The "exists" method is considered to be a deprecated internal method: the -normal way to test for existence is to apply the C<:exists> adverb to a -subscripting operation. - -=item :exists - -This adverb may be applied to any subscripting operation. The -operation returns true if specified element exists. If a slice -is specified by the subscript, a C<List> of C<Bool> is returned, -which can be processed using junctions. - -=item keys - -=item kv - -=item pairs - -=item antipairs - -=item enums - -=item values - - multi method keys ( %hash: ) is export - multi method kv ( %hash: ) is export - multi method pairs ( %hash: ) is export - multi method antipairs ( %hash: ) is export - multi method enums ( %hash: ) is export - multi method values ( %hash: ) is export - -Iterates the elements of C<%hash>. The order is implementation dependent -and arbitrary, but will be the same between successive calls to these -functions, as long as C<%hash> doesn't change. - -What is returned at each element of the iteration varies with function. -C<keys> only returns the key; C<values> the value; C<kv> returns both as -a 2 element list in (key, value) order, C<pairs> a C<Pair(key, value)>. -With C<pairs> the values are references back to the original containers, -while with C<enums> a snapshot of those values is taken. That is, C<.pairs> -returns a C<PairMap> while C<enums> returns an C<EnumMap>. - -Note that C<kv %hash> returns the same as C<zip(keys %hash; values %hash)> - -The lvalue form of C<keys> is no longer supported. Use the C<.buckets> -property instead. - -=item any - - multi method any( %hash: --> Junction ) is export - -Returns a junction with all the keys of the hash C<|>-ed together. The -junction will only match against another value if at least one of the -keys in the hash matches. - -=item all - - multi method all( %hash: --> Junction ) is export - -Returns a junction with all the keys of the hash C<&>-ed together. The -junction will only match against another value if all of the keys in the hash -match. - -=item one - - multi method one( %hash: --> Junction ) is export - -Returns a junction with all the keys of the hash C<^>-ed together. The -junction will only match against another value if exactly one of the keys -in the hash matches. - -=item none - - multi method none( %hash: --> Junction ) is export - -Returns a junction which will only match against another value if none of -the keys in the hash matches. - -=item antipairs - - multi method antipairs ( %hash: --> List ) is export { - %hash.map: { .value => .key } - } - -Produces a simple backmapping of values to keys, like C<.pairs> but with each -returned pair returned as an antipair, that is, a pair with key and value exchanged. -Unlike the C<invert> method, there is no attempt to expand list values into multiple pairs. - -=item invert - - multi method invert ( %hash: --> List ) is export { - %hash.map: { .value »=>» .key } - } - -Produces a backmapping of values to keys, but unlike C<.antipairs>, expands list values -into multiple pairs. (The C<< »=>» >> expands C<.value> if it is a list.) - -This function is essentially a shortcut for C<.pairs.invert>, but bypasses -the creation of pairs only to invert them. - -=item push - - multi method push ( %hash: *@values --> Hash ) is export - -Like hash assignment insofar as it accepts either C<Pair> objects or -alternating keys and values; also like in that it returns the new hash. -However, unlike assignment, when a duplicate key is detected, -C<push> coerces the colliding entry's value to an -array and pushes the C<Pair>'s value onto that array. Hence to invert -a hash containing duplicate values without losing (associative) information, -say: - - %out.push(%in.invert) - -Note that when reading the values of such a hash, you must not assume -that all the elements are arrays, since the first instance of a key -merely sets the value without turning it into an array. (Fortunately, -most list operators create a list of one element when used on an object -that is not a list.) - -The intent is that inverting a hash twice produces a hash equivalent -to the original hash. - -=back - -=head1 Classes and Roles - -This documents Buf, List, Range, Set, Bag, Junction, Array, Hash, MixHash, SetHash, -BagHash, Pair, and PairMap. - -=head2 Range - - class Range does Positional does Iterable { - method min() {...} - method max() {...} - method bounds() returns List {...} - method excludes-min {...} - method excludes-max {...} - method sample {...} - } - -=head3 Methods - -=over - -=item sample - - multi method sample ( $range: Int $num = 1 --> List ) - multi method sample ( $range: Whatever --> List ) - -Returns a lazy list of C<Num> values, taken as linearly distributed samples from -the real interval specified by the invocant. The argument, if any, indicates -how many samples to return. Hence, C<(^1).sample> is equivalent to C<rand>, and -C<(^10).sample(*)> is equivalent to C<rand * 10 xx *>. Ranges with exclusions -other than C<..^> may be less efficient by virtue of having to generate from a larger -interval, throwing out values that are outside the specified interval. - -=back - -=head2 Buf - - class Buf does Positional does Stringy {...} - -A mutable container for an array of integer values in contiguous -memory. The default constructor takes a single array parameter of -integers, the largest of which determines the actual type. So - - Buf.new([:16<c3>, :16<B6>]) # or - Buf.new([195, 182]) # which is exactly the same - -returns a C<buf8> containing two C<uint8> items, while - - Buf.new([256]) - -returns a C<buf16> which consists of a single C<uint16>. - -To explicit request a C<Buf> of a specific size, you can use - - Buf.new([127], :size(16)) # returns a buf16 - Buf.new([1024], :size(8)) # dies, because 1024 >= 2**8 - -Subtypes with additional constraints like C<utf8> (which only allows valid -UTF-8 byte sequences) exist and provide similar constructors. See -L<S02/Built-In Data Types>. - -The array in the constructor used to be slurpy rather than positional, but -the former was deemed to be too inefficient (during signature construction) -for arrays of many elements. - -=head3 Methods - -=over - -=item decode - - method decode($encoding = $?ENC, $nf = $?NF --> Str ) - -Decode the C<Buf> into a C<Str>. For subtypes that know their encoding (like -C<utf8>, C<utf16>) the C<$encoding> parameter defaults to their intrinsic -encoding instead. - -=item subbuf - - method subbuf($from, $elems?) returns Buf:D - -Returns a part of the original buffer, starting from index C<$from> and taking -C<$elems> elements (or to the end of the buffer, if not provided). - -The method fails with C<X::OutOfRange> if either C<$from> or C<$elems> are negative. The method also fails if C<$from> is larger than the amount of elements in the buffer. - -C<$from> may be specified relative to the end of the string using a WhateverCode: - - Buf.new(0x00, 0xFF).subbuf(*-1, 1) - -=item subbuf-rw - - method subbuf-rw( $from; $elems?) is rw - - A version of C<.subbuf> that returns a writable reference to a part of a - buffer: - - $b.subbuf-rw($from,$to) = Buf.new(0x00, 0x77); - -=back - - -=head3 C<Buf> Operators - -Two C<Buf> objects of the same bit size can be compared with the same -operators as strings (in particular C<eq>, C<lt>, C<le>, C<gt>, C<ge>, -C<ne> and C<leg>), but actually compares the stored integers, not -characters. Concatenating two compatible C<Buf>s produces an object of the -most specific type possible, for example C<buf8.new() ~ utf8.new()> results in -a C<buf8> object. - -Comparing or concatenating two C<Buf> objects of different bit sizes, -or a C<Buf> that doesn't know its encoding with a C<Str> throws an exception. - -Likewise, coercing an encoding-unaware C<Buf> to C<Str> dies. - -[Conjecture: The behaviour of encoding-aware C<Buf> objects on string -operators is intentionally not defined yet, because I have no idea what -implications on speed and usage they might have --moritz]. - -=head2 Enum and Pair - - class Enum does Associative {...} - class Pair does Associative {...} - - -A value formed by associating a single key with a single value. -In an C<Enum>, both key and value are immutable. In a C<Pair>, the -key is immutable but the value mutable. C<Enum> works identically -to C<Pair> unless you try to modify it.) - -=over - -=item antipair - - multi method antipair ( $pair: --> Pair ) is export { - $pair.value => $pair.key - } - -Returns new pair with key and value swapped. Note singular spelling, -since this operates only on one pair. - -=item invert - - multi method invert ( $pair: --> List ) is export { - $pair.value »=>» $pair.key - } - -Note that this is not a simple exchange, but splits pairs with C<Positional> values -into multiple pairs in support of database inversion operations (when -used along with C<Hash.push>). - -Equivalent to C<antipair> if no values are C<Positional>. - -=back - -=head2 EnumMap - - class EnumMap does Associative does Positional {...} - -An immutable hash value, viewable either as a (constant) hash or as -a sequence of C<Enum>s. The keys may not contain duplicates, while -the values may. The implementation of C<EnumMap> associativity is not -guaranteed to be as efficient as a C<Hash> lookup. (A brute force -linear scan for the matching key is allowed. Optimization -is also allowed.) - -=head2 PairMap - - class PairMap does Associative does Positional {...} - -A hash value that is mutable only in values, differing from a normal -hash insofar as the key set is frozen. It may be accessed either as -a frozen hash or as a sequence of C<Pair>s. The keys may not contain -duplicates, while the values may. The implementation of C<PairMap> -associativity is not guaranteed to be as efficient as a C<Hash> lookup. -(A brute force linear scan for the matching key is allowed. Optimization -to something like an ordered hash is also allowed.) - -=head2 Set - - class Set does Associative {...} - -A set of unique values or objects. (Sets are notionally "object -hashes", that is, hashes that allow more than just strings as keys; as -such, they are subject to C<===> equality rather than C<eqv> equality.) -A C<Set> responds to hash operators as if it were a C<Hash of True>. -that is, when used as a hash, a set always treats the set's elements -as the keys of the hash, returning C<True> for existing set elements, -and C<False> for any key not found in the set. - -See C<SetHash> for a container that can represent different sets as -keys are added or deleted. - -Regardless of their behavior as hashes, set (and bag) types do not -flatten in list context; in the absence of explicit interpolation -instructions (such as use of the C<@> sigil or C<.keys> method) -they are returned as items in list context. On the other end, the -constructors for set and bag types do not automatically interpolate -the contents of sets or bags (or any other other item type). They -simply take the list of objects slurped in and turn them into a set. -Together these rules allow us to constructs sets and bags containing -sets and bags as elements. - -Use the C<set> composer to construct a set of the elements of the -list. The empty set may be indicated with either C<set()> or C<∅> -(U+2205 EMPTY SET). - -The C<set> composer will very literally make a set of whatever you -pass it; in particular, it will make a set of Pairs if you try to -pass it a list of Pairs (recall that a hash returns a list of Pairs -in list context). To create a set from the keys of a list of Pairs, -use a C<Set()> coercion rather than a constructor. Or to create a -set from a hash, use the C<.keys> or C<:k> to extract only the keys. - -=over - -=item pick - - multi method pick ( $set: Int $num = 1 --> Any ) - multi method pick ( $set: Whatever --> Any ) - -Works like an ordinary list C<pick>. - -=item roll - - multi method roll ( $set: Int $num = 1 --> Any ) - multi method roll ( $set: Whatever --> Any ) - -Works like an ordinary list C<roll>. - -=item combinations - - multi method combinations ( Int $of ) - multi method combinations ( Range $of = 0 .. * ) - -Works as if the set were turned into a list of elements and then -the combinations were turned back into a list of sets, ordered by -increasing size. You may, of course, turn that list back into a set of sets. - -Note that, without an argument, this method basically calculates the powerset. - -=back - -=head2 SetHash - -A mutable Set container, represented as C<QuantHash[Bool,False]>. - -=head2 Bag - - class Bag does Associative {...} - -A collection of values or objects that work just like sets, except -that they need not be unique. The count of each value or object is -represented by an associative mapping from each key value/object to its -replication number. The C<.total> method returns the sum of all -replication values. The C<.minpairs> and C<.maxpairs> methods return the -pairs with the minimum and maximum replication number. - -Sets and bags do not flatten into list context, nor do the constructors -interpolate items passed to them, even if they look like sets or bags. -(To create a bag from a list of Pairs or a hash, use a C<Bag()> coercion -rather than a constructor.) - -=over - -=item pick - - multi method pick ( $bag: Int $num = 1 --> Any ) - multi method pick ( $bag: Whatever --> Any ) - multi method pickpairs ( $bag: Int $num = 1 --> Pairs ) - multi method pickpairs ( $bag: Whatever --> Pairs ) - -Like an ordinary list C<pick>, but returns keys of the bag weighted by -values, as if the keys were replicated the number of times indicated -by the corresponding value and then list pick used. C<BagHash> is the -mutable form of C<Bag>. A C<Bag> responds to hash operators as if it were -a C<Hash of UInt>. - -The underlying metaphor for picking is that you're pulling colored -marbles out a bag. (For "picking with replacement" see C<roll> instead.) -Picking require tracking the temporary state, so the immutable C<Bag> is -copied to a temporary private C<BagHash>, and the picks are made from that -using the corresponding C<.grab> or C<.grabpairs> method (see below). - -Each C<.pick>/C<.pickpairs> invocation maintains its own private state and -has no effect on subsequent C<.pick>/C<.pickpairs> invocations. - -The C<.pickpairs> version returns the grabbed values as a list of C<Pair> -objects, whose keys are the keys and whose values are the replication values. - -=item roll - - multi method roll ( $bag: Int $num = 1 --> Any ) - multi method roll ( $bag: Whatever --> Any ) - -Like an ordinary list C<roll>, but returns keys of the bag weighted -by values, as if the keys were replicated the number of times -indicated by the corresponding value and then list C<roll> used. -The underlying metaphor for rolling is that you're throwing C<$num> -dice that are independent of each other, which (in bag terms) is -equivalent to picking a colored marble out your bag and then putting -it back, and doing this C<$num> times. In dice terms, the number -of marbles corresponds to the number of sides, and the number of -marbles of the same color corresponds to number of sides with the -same color. (For "picking without replacement" see C<pick> instead.) -Rolling requires no temporary state. - -=item kxxv - - method kxxv (-->List) - -Returns a list of the keys of the bag, with each key multiplied by its -replication factor (hence the name: .k xx .v). - -=back - -=head2 BagHash - -A mutable C<Bag> container, represented as C<QuantHash[UInt,0]>. - -=head2 QuantHash - - role QuantHash[::T, $default = Any] does Mixy does Associative {...} - -A C<QuantHash> represents a mutable set of objects, represented as the -keys of a C<Hash>. When asked to behave as a list it ignores its -C<.values> and returns only C<.keys> (possibly replicated by weight -in the case of bag types). C<SetHash> and C<BagHash> are derived -from this type, but constrain their hash values to be C<Bool> and -C<UInt>, respectively. A C<QuantHash> automatically deletes any key -whose corresponding value goes to the default value for the hash. -For any C<QuantHash>, the C<.total> methods returns the current sum -of the values, which the C<QuantHash> must either track or compute -on demand. Tracking is preferable for efficient implementation of -C<.pick> and C<.grab>. - -All standard C<QuantHash> containers have a default value that is false -(such as C<0> or C<''> or C<Nil> or C<Bool::False>), and keep around -only those entries with non-default values, automatically deleting -any entry if its value goes to that (false) default value. - -=over - -=item grab - - multi method grab ( $bag: Int $num = 1 --> Any ) - multi method grab ( $bag: Whatever --> Any ) - multi method grabpairs ( $bag: Int $num = 1 --> Any ) - multi method grabpairs ( $bag: Whatever --> Any ) - -Like C<pick>, a C<grab> returns a random selection of elements, weighted -by the values corresponding to each key. Unlike C<pick>, it works only -on mutable structures. Use of C<grab> on an immutable structure results -in an exception (much like C<push> would). -Since a C<QuantHash>, unlike a C<Set> or C<Bag>, is mutable, C<.grab> -works directly on the C<QuantHash>, modifying it in place. (You may use -C<.pick> to treat the C<QuantHash> as immutable; this will copy it and grab -only from the temporary copy.) - -Grabbing decrements the grabbed -key's replication value by one (deleting the key when it goes to 0). -By definition, C<.total> of the bag also decreases by one, so the -probabilities stay consistent through subsequent grab operations. - -With the C<.grabpairs> version, the replication value of the picked -key is forced immediately to 0, removing all marbles of that color from -the bag, as it were. Instead of returning keys, returns the grabbed -values as a list of C<Pair> objects, whose keys are the deleted keys -and whose values are the deleted replication values. - -=back - -=head2 MixHash - -A C<QuantHash[Real,0]>; like a C<BagHash> but may have non-integral -weights for use in weighted picking. Keys with fractional weights -are deleted if they go to 0. Negative weights are not deleted, but -the implementation may complain if it notices you attempting to use -such a weight. - -=head2 Junction - -All method calls on junctions autothread because the type provides no public methods. - -=over 4 - -=item !eigenstates - - method !eigenstates (Junction $j: --> List) - -Returns an unordered list of the values that constitute the junction (formerly -called C<.values>). It flattens nested junctions of the same type, so -C<(1|(2|3)).eigenstates> returns an arbitrary permutation of the list -C<1, 2, 3>. - -Note this is a private method; you must arrange for yourself to be trusted -by the junctions class in order to call it, which probably involves evil -MONKEY-TYPING. - -Alternately, the values may be explicitly converted to a set value -using C<.Set> or C<Set()>. Note, however, that the set of eigenstates -for a C<none> junction defines the values that are *not* there, -so the resulting C<Set> will be the I<complement> to the universe of -values recognized by the junction! Also note that C<any> and C<all> -junctions represent I<sets> of sets of items, not sets of items. -Since set items are by definition unique, only the C<one> junction -can be unthinkingly mapped to and from a given set. (This is why we -discourage casual use of the eigenstates as a set.) - -=back - -=head1 AUTHORS - - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - -=for vim:set expandtab sw=4: diff --git a/S32-setting-library/Exception.pod b/S32-setting-library/Exception.pod deleted file mode 100644 index 1e1a5117..00000000 --- a/S32-setting-library/Exception.pod +++ /dev/null @@ -1,1367 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Exceptions - -=head1 VERSION - - Created: 26 Feb 2009 - - Last Modified: 28 Dec 2013 - Version: 27 - -The document is a draft. - -=head1 Roles and Classes - -All built-in exceptions save for the base class C<Exception> live in the -C<X::> namespace. - -Generally error classes are supposed to provide the objects involved with the -error, and only convert them to a string form when producing the error -message. This does not apply to compile errors that involve types which have -not been fully composed yet; in that case just the name of the incomplete -type is included in the exception object. - -Names of error classes should describe the problem in some way, or at least -mention the operation that went wrong. If an error can only occur in relation -to a certain type, the error types should be under C<X::ThatType::>. - -=head2 Exception - -All built-in exceptions inherit from C<Exception>, which provides some basic -behavior: storing a backtrace and providing an interface for the backtrace -printer. - - class Exception { - has $.backtrace; - method message() { ... } # an actual stub - method gist { "$.message\n$.backtrace" } - method throw() { } - method fail() { } - method resumable() { } - method resume() { } - } - -All direct subclasses are supposed to override method C<message>. - -=head2 X::OS - - role X::OS { has $.os-error } - -for all errors that are triggered by some error reported by the operating -system (failed IO, system calls, fork, memory allocation). - -=head2 X::IO - - role X::IO does X::OS { } - -For IO related errors - - -=head3 X::IO::Rename - -Thrown when a file rename fails. TODO: maybe unify with X::IO::Copy? - - my class X::IO::Rename does X::IO is Exception { - has $.from; - has $.to; - method message() { - "Failed to rename '$.from' to '$.to': $.os-error" - } - } - -=head3 X::IO::Copy - -Thrown when a file copy operation fails - - my class X::IO::Copy does X::IO is Exception { - has $.from; - has $.to; - method message() { - "Failed to copy '$.from' to '$.to': $.os-error" - } - } - -=head3 X::IO::Mkdir - -Thrown when an C<mkdir> operation fails. - - my class X::IO::Mkdir does X::IO is Exception { - has $.path; - has $.mode; - method message() { - "Failed to create directory '$.path' with mode '0o{$.mode.fmt("%03o")}': $.os-error" - } - } - -=head3 X::IO::Chdir - -Thrown when a C<chdir> fails - - my class X::IO::Chdir does X::IO is Exception { - has $.path; - method message() { - "Failed to change the working directory to '$.path': $.os-error" - } - } - -=head3 X::IO::Dir - -Thrown when a C<dir()> fails - - my class X::IO::Dir does X::IO is Exception { - has $.path; - method message() { - "Failed to get the directory contents of '$.path': $.os-error" - } - } - -=head3 X::IO::Cwd - -Thrown when unable to determine the current directory. - - my class X::IO::Cwd does X::IO is Exception { - method message() { - "Failed to get the working directory: $.os-error" - } - } - -=head3 X::IO::Rmdir - -Thrown when C<rmdir> fails. - - my class X::IO::Rmdir does X::IO is Exception { - has $.path; - method message() { - "Failed to remove the directory '$.path': $.os-error" - } - } - -=head3 X::IO::Unlink - -Thrown when C<unlink> fails. - - my class X::IO::Unlink does X::IO is Exception { - has $.path; - method message() { - "Failed to remove the file '$.path': $.os-error" - } - } - -=head3 X::IO::Chmod - -Thrown when C<chmod> fails. - - my class X::IO::Chmod does X::IO is Exception { - has $.path; - has $.mode; - method message() { - "Failed to set the mode of '$.path' to '0o{$.mode.fmt("%03o")}': $.os-error" - } - } - -=head2 X::NYI - - class X::NYI is Exception { - has $.feature; - method message() { "$.feature is not yet implemented. Sorry. " } - } - -For errors that stem from incomplete implementations of the Perl 6 language. -A full Perl 6.0 implementation should not throw such errors. - -=head2 X::AdHoc - - class X::AdHoc is Exception { - has $.payload handles <Str Numeric>; - method message() { $.payload.Str } - } - -If you call C<&die> with non-C<Exception> arguments, what the user finds -in his C<$!> variables is an object of type C<X::AdHoc>. - -So C<&die> could be written as - - multi sub die(Exception $e) is hidden-from-backtrace { - $e.throw - } - multi sub die($payload) is hidden-from-backtrace { - X::AdHoc.new(:$payload).throw; - } - - -=head2 Compile-time errors - -=head3 X::Comp - - role X::Comp { - has $.filename; - has $.line; - has $.column; - } - -For errors that arise from compiling code. Note that in this case the -backtrace shows how the -compilation was triggered (through C<use SomeModule;>, C<EVAL>s etc.). -The actual location of the error does not appear in the backtrace, but -rather in the attributes defined in this role. - -For exceptions that can occur both at run time and at compile time, the base -exception type should not do C<X::Comp>, but it should be mixed in into -the exception object when thrown at compile time. - -=head3 X::Placeholder::Block - -Thrown when a placeholder variable is used in a block that does not allow a -signature (for example C<class A { $^foo }>. - - my class X::Placeholder::Block does X::Comp { - has $.placeholder; - method message() { - "Placeholder variable $.placeholder may not be used here because the surrounding block takes no signature"; - } - } - -=head3 X::Placeholder::Mainline - -Thrown when a placeholder variable is used in the mainline, ie outside of any -explicit block. - - my class X::Placeholder::Mainline is X::Placeholder::Block { - method message() { - "Cannot use placeholder parameter $.placeholder in the mainline" - } - } - -=head3 X::Redeclaration - -Thrown when a symbol is redeclared - - my class X::Redeclaration does X::Comp { - has $.symbol; - has $.postfix = ''; - has $.what = 'symbol'; - method message() { - "Redeclaration of $.what $.symbol$.postfix"; - } - } - -=head3 X::Undeclared - -Occurs when a symbol is being referenced that needs to be declared, but isn't. - - my class X::Undeclared does X::Comp { - has $.what = 'Variable'; - has $.symbol; - method message() { - "$.what $.symbol is not declared"; - } - } - -=head3 X::Attribute::Undeclared - -Thrown when an undeclared attribute is being referenced. - - my class X::Attribute::Undeclared is X::Undeclared { - has $.package-kind; - has $.package-name; - method message() { - "Attribute $.name not declared in $.package-kind $.package-name"; - } - } - -=head3 X::Phaser::Multiple - -Thrown when multiple phasers of the same type occur in a block, but only one -is allowed (for example C<CATCH> or C<CONTROL>). - - my class X::Phaser::Multiple does X::Comp { - has $.block; - method message() { "Only one $.block block is allowed" } - } - -=head3 X::Parameter::Default - -Thrown when a parameter has a default, but isn't allowed to have one, for -example on mandatory parameters. - - my class X::Parameter::Default does X::Comp { - has $.how; - has $.parameter; - method message() { - $.parameter - ?? "Cannot put default on $.how parameter $.parameter" - !! "Cannot put default on anonymous $.how parameter"; - } - } - - -=head3 X::Parameter::Placeholder - -Thrown when the user tries to use a placeholder as a formal parameter. -(Usually C<:$foo> misspelled as C<$:foo>). - - my class X::Parameter::Placeholder does X::Comp { - has $.parameter; - has $.right; - method message() { - "In signature parameter, placeholder variables like $.parameter are illegal\n" - ~ "you probably meant a named parameter: '$.right'"; - } - } - -=head3 X::Parameter::Twigil - -Thrown when an illegal twigil is used in a formal parameter. - - my class X::Parameter::Twigil does X::Comp { - has $.parameter; - has $.twigil; - method message() { - "In signature parameter $.parameter, it is illegal to use the $.twigil twigil"; - } - } - -=head3 X::Parameter::MultipleTypeConstraints - -Thrown for multiple prefix type constraints like C<Int Str $x>. - - my class X::Parameter::MultipleTypeConstraints does X::Comp { - has $.parameter; - method message() { - qq[{"Parameter $.parameter" || 'A parameter'} may only have one prefix type constraint]; - } - } - -=head3 X::Parameter::WrongOrder - -Thrown when parameters are listed in a signature in the wrong order (for -example optional before mandatory parameters). - - my class X::Parameter::WrongOrder does X::Comp { - has $.misplaced; - has $.parameter; - has $.after; - method message() { - "Cannot put $.misplaced parameter $.parameter after $.after parameters"; - } - } - -=head3 X::Signature::NameClash - -Thrown when multiple named parameters have the same name. - - my class X::Signature::NameClash does X::Comp { - has $.name; - method message() { - "Name $.name used for more than one named parameter"; - } - } - -=head3 X::Method::Private::Permission - -Thrown when attempting to call a private method outside the current class or -role without a fitting trust relation. - - my class X::Method::Private::Permission does X::Comp { - has $.method; - has $.source-package; - has $.calling-package; - method message() { - "Cannot call private method '$.method' on package $.source-package because it does not trust $.calling-package"; - } - } - -=head3 X::Method::Private::Unqualified - -Thrown when attempting to call a method on something else than C<self> without -fully qualifying the class. - - my class X::Method::Private::Unqualified does X::Comp { - has $.method; - method message() { - "Private method call to $.method must be fully qualified with the package containing the method"; - } - } - - -=head3 X::Bind::NativeType - -Thrown when trying to bind to a natively typed variable -TODO: inherit from X::Bind? - - my class X::Bind::NativeType does X::Comp { - has $.name; - method message() { - "Cannot bind to natively typed variable '$.name'; use assignment instead' - } - } - -=head3 X::Attribute::Package - -Thrown when trying to declare an attribute inside a package which doesn't -support attributes. - - my class X::Attribute::Package does X::Comp { - has $.package-kind; - method message() { "A $.package-kind cannot have attributes" } - } - -=head3 X::Attribute::NoPackage - -Thrown when an attribute is declared where it does not make sense (for example -in the mainline) - - my class X::Attribute::NoPackage does X::Comp { - method message() { "You cannot declare an attribute here; maybe you'd like a class or a role?" } - } - -=head3 X::Value::Dynamic - -Thrown when a value must be known at compile time, but is not. - - my class X::Value::Dynamic does X::Comp { - has $.what; - method message() { "$.what value must be known at compile time" } - } - -=head3 X::Declaration::Scope - -Thrown when a declaration does not harmonize with the declared scope (for -example C<has sub foo() { }>. - - my class X::Declaration::Scope does X::Comp { - has $.scope; - has $.declaration; - method message() { "Cannot use '$.scope' with $.declaration declaration" } - } - -=head3 X::Declaration::Scope::Multi - -Thrown when a multi is declared with an incompatible scope, for example C<our -multi sub>. - - my class X::Declaration::Scope::Multi is X::Declaration::Scope { - method message() { - "Cannot use '$.scope' with individual multi candidates. Please declare an {$.scope}-scoped proto instead"; - } - } - -=head3 X::Anon::Multi - -Thrown when an anonymous multi is being declared. - - my class X::Anon::Multi does X::Comp { - has $.multiness; - has $.routine-type = 'routine'; - method message() { "Cannot put $.multiness on anonymous $.routine-type" } - } - -=head3 X::Anon::Augment - -Thrown when trying to augment an anonymous package. - - my class X::Anon::Augment does X::Comp { - has $.package-kind; - method message() { "Cannot augment anonymous $.package-kind" } - } - -=head3 X::Augment::NoSuchType - -Thrown when trying to augment a type which doesn't exist. - - my class X::Augment::NoSuchType does X::Comp { - has $.package-kind; - has $.package; - method message() { "You tried to augment $.package-kind $.package, but it does not exist" } - } - -=head3 X::Package::Stubbed - -Thrown at C<CHECK> time when there are packages stubbed but not later defined. - - my class X::Package::Stubbed does X::Comp { - has @.packages; - # TODO: suppress display of line number - method message() { - "The following packages were stubbed but not defined:\n " - ~ @.packages.join("\n "); - } - } - -=head3 X::Inheritance::Unsupported - -Thrown when trying to inherit from a type that does not support inheritance -(like a package or an enum). - - my class X::Inheritance::Unsupported does X::Comp { - # note that this exception is thrown before the child type object - # has been composed, so it's useless to carry it around. Use the - # name instead. - has $.child-typename; - has $.parent; - method message { - $.child-typename ~ ' cannot inherit from ' ~ - $.parent.^name ~ ' because it is not inheritable'; - } - } - - -=head2 Syntax Errors - -Note that the distinction between general compile-time errors and syntax -errors is somewhat blurry and arbitrary. - -=head3 X::Syntax - - role X::Syntax does X::Comp { } - -Common role for all syntax errors. - -=head3 X::Syntax::Obsolete - -Thrown when obsolete (mostly Perl 5) syntax is detected. - - role X::Syntax::Obsolete does X::Syntax { - has $.old; - has $.replacement; # cannot call it 'new', - # would collide with constructor - has $.when = 'in Perl 6'; - method message() { - "Unsupported use of $.old; $.when please use $.replacement"; - } - } - - -=head3 X::Syntax::Name::Null - -Thrown when a name component is empty, but shouldn't (for example C<use ::;>). - - my class X::Syntax::Name::Null does X::Syntax { - method message() { 'Name component may not be null'; } - } - -=head3 X::Syntax::UnlessElse - -Thrown when an C<unless> clause is followed by an C<else> clause. - - my class X::Syntax::UnlessElse does X::Syntax { - method message() { '"unless" does not take "else", please rewrite using "if"' } - } - -=head3 X::Syntax::Reserved - -Thrown when a syntax is used which is reserved for future expansion. - - my class X::Syntax::Reserved does X::Syntax { - has $.reserved; - has $.instead = ''; - method message() { "The $.reserved is reserved$.instead" } - } - -=head3 X::Syntax::P5 - -Thrown when some piece of syntax is clearly Perl 5, not Perl 6. - - my class X::Syntax::P5 does X::Syntax { - method message() { 'This appears to be Perl 5 code' } - } - -=head3 X::Syntax::NegatedPair - -Thrown when a negated pair has a value, for example C<:!foo($val)>. - - my class X::Syntax::NegatedPair does X::Syntax { - has $.key; - method message() { "Argument not allowed on negated pair with keys '$.key'" } - } - -=head3 X::Syntax::Variable::Numeric - -Thrown on C<my $0> and the likes. - - my class X::Syntax::Variable::Numeric does X::Syntax { - has $.what = 'variable'; - method message() { "Cannot declare a numeric $.what" } - } - -=head3 X::Syntax::Variable::Match - -Thrown on C<< my $<foo> >> and the likes. - - my class X::Syntax::Variable::Match does X::Syntax { - method message() { 'Cannot declare a match variable' } - } - -=head3 X::Syntax::Variable::Twigil - -Thrown on C<my $:foo> and the likes - - my class X::Syntax::Variable::Twigil does X::Syntax { - has $.twigil; - has $.scope; - method message() { "Cannot use $.twigil twigil on $.scope variable" } - } - -=head3 X::Syntax::Variable::IndirectDeclaration - -Thrown on C<my $::($name);> and similar constructs. - - my class X::Syntax::Variable::IndirectDeclaration does X::Syntax { - method message() { 'Cannot declare a variable by indirect name (use a hash instead?)' } - } - -=head3 X::Syntax::Augment::WithoutMonkeyTyping - -Thrown when C<augment> is used without C<use MONKEY-TYPING>. - - my class X::Syntax::Augment::WithoutMonkeyTyping does X::Syntax { - method message() { "augment not allowed without 'use MONKEY-TYPING'" }; - } - -=head3 X::Syntax::Augment::Role - -Thrown when trying to augment a role. - - my class X::Syntax::Augment::Role does X::Syntax { - has $.role-name; - method message() { "Cannot augment role $.role-name, since roles are immutable" }; - } - -=head3 X::Syntax::Placeholder - -Occurs when a placeholder is used in a block that already has a signature -attached. TODO: report the placeholder variables. - - my class X::Signature::Placeholder does X::Syntax { - method message() { - 'Placeholder variable cannot override existing signature'; - } - } - -=head3 X::Syntax::Comment::Embedded - -Thrown when C<#`> is encountered and it is not followed by an opening bracket. - - my class X::Syntax::Comment::Embedded does X::Syntax { - method message() { "Opening bracket required for #` comment" } - } - -=head3 X::Syntax::Pod::BeginWithoutIdentifier - -Thrown when C<=begin> is encountered and no identifier comes after it. - - my class X::Syntax::Pod::BeginWithoutIdentifier does X::Syntax does X::Pod { - method message() { - '=begin must be followed by an identifier; (did you mean "=begin pod"?)' - } - } - -=head3 X::Syntax::Pod::BeginWithoutEnd - -Thrown when C<=begin identifier> is parsed without the matching C<=end identifier>. - - my class X::Syntax::Pod::BeginWithoutEnd does X::Syntax does X::Pod { - method message() { '=begin without matching =end' } - } - -=head3 X::Syntax::Confused - -The most general syntax error, if no more specific error message can be given. - - my class X::Syntax::Confused does X::Syntax { - method message() { 'Confused' } - } - -=head3 X::Syntax::Malformed - -Thrown when a parsed construct is malformed. - - my class X::Syntax::Malformed does X::Syntax { - has $.what; - method message() { "Malformed $.what" } - } - -=head3 X::Syntax::Missing - -Thrown when the previous piece of syntax requires the existence of another -piece of syntax, and that second piece is missing. - - my class X::Syntax::Missing does X::Syntax { - has $.what; - method message() { "Missing $.what" } - } - -=head3 X::Syntax::SigilWithoutName - -Thrown when a sigil without a following name is encountered in a place where -this is not allowed. - - my class X::Syntax::SigilWithoutName does X::Syntax { - method message() { 'Non-declarative sigil is missing its name' } - } - -=head3 X::Syntax::Self::WithoutObject - -Thrown when C<self> is referenced in a place where no invocant is available. - - my class X::Syntax::Self::WithoutObject does X::Syntax { - method message() { "'self' used where no object is available" } - } - -=head3 X::Syntax::VirtualCall - -Thrown when a C<$.foo> style virtual call appears before an object is fully -constructed, for example C<has $.a = $.b;>. - - my class X::Syntax::VirtualCall does X::Syntax { - has $.call; - method message() { "Virtual call $.call may not be used on partially constructed objects" } - } - -=head3 X::Syntax::NoSelf - -Thrown when C<$.foo> style calls are used where no invocant is available. - - my class X::Syntax::NoSelf does X::Syntax { - has $.variable; - method message() { "Variable $.variable used where no 'self' is available" } - } - -=head3 X::Syntax::Number::RadixOutOfRange - -Thrown when the radix of a radix number is larger not allowed, like C<< :1<1> >> -or C<< :42<ouch> >>. - - my class X::Syntax::Number::RadixOutOfRange does X::Syntax { - has $.radix; - method message() { "Radix $.radix out of range (allowed: 2..36)" } - } - -=head3 X::Syntax::Regex::Adverb - -Thrown when an unrecognized or illegal regex adverb is encountered (for -example C<rx:g/a/>). - - my class X::Syntax::Regex::Adverb does X::Syntax { - has $.adverb; - has $.construct; - method message() { "Adverb $.adverb not allowed on $.construct" } - } - -=head3 X::Syntax::Regex::SolitaryQuantifier - -Thrown when a stand alone quantifier in a regex is encountered (for -example C</ * />). - - my class X::Syntax::Regex::SolitaryQuantifier does X::Syntax { - method message { 'Quantifier quantifies nothing' } - } - -=head3 X::Syntax::Term::MissingInitializer - -Thrown when a backslash-variable is declared without initialization assignment. - - my class X::Syntax::Term::MissingInitializer does X::Syntax { - method message { "Term definition requires an initializer" } - } - -=head3 X::Syntax::AddCategorial::MissingSeparator - -Thrown when a circumfix operator is defined without separator between opening and closing terminators. - - my class X::Syntax::AddCategorial::MissingSeparator does X::Syntax { - has $.opname; - method message { "Unable to identify both starter and stopper from $.opname\nPerhaps you forgot to separate them with whitespace?" } - } - -=head3 X::Syntax::Signature::InvocantMarker - -Thrown when the invocant in a signature is anywhere else than after the -first parameter. - - my class X::Syntax::Signature::InvocantMarker does X::Syntax { - method message() { - "Can only use : as invocant marker in a signature after the first parameter" - } - } - -=head3 X::Syntax::Extension::Category - -Thrown when a subroutine of name C<< category:<symbol>() >> is encountered, -and the category is not known. - - my class X::Syntax::Extension::Category does X::Syntax { - has $.category; - method message() { - "Cannot add tokens of category '$.category'"; - } - } - -=head3 X::Syntax::InfixInTermPosition - -Thrown when the parser expects a term, but finds an infix operator. - - my class X::Syntax::InfixInTermPosition does X::Syntax { - has $.infix; - method message() { - "Preceding context expects a term, but found infix $.infix instead"; - } - } - -=head2 X::Pod - - role X::Pod { } - -Common role for all Pod-related errors. - -=head2 Dispatch errors - -=head3 X::Method::NotFound - -Thrown when the user tries to call a method that isn't there, for example -C<1.foo>. - -TODO: should hold the actual invocation, not the type name. Currently that's -due to a limit in Rakudo and Parrot. - - my class X::Method::NotFound is Exception { - has $.method; - has $.typename; - has Bool $.private = False; - method message() { - $.private - ?? "No such private method '$.method' for invocant of type '$.typename'" - !! "No such method '$.method' for invocant of type '$.typename'"; - } - } - -=head3 X::Method::InvalidQualifier - -Thrown when a method is call in the form C<$invocant.TheClass::method> if -<$invocant> does not conform to C<TheClass> - - my class X::Method::InvalidQualifier is Exception { - has $.method; - has $.invocant; - has $.qualifier-type; - method message() { - "Cannot dispatch to method $.method on {$.qualifier-type.^name} " - ~ "because it is not inherited or done by {$.invocant.^name}"; - } - } - -=head2 X::OutOfRange - -General error when something (for example an array index) is out of an allowed -range. - - my class X::OutOfRange is Exception { - has $.what = 'Argument'; - has $.got = '<unknown>'; - has $.range = '<unknown>'; - has $.comment; - method message() { - $.comment.defined - ?? "$.what out of range. Is: $.got, should be in $.range.gist(); $.comment" - !! "$.what out of range. Is: $.got, should be in $.range.gist()" - } - } - -=head2 X::Buf::AsStr - -Thrown when a C<Buf> object is used as string. - - my class X::Buf::AsStr is Exception { - has $.method; - method message() { - "Cannot use a Buf as a string, but you called the $.method method on it"; - } - } - -=head2 X::Buf::Pack - -Thrown when an unknown template/directive is encountered by C<pack> or C<unpack>. - - my class X::Buf::Pack is Exception { - has $.directive; - method message() { - "Unrecognized directive '$.directive'"; - } - } - -=head2 X::Buf::Pack::NonASCII - -Thrown when the C<A> template/directive comes across a non-ASCII character. - - my class X::Buf::Pack::NonASCII is Exception { - has $.char; - method message() { - "non-ASCII character '$.char' while processing an 'A' template in pack"; - } - } - -=head2 X::Bind - -Thrown when trying to bind to something which isn't a valid target for -binding (except for some more special cases listed below). - - my class X::Bind is Exception { - has $.target; - method message() { - $.target.defined - ?? "Cannot bind to $.target" - !! 'Cannot use bind operator with this left-hand side' - } - } - -=head2 X::Bind::Slice - -Thrown when trying to bind to a slice. -TODO: inherit from X::Bind? - - my class X::Bind::Slice is Exception { - has $.type; - method message() { - "Cannot bind to {$.type.^name} slice"; - } - } - -=head2 X::Bind::ZenSlice - -Thrown when trying to bind to a Zen slice, eg C<@a[] := (1, 2)>. - - my class X::Bind::ZenSlice is X::Bind::Slice { - method message() { - "Cannot bind to {$.type.^name} zen slice"; - } - } - -=head2 X::Does::TypeObject - -Thrown when trying to use infix C<does> (not the trait) on a type object. - - my class X::Does::TypeObject is Exception { - method message() { "Cannot use 'does' operator with a type object." } - } - -=head2 X::Role::Initialization - -Thrown when the C<SomeRole($init)> syntax is used, but SomeRole does not have -exactly one public attribute. - - my class X::Role::Initialization is Exception { - method message() { 'Can only supply an initialization value for a role if it has a single public attribute' } - } - -=head2 X::Routine::Unwrap - -Thrown when C<&routine.unwrap> is called with an argument that is not a wrap -handle. - - my class X::Routine::Unwrap is Exception { - method message() { "Cannot unwrap routine: invalid wrap handle" } - } - -=head2 X::Constructor::Positional - -Thrown from C<Mu.new> when positional arguments are passed to it. - - my class X::Constructor::Positional is Exception { - method message() { "Default constructor only takes named arguments" } - } - -=head2 X::Hash::Store::OddNumber - -Thrown when hash assignment finds a trailing hash key with a value. - - my class X::Hash::Store::OddNumber is Exception { - method message() { "Odd number of elements found where hash expected" } - } - -=head2 X::Phaser::PrePost - -Thrown when the condition inside a C<PRE> or C<POST> phaser evaluate to a -false value. - - my class X::Phaser::PrePost is Exception { - has $.phaser = 'PRE'; - has $.condition; - method message { - my $what = $.phaser eq 'PRE' ?? 'Precondition' !! 'Postcondition'; - $.condition.defined - ?? "$what '$.condition.trim()' failed" - !! "$what failed"; - } - } - -=head2 X::Str::Numeric - -Thrown (or wrapped in a C<Failure>) when a conversion from string to number -fails. - - my class X::Str::Numeric is Exception { - has $.source; - has $.pos; - has $.reason; - method source-indicator { - constant marker = chr(0x23CF); - join '', "in '", - $.source.substr(0, $.pos), - marker, - $.source.substr($.pos), - "' (indicated by ", - marker, - ")", - ; - } - method message() { - "Cannot convert string to number: $.reason $.source-indicator"; - } - } - -=head2 X::Str::Match::x - -Thrown when C<Str.match(:$x)> or C<m:x($x)//> is called with an type of C<$x> -that is now allowed. - - my class X::Str::Match::x is Exception { - has $.got; - method message() { - "in Str.match, got invalid value of type {$.got.^name} for :x, must be Int or Range" - } - } - -=head2 X::Str::Trans::IllegalKey - -Thrown when a Pair passed to C<Str.trans> is of a type that the trans method -cannot work with (regexes and types derived from C<Cool> are fine). - - my class X::Str::Trans::IllegalKey is Exception { - has $.key; - method message { - "in Str.trans, got illegal substitution key of type {$.key.^name} (should be a Regex or Str)" - } - } - -=head2 X::Str::Trans::InvalidArg - -Thrown when an argument to C<Str.trans> is not a C<Pair>. - - my class X::Str::Trans::InvalidArg is Exception { - has $.got; - method message() { - "Only Pair objects are allowed as arguments to Str.trans, got {$.got.^name}"; - } - } - -=head2 X::Range::InvalidArg - -Thrown when an argument to C<Range.new> is a C<Range>. - - my class X::Range::InvalidArg is Exception { - has $.got; - method message() { - "{$.got.^name} objects are not valid endpoints for Ranges"; - } - } - -=head2 X::Sequence::Deduction - -Exception type when the C<...> sequence operator is being called without an -explicit closure, and the sequence cannot be deduced. - - my class X::Sequence::Deduction is Exception { - method message() { 'Unable to deduce sequence' } - } - -=head2 X::ControlFlow - -Thrown when a control flow construct (such as C<next> or C<redo>) is called -outside the dynamic scope of an enclosing construct that is supposed to catch -them. - - my class X::ControlFlow is Exception { - has $.illegal; # something like 'next' - has $.enclosing; # .... outside a loop - - method message() { "$.illegal without $.enclosing" } - } - -=head2 X::ControlFlow::Return - -Thrown when a C<return> is called from outside a routine. - - my class X::ControlFlow::Return is X::ControlFlow { - method illegal() { 'return' } - method enclosing() { 'Routine' } - method message() { 'Attempt to return outside of any Routine' } - } - -=head2 X::Composition::NotComposable - -Thrown when trying to compose a type into a target type, but the composer type -cannot be used for composition (roles and enums are generally OK). - - my class X::Composition::NotComposable is Exception { - has $.target-name; - has $.composer; - method message() { - $.composer.^name ~ " is not composable, so $.target-name cannot compose it"; - } - } - -=head2 X::TypeCheck - -Thrown when a type check fails. - - my class X::TypeCheck is Exception { - has $.operation; - has $.got; - has $.expected; - method message() { - "Type check failed in $.operation; expected '{$.expected.^name}' but got '{$.got.^name}'"; - - } - } - -=head2 X::TypeCheck::Binding - -Thrown when the type check of a binding operation fails. - -TODO: figure out if we actually need that type - - my class X::TypeCheck::Binding is X::TypeCheck { - method operation { 'binding' } - } - -=head2 X::TypeCheck::Return - -Thrown when a return type check fails. - -TODO: figure out if we actually need that type - - my class X::TypeCheck::Return is X::TypeCheck { - method operation { 'returning' } - method message() { - "Type check failed for return value; expected '{$.expected.^name}' but got '{$.got.^name}'"; - } - } - -=head2 X::NoDispatcher - -Thrown when a redispatcher like C<nextsame> is called without being in the -dynamic scope of a call that could possible redispatch. - - my class X::NoDispatcher is Exception { - has $.redispatcher; - method message() { - "$.redispatcher is not in the dynamic scope of a dispatcher"; - } - } - -=head2 X::Localizer::NoContainer - -Thrown when C<let> or C<temp> or a similar localizer are used on a -non-container, like C<temp 1 = 2>. - - my class X::Localizer::NoContainer is Exception { - has $.localizer; - method message() { - "Can only use '$.localizer' on a container"; - } - } - -=head2 X::Mixin::NotComposable - -Thrown when a mixin with infix C<does> or C<but> is done with a composer that -cannot be used for mixin. - - my class X::Mixin::NotComposable is Exception { - has $.target; - has $.rolish; - method message() { - "Cannot mix in non-composable type {$.rolish.^name} into object of type {$.target.^name}"; - } - } - -=head2 X::Export::NameClash - -Thrown when a symbol is exported twice. - - my class X::Export::NameClash is Exception { - has $.symbol; - method message() { - "A symbol '$.symbol' has already been exported"; - } - } - -=head2 X::HyperOp::NonDWIM - -Thrown when a non-DWIMy hyperop has lists of lengths that do not match. - - my class X::HyperOp::NonDWIM is Exception { - has &.operator; - has $.left-elems; - has $.right-elems; - method message() { - "Lists on both side of non-dwimmy hyperop of &.operator.name() are not of the same length\n" - ~ "left: $.left-elems elements, right: $.right-elems elements"; - } - } - -=head2 X::Set::Coerce - -Thrown when C<Set($obj)> is called to coerce an object to a C<Set>, and -C<Set> does not know how to handle an object of such type. - - my class X::Set::Coerce is Exception { - has $.thing; - method message { - "Cannot coerce object of type {$.thing.^name} to Set. To create a one-element set, pass it to the 'set' function"; - } - } - -=head2 X::Temporal - -A common exception type for all errors related to C<DateTime> or C<Date>. - - my role X::Temporal is Exception { } - -=head2 X::Temporal::InvalidFormat - -Thrown when the C<Date> or C<DateTime> constructors get a string in a format -which is not a valid date format. - - my class X::Temporal::InvalidFormat is X::Temporal { - has $.invalid-str; - has $.target = 'Date'; - has $.format; - method message() { - "Invalid $.target string '$.invalid-str'; use $.format instead"; - } - } - -=head2 X::Temporal::Truncation - -Thrown when C<DateTime.truncated-to> or C<Date.truncated-to> are called in a -way that doesn't make sense. - - my class X::Temporal::Truncation is X::Temporal { - has $.class = 'DateTime'; - has $.error; - method message() { - "in $.class.truncated-to: $.error"; - } - } - -=head2 X::Eval::NoSuchLang - -Thrown when C<EVAL($str, :$lang)> specifies a language that the compiler does -not know how to handle. - - my class X::Eval::NoSuchLang is Exception { - has $.lang; - method message() { - "No compiler compiler available for language '$.lang'"; - } - } - -=head2 X::Numeric::Real - -Occurs when an attempt to coerce a C<Numeric> to a C<Real>, C<Num>, C<Int> or -C<Rat> fails (due to a number with a nonzero imaginary part, for instance). - - my class X::Numeric::Real is Exception { - has $.source; - has $.target; - has $.reason; - - method message() { - "Can not convert $.source to {$.target.^name}: $.reason"; - } - } - -=head2 X::StubCode - -Occurs when a stub (created via C<!!!>, or C<...> with C<use fatal>) is executed. - - my class X::StubCode is Exception { - has $.message = 'Stub code executed'; - } - -=head1 Related types - -=head2 Failure - - class Failure is Mu { - has Bool $.handled is rw; - has $.X; # the actual exception object - } - -An unthrown exception, usually produce by C<fail()>. - -(Conjecture: S04 implies that all exceptions have a C<$.handled> attribute. -Do we actually need that?) - -=head2 Backtrace - - class Backtrace does Positional[Backtrace::Frame] { - method Stringy() { ... } - method full() { ... } - } - class Backtrace::Frame { - has $.file; - has $.line; - has $.code; - has $.subname; - - method is-hidden () { ... } - method is-routine() { ... } - method is-setting() { ... } - } - -Backtrace information, typically used (but not limited to) in exceptions. -Stringifies to - - in '$<routine>' at line $<line>:$<filename> - in '$<routine>' at line $<line>:$<filename> - ... - -with two leading spaces on each line. - -The default stringification includes blocks and routines from user-space -code, but from the setting only routines are shown [conjectural]. Routines -can be hidden from the default backtrace stringification by apply the -C<hidden-from-backtrace> trait: - - sub my-die(*@msg) is hidden-from-backtrace { } - -the C<is-hidden> method in C<Backtrace::Frame> returns C<Bool::True> for routines -with that trait. - -The C<full> method in C<Backtrace> provides a string representation of the -backtrace that includes all available code objects, including hidden ones. - -If a code object does not have a name, C<< <anon> >> is used instead of the -routine name. - -=head1 The Default Exception Printer - -In case an exception does not get caught by any C<CATCH> or C<CONTROL> block, -it is caught by a default handler in the setting. - -This handler calls the C<.gist> method on the exception, prints the result, -and terminates the program. The exit code is determined as -C<$exception.?exit-code // 1>. - -=head1 AUTHORS - - Moritz Lenz <moritz@faui2k.org> - -Authors of previous versions of this document: - - Tim Nelson <wayland@wayland.id.au> - Larry Wall <larry@wall.org> diff --git a/S32-setting-library/IO-OLD.pod b/S32-setting-library/IO-OLD.pod deleted file mode 100644 index 864cd8d8..00000000 --- a/S32-setting-library/IO-OLD.pod +++ /dev/null @@ -1,1654 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - IO - -=head1 VERSION - - Created: 19 Feb 2009 extracted from S29-functions.pod; added stuff from S16-IO later - - Last Modified: 05 May 2014 - Version: 23 - -The document is a draft. - -=head1 Overview - -The most common IO operations are C<print> and C<say> for writing and -C<lines> and C<get> for reading. All four are available as subroutines -(defaulting to the C<$*OUT> and C<$*ARGFILES> file handles) and as -methods on file handles. - -File handles are of type C<IO::Handle>, and can be created with C<&open>. -Paths are generally passed as strings or C<IO::Path> objects. - -C<&dir> returns C<IO::Path> objects. - - default handle - routine for sub form purpose - ======= =========== ======= - print $*OUT string-based writing - say $*OUT string-based writing - get $*ARGFILES read a line (Str) - lines $*ARGFILES read all lines (Str) - read binary reading (Buf) - write binary writing (Buf) - -File tests are performed through C<IO::Path> objects. - -=head1 Functions - -=over 4 - -=item open -X<open> - - multi open (Str $name, - # mode - Bool :$r = True, - Bool :$w = False, - Bool :$rw = False, - Bool :$a = False, - # encoding - Bool :$bin = False, - Str :$enc = "Unicode", - # newlines - Any :$nl = "\n", - Bool :$chomp = True, - ... - --> IO::Handle - ) is export - -A convenience function that hides most of the OO complexity. -It will only open normal files. Text is the default. Note that -the "Unicode" encoding implies figuring out which actual UTF is -in use, either from a BOM or other heuristics. If heuristics are -inconclusive, UTF-8 will be assumed. (No 8-bit encoding will ever -be picked implicitly.) A file opened with C<:bin> may still be -processed line-by-line, but IO will be in terms of C<Buf> rather -than C<Str> types. - -For a discussion of the read/write/append modes (:r, :w, :a), see -L</IO::Handle/open> under IO::Handle. - -=item dir -X<dir> - - multi dir($directory = '.', Mu :$test = none('.', '..')) { ... } - -Returns a lazy list of file names in the C<$directory>. By default the current -and the parent directory are excluded, which can be controlled with the -C<$test> named parameter. Only items that smart-match against this test are -returned. - -The return value is a list of C<IO::Path> objects. Because of this, you may -want use the C<basename> method on the results to get the just the file name, -without its full path. If dir() fails, it returns an -L<X::IO::Dir|S32::Exception/X::IO::Dir> failure. - -=item glob - - multi glob(Str $pattern --> Array[Str]) - -Accepts a pattern that will then be expanded into a array of filenames (the -creation of C<IO> objects from this list is left to the user). - -The default C<glob> function operates on POSIX rules, which may be read in more -detail in the glob(7) manpage, however an overview is presented below. - -The C<glob> function understands a few metacharacters: - - \ Escape metacharacter - ~ Home directory - ? Match exactly one character - * Match zero or more characters - [ Start of character class (ends with ]) - -Note that this is not a regex-like syntax, so the C<?> and C<*> are not -quantifiers. - - glob("foo?"); # roughly equivalent to /^ foo. $/, NOT /^ foo? $/ - glob("*bar"); # valid syntax; roughly equivalent to /^ .* bar $/ - -The character class construct C<[...]> matches all characters specified. It has -a few metacharacters of its own: - - glob("[]]"); # matches the ] character - glob("[!abc]"); # matches all but 'a', 'b', or 'c' (negation) - glob("[a-z]"); # matches all lowercase letters from a to z (range) - glob("[a-]"); # matches 'a' and '-' - glob("[[:xdigit:]]"); # matches hexadecimal digit (named character class) - -Ranges matches all the characters that fall between and the startpoint and -endpoint, inclusively. Note that the C</> character can never be matched by a -range. If contained within the a range (such as C<[--0]>), the C</> is -skipped. If explicitly specified as the start- or endpoint, it's considered a -syntax error. - - glob("[--0]"); # matches '-', '.', or '0' (skips '/') - glob("[a/b]"); # matches 'a', '/', or 'b' - glob("[/-0]"); # syntax error - -There are some notable departures from POSIX in terms of what the Perl 6 -C<&glob> function allows with character classes. Namely, neither the C<[[.ch.]]> -nor C<[[=ch=]]> forms are supported, and the C<[^...]> form is not undefined, -but rather matches the C<^> character among other things. - -Glob metacharacters that must be escaped outside character classes aren't -within. - - glob('\[\*\?\~'); # Matches the filename "[*?~" - glob("[[*?~]"); # Matches the filenames "[", "*", "?", and "~" - -Unlike Perl 5, no special attention is given to the interpolation rules of -strings, particularly braces. - -=item note - - multi note (*@LIST --> Bool) - -Does a "say" to C<$*ERR>, more or less. Like C<warn>, it adds a -newline only if the message does not already end in newline. Unlike -C<warn>, it is not trappable as a resumable exception because it -outputs directly to C<$*ERR>. You can suppress notes in a lexical -scope by declaring: - - only note(*@) {} - -=item slurp - - multi slurp (IO::Handle $fh = $*ARGFILES, - Bool :$bin = False, - Str :$enc = "Unicode", - --> Str|Buf - ) - multi slurp (Str $filename, - Bool :$bin = False, - Str :$enc = "Unicode", - --> Str|Buf - ) - -Slurps the entire file into a C<Str> (or C<Buf> if C<:bin>) regardless of context. -(See also C<lines>.) - -The routine will C<fail> if the file does not exist, or is a directory. - -=item spurt - - multi spurt (IO::Handle $fh, - Str $contents, - Str :$enc = $?ENC, - Bool :append = False, - Bool :$createonly = False, - ) - multi spurt (IO::Handle $fh, - Buf $contents, - Bool :append = False, - Bool :$createonly = False, - ) - multi spurt (Str $filename, - Str $contents, - Str :$enc = $?ENC, - Bool :append = False, - Bool :$createonly = False, - ) - multi spurt (Str $filename, - Buf $contents, - Bool :append = False, - Bool :$createonly = False, - ) - -Opens the file for writing, dumps the contents, and closes the file. - -This routine will C<fail> if the file exists and C<:createonly> is set. - -If C<:append> is provided, an existing file will not be clobbered, but the -string will be appended. - -The routine will also C<fail> with the corresponding exception if there was any -other error in opening, writing, or closing. - -=item chdir - - multi sub chdir(Str:D) - multi sub chdir(IO::Path:D) - -Changes the current (emulated) working directory to the new value, scoped to the current scope of C<$*CWD> (usually thread-local at worst, or the scope of a C<visitdir> inside the current thread). Fails (X::IO::Chdir) on error. -If C<$*CWD> is not scoped to the current dynamic scope, you must call C<chdir> again when exiting the -dynamic scope to get back to the original directly, just as you would with a real C<chdir>. In this case -you would probably be better off using C<visitdir> instead, which will automatically scope C<$*CWD> to the current -dynamic scope. - -Note that actually changing the process's working directory requires -a call to C<PROCESS::chdir> (which will inform the chdir emulation -that the process's actual current working directory has changed). -This function is not threadsafe, however. And if calling out to a -foreign function, only one thread can safely use it; in general it's -better to pass absolute paths to foreign functions that don't allow -you to set the working directory as a parameter. - -=item visitdir - - multi sub visitdir(Str:D) - multi sub visitdir(IO::Path:D) - -Changes the current (emulated) working directory to the new -value, scoped to the current dynamic scope just as C<temp $*CWD = newdir();> -would. Fails (X::IO::Chdir) on error. Since C<$*CWD> is dynamically scoped, -leaving the current dynamic scope automatically restores the current (emulated) -working directory. - -=item unlink - - sub unlink(Cool:D $path) - -Unlinks an ordinary file, link, or symbolic link from disk -- that is, it is -deleted. Returns True on success; otherwise returns an L<S32::Exception/X::IO::Unlink> -failure. - -=item rmdir - - sub rmdir(Cool:D $directory) - -Removes the directory given from disk. Returns True on success, or an -L<X::IO::Rmdir|S32::Exception/X::IO::Rmdir> failure. - -=item mkdir - - sub mkdir(Cool:D $directory) - -Makes (creates) the directory represented by the IO::Path. Returns True on success, -or an L<X::IO::Mkdir|S32::Exception/X::IO::Mkdir> failure. - - -=back - -=head1 IO Types - -=head2 IO - - role IO { }; - -The base role only tags that this is an C<IO> object for more generic -purposes. It doesn't specify any methods or attributes. - - -=head2 IO::Handle - - class IO::Handle does IO { ... } - -A handle of a file, pipe or anything else that supports reading or -writing like a file. - -=over 4 - -=item open - - multi method open ( - # mode - Bool :$r = True, - Bool :$w = False, - Bool :$rw = False, - Bool :$a = False, - # encoding - Bool :$bin = False, - Str :$enc = "Unicode", - # newlines - Any :$nl = "\n", - Bool :$chomp = True, - --> IO::Handle - ) is export - -Open the handle for reading or writing (or both). Specifying C<:r>, the default, -opens the handle as read-only, C<:w> is write-only, C<:rw> is read-write, and -C<:a> appends writes to the file. - -The C<:enc> parameter controls which text encoding the file is interpreted as. -Unicode is the default encoding. See L</encoding> for encoding options. - -The C<:nl> option sets L</input-line-separator>, and C<:chomp> determines if -the new line separator will be chopped removed by C<get> and C<lines>. - -Conjectural: The <:p> parameter opens a pipe, which is readable with C<:r> -(default) and writable with C<:w>. - -=item get - - method get() returns Str:D - -Reads and returns one line from the handle. Uses C<input-line-separator> -to determine where a line ends. - -=item lines - - method lines($limit = Inf) - -Returns a lazy list of lines read via the C<get> method, limited to C<$limit> -lines. - -=item getc -X<getc> - - method getc (IO::Handle:D: Int $chars = 1 --> Str) - -Reads C<$chars> and returns them - -=item print -X<print> - - method print (IO::Handle:D: *@LIST --> Bool) - multi print (*@LIST --> Bool) - -Stringifies each element, concatenates those strings, and sends the -result to the output. -Returns C<Bool::True> if successful, C<Failure> otherwise. - -The compiler will warn you if use a bare sub C<print> without arguments. -(However, it's fine if you have an explicit argument list that evaluates to -the empty list at runtime.) - - print; # warns - if $_ { print } # warns - if $_ { print() } # ok, but does nothing - if $_ { print () } # ok, but does nothing - -=item say -X<say> - - method say (IO::Handle:D: *@LIST --> Bool) - multi say (*@LIST --> Bool) - -This is identical to print() except that it stringifies its arguments by calling -C<.gist> on them and auto-appends a newline after the final argument. - - Was: print "Hello, world!\n"; - Now: say "Hello, world!"; - -As with C<print>, the compiler will warn you if you use a bare sub C<say> -without arguments. - -=item printf -X<printf> - - method printf (Str $fmt, *@LIST --> Bool) - multi printf (IO::Handle:D: Str $fmt, *@LIST --> Bool) - -Output through C<Str.sprintf>. See L<S32::Str> for details. - -=item write - - method write(IO::Handle:D: Buf $buf --> Int) - -Tries to write C<$buf>. The actual number of bytes -written is returned. It might return unthrown failures, to be -specified by each C<IO> implementation. - -This is "raw" write. C<$buf> contains plain octets. If you want to C<write> -a C<Str>, you should C<.encode> it first, or use "print" or other -C<IO::Writeable::Encoded> methods. - -=item slurp - - method slurp( - Bool :$bin = False, - Str :$enc = "Unicode", - --> Str|Buf) - -Opens the handle if necessary, slurps the entire file into a C<Str> -(or C<Buf> if C<:bin> parameter is given) regardless of context. Closes the -handle after it is done, and returns the contents of the file. -(See also L</lines>.) - -The routine will C<fail> if the file does not exist, or is a directory. - -=item spurt - - multi method spurt ( - Str $contents, - Str :$enc = $?ENC, - Bool :append = False, - Bool :$createonly = False) - - multi method spurt ( - Buf $contents, - Bool :append = False, - Bool :$createonly = False) - -Opens the file for writing, dumps the contents, and closes the file. - -This routine will C<fail> if the file exists and C<:createonly> is set. - -If C<:append> is provided, an existing file will not be clobbered, but the -string will be appended. - -The routine will also C<fail> with the corresponding exception if there was any -other error in opening, writing, or closing. - -=item t - - method t() returns Bool:D - -Returns C<True> if the handle is opened to a tty. - -=item p - - method p() returns Bool:D - -Returns C<True> if the handle is opened to a pipe. - -=item eof - - method eof() returns Bool:D - -Returns C<True> if the handle is exhausted. - -=item seek - -method seek(Int $position, Int $whence --> Bool) - -Position this stream into C<$position>. The meaning of this position is -always in "octets". - -Fails if the handle is not seekable. - -TODO: make $whence an Enum - -=item tell - - method tell() returns Int:D: - -Returns the current raw position in the stream in number of "octets". - -=item ins - - method ins( --> Int) - -Returns the number of lines that have been read with C<get>. - -=item input-line-separator - - method input-line-separator( --> Str) is rw - -This regulates how C<get> and C<lines> behave. - -The input line (record) separator, newline by default. -This influences Perl's idea of what a ``line'' is. -Works like awk's RS variable, including treating empty lines -as a terminator if set to the null string. -(An empty line cannot contain any spaces or tabs.) -You may set it to a multi-character string to match a multi-character -terminator, or to Nil to read through the end of file. -Setting it to "\n\n" means something slightly different -than setting to "", if the file contains consecutive empty lines. -Setting to "" will treat two or more consecutive empty lines -as a single empty line. Setting to "\n\n" will blindly assume -that the next input character belongs to the next paragraph, -even if it's a newline. - -You may also set it to a regular expression. The value of C<$/> -will be (temporarily) set to the matched separator upon input, -if you care about the contents of the separator. - -=item encoding - - multi method encoding($enc?) - -With no arguments, simply returns the current encoding used on the handle. -If supplied a string identifying a valid encoding, change the handle to read -with that encoding. Options include C<binary>, C<utf8>, and -other text encodings. An invalid encoding causes the method to fail. - -=item IO - -Returns the handle itself (no-op). - -=item close - -Closes the handle. Fails on error. - -=back - -=head2 IO::FileTestable - - role IO::FileTestable does IO { ... } - -Provides ways to inspect a file or path without opening it. - -If you apply that role to a class, that class must provide a C<Str> method -which returns the full path. C<IO::FileTestable> will call this method -to obtain the path to test. Stringification must return C<Str:D> here. - -The methods are typically only one letter long (for now; Perl 5 tradition -strikes) and are summarized in the following table: - - M Test performed Returns - = ============== ======= - r Path is readable by effective uid/gid. Bool:D - w Path is writable by effective uid/gid. Bool:D - x Path is executable by effective uid/gid. Bool:D - o Path is owned by effective uid. Bool:D - - R Path is readable by real uid/gid. Bool:D - W Path is writable by real uid/gid. Bool:D - X Path is executable by real uid/gid. Bool:D - O Path is owned by real uid. Bool:D - - e Path exists. Bool:D - s Size of the path in bytes. Int:D - z Path has zero size (an empty file). Bool:D - - f Path is a plain file. Bool:D - d Path is a directory. Bool:D - l Path is a symbolic link. Bool:D - p Path is a named pipe (FIFO) Bool:D - S Path is a socket. Bool:D - b Path is a block special file. Bool:D - c Path is a character special file. Bool:D - - u Path has setuid bit set. Bool:D - g Path has setgid bit set. Bool:D - k Path has sticky bit set. Bool:D - -All methods (except for C<e>) return the appropriate type object if a path -has been specified that does not exist. - -=over 4 - -=item accessed -X<stattimes> - -Returns the last access time (C<atime>) of the path, to the degree that it is -updated on that system. - -=item modified - -Returns the time that the path was last modified (C<mtime>). - -=item changed - -Returns the time that the path was last changed (modified or a metadata change). - -=item stat - -Returns a stat buffer for the path. - -=back - -TODO: methods created, accessed, modified: return format, failure - -=head2 IO::Path - - class IO::Path is Cool does IO::FileTestable { } - -Holds a path of a file or directory. The path is generally divided -into three parts, the I<volume>, I<directory> and I<base name>. - -On Windows, the volume is a drive letter like C<C:>, or a UNC network volume -like C<\\share\>. On UNIX-based systems, the volume part is empty. - -The base name is name of the file or directory that the IO::Path object -represents, and the directory is the part of the path leading up to the base -name. - - path volume directory base name - /usr/bin/gvim /usr/bin gvim - /usr/bin/ /usr bin - foo/bar.txt foo bar.txt - C:\temp\f.txt C: \temp f.txt - \\server\share\a \\server\share \ a - -IO::Path uses the syntax for the current operating system. If -you want to work paths as if you were using another OS, use the OS-specific -subclasses such as IO::Path::Cygwin. - -There are several ways of creating an IO::Path. Both IO::Handle and Cool have -a .path method, or you can construct it directly: - - "my/path".path - $filehandle.path - IO::Path.new( $full-path ); - IO::Path.new( :$volume, :$directory, :$basename); - -=over 4 - -=item Str - -Stringification returns the path (volume, directory and base name joined -together) as a string. - -=item volume - -Returns the volume part of the path. On Unix-like OSes or systems without a -concept of volume in the path, returns the empty string. - -=item directory - -Returns the directory part of the path, not including the last item. Functions -equivalently to the C<dirname> shell program on Unix-like systems. - -=item basename - -Returns the base name part of the path -- that is, the last portion. Functions -equivalently to the C<basename> shell program on Unix-like systems. - -=item path - -Returns the entire IO::Path object (a no-op). - -=item contents - - method contents( Mu :$test = none('.', '..') ) - -Returns a lazy list of file names in the path, if it is a directory. The -current and the parent directory are excluded, which can be controlled with -the C<$test> named parameter. Only items that smart-match against this test -are returned. - -The return value is a list of C<IO::Path> objects. Because of this, you may -want use the C<basename> method on the results to get the just the file name, -without its full path. - -=item cleanup - - method cleanup( :$parent = False ) - -Returns a new IO::Path object with the canonical path. This eliminates extra -slashes and C<'.'> directories, but leaves C<'..'> in (or whatever the parent -directory is called on that platform). - -With C<:parent>, cleanup will logically remove references to the parent -directory without I<checking the filesystem>. That is, the parent of a -symbolic link will remove the symlink itself, not the parent of the symlink's -destination. - -=item resolve - -Returns a new IO::Path object that is cleaned-up (as above), and all symbolic -links and references to the parent directory (C<..>) are physically resolved. -This means that the filesystem is examined for each directory in the path, -and any symlinks found are followed. Identical to C<.cleanup(:parent)> on systems -where symbolic links are not supported. - - # bar is a symlink pointing to "/baz" - my $path = "foo/./bar///..".path; - $path.=cleanup; # now "foo/bar/.." - $path.cleanup(:parent); # yields "foo" - $path.=resolve; # now "/" (the parent of "/baz") - -=item is-relative - -Returns True if the path is a relative path (like C<foo/bar>), False -otherwise. - -=item is-absolute - -Returns True if the path is an absolute path (like C</usr/bin>), False -otherwise. - -=item absolute - - method absolute ( Str $base = $*CWD ) - -Transforms the path into an absolute form, and returns the result as a new -IO::Path. If C<$base> is supplied, transforms it relative to that base -directory; otherwise the current working directory is used. Paths that are -already absolute are returned unchanged. - -=item relative - - method relative ( Str $base = $*CWD ) - -Transforms the path into an relative form, and returns the result as a new -IO::Path. If C<$base> is supplied, transforms it relative to that base -directory; otherwise the current working directory is used. Paths that are -already relative are returned unchanged. - -=item parent - -Removes the last portion the given path, and returns a new IO::Path. This does -not remove C<.>, C<..>, or symbolic links, so you may want to consider calling -cleanup or resolve first. - -On a Unix/POSIX filesystem, if called recursively, it will work like so: - - parent level relative absolute - Starting Path (0) foo/bar /foo/bar - 1 foo /foo - 2 . / - 3 .. / - 4 ../.. / - 5 ../../.. / - -=item child - - method child ( Str $childname ) - -Appends C<$childname> to the end of the path, adding path separators where -needed and returns the result as a new IO::Path. - -=item succ - -Increments the basename portion of the string, as Str.succ does, and returns -that successor as an IO::Path. - -This is useful for getting all the parts of say, a multi-part archive, but -does not always return the next item in the folder. To crawl a folder, you -probably want to iterate on the parent directory's contents. - -=item pred - -Decrements the basename portion of the string, as Str.pred does, and returns -that predecessor as an IO::Path. - -=item copy - - method copy ($dest, :$createonly = False ) - -Copies a file from the path, to the destination specified. If :createonly is -set to True, copy fails when a file already exists in the destination. If the -operation cannot be completed, fails as X::IO::Copy. - -=item unlink - -Unlinks (deletes) the ordinary file, link, or symbolic link represented by the -IO::Path. Returns True on success; on error, fails with an X::IO::Unlink. - -=item rmdir - -Removes (deletes) the directory represented by the IO::Path. Typically fails -unless the directory is empty. Returns True on success; fails with an X::IO::Rmdir -on error. - -=item mkdir - -Makes (creates) the directory represented by the IO::Path. Returns True on success. -The method will C<fail> with L<X::IO::Mkdir|S32::Exception/X::IO::Mkdir> if it -can not create the directory, if file or directory already exists or if the parent -directory of the path does not exist. - -=back - -=head3 OS Specific subclasses. - -IO::Path::Unix, IO::Path::Win32, and IO::Path::Cygwin subclasses are available -for manipulating paths from different operating systems than the one you're -currently using. Unix works with any POSIX-like operating system, such as Linux -or Darwin. Win32 works for paths from Windows, DOS, OS/2, NetWare, and Symbian. - -=head2 IO::Spec - -This class is a collection of methods dealing with file specifications (commonly -known as file names, though it can include the entire directory path). -Most of the methods are less convenient than in IO::Path, but it allows access -to lower-level operations on file path strings. - -As with IO::Path, these operations are significantly different on some operating -systems, so we have the following subclasses: IO::Spec::Unix, IO::Spec::Win32, -and IO::Spec::Cygwin. IO::Spec automatically loads the correct module for use -on the current system. - -Each class can (and should) be used in its undefined form: - - my $cleanpath = IO::Spec.canonpath("a/.//b/") # gives "a/b" - -Although we inherit a lot from Perl 5's File::Spec, some things have changed: -C<no_updirs> has been removed (but see C<no-parent-or-current-test>) and -C<case_tolerant> has also been removed (and put in a module). Method C<join> -is no longer an alias for catfile, but is now a function similar to C<catpath>. - -Each of the following methods are available under the subclasses, with the -exception of C<os>. - -=over - -=item os - -The os method takes a single argument, an operating system string, and returns -an IO::Spec object for the appropriate OS. - - my $mac_os_x_spec = File::Spec.os('darwin'); - # returns a File::Spec::Unix object - my $windows_spec = File::Spec.os('MSWin32'); - #returns File::Spec::Win32 - say File::Spec.os('Win32').canonpath('C:\\foo\\.\\bar\\'); - # prints "C:\foo\bar" - -The parameter can be either an operating system string, or the last part of -the name of a subclass ('Win32', 'Mac'). The default is `$*OS`, which gives -you the same subclass that IO::Spec already uses for your system. - -This is only implemented by the IO::Spec class, and not its subclasses. - - -=item canonpath -X<canonpath> - -No physical check on the filesystem, but a logical cleanup of a -path. - - $cpath = IO::Spec.canonpath( $path ) ; - -Note that this does *not* collapse F<x/../y> sections into F<y>. This -is by design. If F</foo> on your system is a symlink to F</bar/baz>, -then F</foo/../quux> is actually F</bar/quux>, not F</quux> as a naive -F<../>-removal would give you. If you want to do this kind of -processing, you probably want IO::Path's C<resolve> method to -actually traverse the filesystem cleaning up paths like this. - -=item is-absolute - -Takes as its argument a path, and returns True if it is an absolute path, -False otherwise. For File::Spec::Win32, it returns 1 if it's an absolute -path with no volume, and 2 if it's absolute with a volume. - - $is_absolute = IO::Spec.is-absolute( $path ); - - -=item splitpath -X<splitpath> - - method splitpath( $path, $nofile = False ) - -Splits a path in to volume, directory, and filename portions. On systems -with no concept of volume, returns '' for volume. - - my ($volume,$directories,$file) = IO::Spec.splitpath( $path ); - my ($volume,$directories,$file) = IO::Spec.splitpath( $path, $no_file ); - -For systems with no syntax differentiating filenames from directories, -assumes that the last file is a path unless C<$no_file> is true or a -trailing separator or F</.> or F</..> is present. On Unix, this means that C<$no_file> -true makes this return ( '', $path, '' ). - -The directory portion may or may not be returned with a trailing '/'. - -The results can be passed to L</catpath()> to get back a path equivalent to -(usually identical to) the original path. - -=item split - -A close relative of `splitdir`, this function also splits a path into -volume, directory, and filename portions. Unlike splitdir, split returns -paths compatible with dirname and basename I<and> returns it arguments as -a hash of C<volume>, C<directory>, and C<basename>. - -This means that trailing slashes will be eliminated from the directory -and basename components, in Win32 and Unix-like environments. The basename -component will always contain the last part of the path, even if it is a -directory, C<'.'>, or C<'..'>. If a relative path's directory portion would -otherwise be empty, the directory is set to C<'.'> (or whatever C<curdir> is). - -On systems with no concept of volume, returns C<''> (the empty string) for volume. - - my %splitfile = IO::Spec.split( $path ); - say IO::Spec::Win32( "C:\\saga\\waffo\\" ); - # ("volume" => "C:", "directory" => "\\saga", "basename" => "waffo") - -The results can be passed to `.join` to get back a path equivalent to -(but not necessarily identical to) the original path. If you want to keep -all of the characters involved, use `.splitdir` instead. - -=item Comparison of splitpath and split - - OS Path splitpath split (.values) - linux /a/b/c ("", "/a/b/", "c") ("", "/a/b", "c") - linux /a/b//c/ ("", "/a/b//c/", "") ("", "/a/b", "c") - linux /a/b/. ("", "/a/b/.", "") ("", "/a/b", ".") - Win32 C:\a\b\ ("C:", "\\a\\b\\", "") ("C:", "\\a", "b") - VMS A:[b.c] ("A:", "[b.c]", "") ("A:", "[b]", "[c]") - -* The VMS section is still speculative, and not yet supported. - -=item catpath() - -Takes volume, directory and file portions and returns an entire path string. -Under Unix, C<$volume> is ignored, and directory and file are concatenated. -On other OSes, C<$volume> is significant. Directory separators like slashes -are inserted if need be. - - $full_path = IO::Spec.catpath( $volume, $directory, $file ); - -=item join - -A close relative of `.catpath`, this function takes volume, directory and -basename portions and returns an entire path string. If the dirname is `'.'`, -it is removed from the (relative) path output, because this function inverts -the functionality of dirname and basename. - - $full-path = IO::Spec.join(:$volume, :$directory, :$basename); - say IO::Spec::Unix.join( directory => '/hobbit', basename => 'frodo' ); - # "/hobbit/frodo" - -Directory separators are inserted if necessary. Under Unix, $volume is -ignored, and only directory and basename are concatenated. On other OSes, -$volume is significant. - -This method is the inverse of `.split`; the results can be passed to it -to get the volume, dirname, and basename portions back. - - -=item Comparison of catpath and join - - OS Components catpath join - linux ("", "/a/b", "c") /a/b/c /a/b/c - linux ("", ".", "foo") ./foo foo - linux ("", "/", "/") // / - Win32 ("C:", "\a", "b") C:\a\b C:\a\b - VMS ("A:", "[b]", "[c]") A:[b][c] A:[b.c] - -* The VMS section is still speculative, and not yet supported. - -=item splitdir -X<splitdir> - -The opposite of L</catdir>. - - @dirs = IO::Spec.splitdir( $directories ); - -C<$directories> must be only the directory portion of the path on systems -that have the concept of a volume or that have path syntax that differentiates -files from directories. - -Unlike just splitting the directories on the separator, empty -directory names (C<''>) can be returned, because these are significant -on some OSes. - -=item catdir -X<catdir> - -Concatenate two or more directory names to form a complete path ending -with a directory. Removes any trailing slashes from the resulting -string, unless it's the root directory. - - $path = IO::Spec.catdir( @directories ); - -=item catfile -X<catfile> - -Concatenate one or more directory names and a filename to form a -complete path ending with a filename - - $path = IO::Spec.catfile( @directories, $filename ); - -=item abs2rel -X<abs2rel> - -Takes a destination path and an optional base path returns a relative path -from the base path to the destination path: - - $rel_path = IO::Spec.abs2rel( $path ) ; - $rel_path = IO::Spec.abs2rel( $path, $base ) ; - -If C<$base> is not present or '', then C<$*CWD> is used. If C<$base> is -relative, then it is converted to absolute form using -L</IO::Spec/rel2abs>. This means that it is taken to be relative to -C<$*CWD>. - -On systems with the concept of volume, if C<$path> and C<$base> appear to be -on two different volumes, we will not attempt to resolve the two -paths, and we will instead simply return C<$path>. - -On systems that have a grammar that indicates filenames, this ignores the -C<$base> filename as well. Otherwise all path components are assumed to be -directories. - -If C<$path> is relative, it is converted to absolute form using L</IO::Spec/rel2abs>. -This means that it is taken to be relative to C<$*CWD>. - -No checks against the filesystem are made. - -=item rel2abs -X<rel2abs> - -Converts a relative path to an absolute path. - - $abs_path = IO::Spec.rel2abs( $path ) ; - $abs_path = IO::Spec.rel2abs( $path, $base ) ; - -If C<$base> is not present or '', then C<$*CWD> is used. If C<$base> is also -relative, then it is first converted to absolute form, relative to C<$*CWD>. - -On systems with the concept of volume, if C<$path> and C<$base> appear to be -on two different volumes, IO::Spec will not attempt to resolve the two -paths, and will instead simply return C<$path>. - -On systems that have a grammar that indicates filenames (like VMS), this -ignores the C<$base> filename as well. Otherwise all path components are -assumed to be directories. - -If C<$path> is absolute, it is cleaned up and returned using L</canonpath>. - -No checks against the filesystem are made. - -=item curdir -X<curdir> - -Returns a string representation of the current directory (C<.> on Linux and Windows). - - my $curdir = IO::Spec.curdir; - -=item updir -X<updir> - -Returns a string representation of the parent directory (C<..> on Linux and Windows). - - my $updir = IO::Spec.updir; - -=item rootdir -X<rootdir> - -Returns a string representation of the root directory (C</> on Linux). - - my $rootdir = IO::Spec.rootdir; - -=item devnull -X<devnull> - -Returns a string representation of the null device (C</dev/null> on Linux). - - my $devnull = IO::Spec.devnull; - -=item path -X<path> - -Takes no argument. Returns the environment variable C<PATH> (or the local -platform's equivalent) as a list. - - my @PATH = IO::Spec.path; - -=item tmpdir -X<tmpdir> - -Returns a string representation of the first writable directory from a -list of possible temporary directories. Returns the current directory -if no writable temporary directories are found. The list of directories -checked depends on the platform; e.g. IO::Spec::Unix checks C<%*ENVE<lt>TMPDIRE<gt>> -and F</tmp>. - - $tmpdir = IO::Spec.tmpdir; - -=for comment -(sorry about the ugly E<> escapes above, Pod::To::* seems to misinterpret it otherwise) - -=item no-parent-or-current-test - -Returns a test as to whether a given path is identical to the parent or the -current directory. On Linux, this is simply C<none('.', '..')>. The L</Functions/dir> -function automatically removes these for you in directory listings, so under -normal circumstances you shouldn't need to use it directly. - - 'file' ~~ IO::Spec.no-parent-or-current-test #False - '.' ~~ IO::Spec.no-parent-or-current-test #True - '..' ~~ IO::Spec.no-parent-or-current-test #True - -This can, however, be used to extend C<dir()> through its `$test` parameter: - - dir( "my/directory", test=> - all(IO::Spec.no-parent-or-current-test, /^ '.' /)); - -This example would return all files beginning with a period that are -not `.` or `..` directories. This would work similarly with IO::Path.contents. - -This method replaces the functionality of the Perl 5 C<no_updirs> method. - -=back - -=head1 Here Be Dragons - -Everything below this point hasn't been reviewed properly - -=head2 IO::Socket - - role IO::Socket { - has %.options; - has Bool $.Listener; - ... - } - -Accessing the C<%.options> would on Unix be done with I<getsockopt(2)>/I<setsockopt(2)>. - -The $.Listener attribute indicates whether the socket will be a listening socket when -opened, rather than indicating whether it is currently listening. - -=over - -=item new - - method new( - :$Listener, # initializes $.Listener - ) - -The initial value of the $.Listener attribute is defined according to the following rules: - - * If $Listener is passed to .new(), then that value is used - * If neither a local address nor a remote address are passed in, throw an exception - * If no remote address is passed, then $.Listener is set to SOMAXCONN - * If no local address is used, then $Listener is set to 0 - * If both local and remote addresses are used, throw an exception that asks people to - specify $Listener - -=item open - - method open() - -If $.Listener is true, does a I<bind(2)> and a I<listen(2)>, otherwise does a -I<connect(2)>. - -It's end-user use case is intended for the case where NoOpen is passed to .new(). .new() -itself will presumably also call it. - -=item close - - method close() - -Implements the close() function from IO::Closeable by doing a shutdown on the connection -(see below) with @how set to ('Readable', 'Writeable'). - -=item shutdown - - method shutdown(Str @how) - -Does a I<shutdown(2)> on the connection. See also IO::Readable.isReadable and -IO::Writeable.isWriteable. - -$how can contain 1 or more of the strings 'Readable' and 'Writeable'. - -=item accept - - method accept( --> IO::Socket) - -=item method read(Int $bytes --> Buf) - -Reads and returns C<$bytes> bytes from the handle - -=item method write(Buf $buf --> Int) - -Implements the IO::Writeable interface by doing a I<send(2)>. - -=back - -=head2 IO::Socket::INET - - class IO::Socket::INET does IO::Socket { - has Str $.proto = 'TCP'; - has Str $.host; - has Int $.port; - has Str $.localhost; - has Int $.localport; - ... - } - -=over - -=item new - - multi method new(:$host!, :$port, *%attributes) { ... } - multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... } - -Creates a new socket and opens it. - -=back - -=head2 IO::Handle (opened version) - -This role indicates that this object actually represents an open file -descriptor in the os level. - -=over - -=item method int fileno() - -File descriptors are always native integers, conforming to C89. - -=back - - -=head1 Conjectural Stuff - -Everything below this point should be considered as mere ideas for -future evolution, not as things that a compiler write should implement -unquestioningly. - -=head2 IO::ACL - -This is a basic abstraction; for better control, use the operating-system specific -interfaces, over which this is a thin veneer. - - class IO::ACL { - has Str $.type; # "User", "Group", "Everyone", ??? - has Str $.id; # username or groupname; unused for $type eq "Everyone" - has %.permissions; - # Unsupported values may (or may not) throw - # UnsupportedPermission when set or read - has Path $.owningObject; - ... - } - -The permissions used in C<%permissions> are: - -=over - -=item Readable - -Should be supported by all filesystems as an item to read from the hash for the group -"Everyone". - -=item Writeable - -Should be supported by all filesystems as an item to read from the hash for the group -"Everyone". - -=item Executable - -Supported on most Unix systems, anyway. Windows should be able to guess when this is -read, and throw an exception if written to. - -=item Default - -An ACL of User,fred,Default sets the user "fred" to be the owner of the file. This can be -done with groups too. Works on Unix, at least. - -=back - -The C<$.owningObject> attribute of C<ACL> shows what the ACL is set on. On a -Windows system, this can be a parent directory, as permissions are inherited. - - -=head2 IO::Pipe - - class IO::Pipe does IO::Streamable does IO::Readable does IO::Writable { - ... - } - -Will need to set IO::Readable.isReadable and IO::Writable.isWriteable depending on opening -method. - -=over - -=item close() - -If the file handle came from a piped open, C<close> will additionally -return C<Failure> (aliased to C<$!>) if one of the other system calls involved fails, or if the -program exits with non-zero status. The exception object will contain any -pertinent information. Closing a pipe -also waits for the process executing on the pipe to complete, in case you -want to look at the output of the pipe afterwards, and -implicitly puts the exit status value into the C<Failure> object if necessary. - -=item IO::Pipe.to - - method to(Str $command, *%opts --> Bool) - method to(Str *@command, *%opts --> Bool) - -Opens a one-way pipe writing to C<$command>. C<IO> redirection for -stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO> redirection -is done with feed operators. XXX how to specify "2>&1"? - -=item IO::Pipe.from - - method from(Str $command, *%opts --> Bool) - method from(Str *@command, *%opts --> Bool) - -Opens a one-way pipe reading from $command. C<IO> redirection for -stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO> redirection -is done with feed operators. XXX how to specify "2>&1"? - -=item IO::Pipe.pair - - method pair(--> List of IO::Pipe) - -A wrapper for I<pipe(2)>, returns a pair of C<IO> objects representing the -reader and writer ends of the pipe. - - ($r, $w) = IO::Pipe.pair; - -=back - -=head2 OS-specific classes - -=head3 Unix - -=head3 Path::Unix - -=over - -=item chown - - multi chown ($uid = -1, $gid = -1, *@files --> Int) - -Changes the owner (and group) of a list of files. The first -two elements of the list must be the numeric uid and gid, in -that order. A value of -1 in either position is interpreted by -most systems to leave that value unchanged. Returns the number -of files successfully changed. - - $count = chown $uid, $gid, 'foo', 'bar'; - chown $uid, $gid, @filenames; - -On systems that support C<fchown>, you might pass file handles -among the files. On systems that don't support C<fchown>, passing -file handles produces a fatal error at run time. - -Here's an example that looks up nonnumeric uids in the passwd -file: - - $user = prompt "User: "; - $pattern = prompt "Files: "; - - ($login,$pass,$uid,$gid) = getpwnam($user) - or die "$user not in passwd file"; - - @ary = glob($pattern); # expand filenames - chown $uid, $gid, @ary; - -On most systems, you are not allowed to change the ownership of -the file unless you're the superuser, although you should be -able to change the group to any of your secondary groups. On -insecure systems, these restrictions may be relaxed, but this -is not a portable assumption. On POSIX systems, you can detect -this condition this way: - - use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); - $can-chown-giveaway = not sysconf(_PC_CHOWN_RESTRICTED); - -=item chmod LIST -X<chmod> X<permission> X<mode> - -Changes the permissions of a list of files. The first element of the -list must be the numerical mode, which should probably be an octal -number, and which definitely should I<not> be a string of octal digits: -C<0o644> is okay, C<0644> is not. Returns the number of files -successfully changed. - - $count = chmod 0o755, 'foo', 'bar'; - chmod 0o755, @executables; - $mode = '0644'; chmod $mode, 'foo'; # !!! sets mode to --w----r-T - $mode = '0o644'; chmod $mode, 'foo'; # this is better - $mode = 0o644; chmod $mode, 'foo'; # this is best - -=item stat - -=item IO.stat - - $node.stat(Bool :$link); # :link does an lstat instead - -Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates -to true, and additional file tests may be performed on the value. If -the stat fails, all subsequent tests on the stat buffer also evaluate -to false. - -=back - -=head3 IO::Socket::Unix - - role IO::Socket::Unix does IO::Socket { - has Str $.RemoteAddr, # Remote Address - has Str $.LocalAddr, # Local Address - } - -=over - -=item new - - method new( - Str :$RemoteAddr, - Str :$LocalAddr, - - Bool :$Listener, # Passed to IO::Socket.new() - - Bool :$Blocking, # Passed to IO::Streamable.new() - Bool :$NoOpen, # Passed to IO::Streamable.new() - - --> IO::Socket::Unix - ) {...} - -=item pair - - method pair(Int $domain, Int $type, Int $protocol --> List of IO) - -A wrapper for I<socketpair(2)>, returns a pair of C<IO> objects representing the -reader and writer ends of the socket. - - use IO::Socket; - ($r, $w) = IO::Socket::Unix.pair(AF_UNIX, SOCK_STREAM, PF_UNSPEC); - - -=back - - -=head3 IO::POSIX - -Indicates that this object can perform standard posix C<IO> -operations. It implies C<IO::Readable> and C<IO::Writeable>. - -=over - -=item method dup( --> IO) - -=item has Bool $.blocking is rw - -=item method flock(:$r,:$w --> Bool) - -=item method funlock( --> Bool) - -=item ... - -=back - -=head1 Unfilled - -=over 4 - -=item IO.ioctl - -Available only as a handle method. - -=item alarm - -=item prompt - - multi prompt (Str $prompt --> Str) - -Should there be an IO::Interactive role? - -=item Str.readpipe - -=item sysopen - -=item IO.sysseek - -=item umask - -=back - -=head1 Removed functions - -=over - -=item IO.eof - -Gone, see eoi C<IO::Seekable>. - -=item IO.fileno - -See C<IO::Handle>. - -=item /(get|set)(host|net|proto|serv|sock).*/ - -Should be implemented by an external library. - -=item lstat - -Use C<stat> with the C<:link> option. - -=item IO.name - -Changed to C<.path>, but we haven't gotten around to specifying this on all of them. - -The C<.name> method returns the name of the file/socket/uri the handle -was opened with, if known. Returns Nil otherwise. There is no -corresponding C<name()> function. - -=item pipe - -Gone, see Pipe.pair - -=item select(both) - -Gone. (Note: for sub-second sleep, just use sleep with a fractional argument.) - -=item IO.shutdown() - -Gone, see C<IO::Socket.close()>, C<$IO::Readable.isReadable>, and C<$IO::Writeable.isWriteable> - -=item socketpair - -Gone, see Socket.pair - -=item IO.sysread - -Gone, see C<IO::Readable.read()>. - -=item IO.syswrite - -Gone, see C<IO::Writeable.read()>. - -=item utime - -Gone, see C<Path.times>. - -=back - -=head2 IO::Buffered - -Indicates that this object performs buffering. The management of the -buffer is completely implementation specific. - -=over - -=item method flush( --> Bool) - -Flushes the buffers associated with this object. - -=item method autoflush( --> Bool) is rw - -Forces this object to keep its buffers empty - -If set to nonzero, forces a flush right away and after every write -or print on the currently selected output channel. -Default is 0 (regardless of whether the channel is really buffered -by the system or not; -C<$OUT_FH.autoflush> tells you only whether you've asked Perl -explicitly to flush after each write). -C<$*OUT> will typically be line buffered if output is to the -terminal and block buffered otherwise. -Setting this variable is useful primarily when you are -outputting to a pipe or socket, -such as when you are running a Perl program under rsh -and want to see the output as it's happening. -This has no effect on input buffering. - - -=back - -=head2 IO::Streamable - -This role represents objects that depend on some external resource, -which means that data might not be available at request. - - role IO::Streamable does IO {...} - -=over - -=item new() - - method new( - Bool :$NoOpen, - Bool :$Blocking, - --> IO::Streamable - ) {...} - -Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is -created. - -If blocking is passed in, .blocking() is called (see below). - -=item method blocking( --> Bool) is rw - -This allows the user to control whether this object should do a -blocking wait or immediately return in the case of not having data -available. - -=item uri - - method uri(Str $uri --> IO::Streamable) {...} - -This should be callable on the class, and act like a kind of "new()" function. When given -a URI, it returns an C<IO::Streamable> of the appropriate type, and throws an error when an -inappropriate type is passed in. For example, calling C<IO::File.uri('http://....')> will -throw an error (but will suggest using just uri('http://...') instead). - -=back - -=head2 IO::Encoded - -This is a generic role for encoded data streams. - -=over - -=item method encoding( --> Str) is rw - -=item method locale( --> Str) is rw - -Encoding and locale are required for sane conversions. - -=back - -=head2 IO::Readable::Encoded - -This role provides encoded access to a readable data stream, implies -C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement. - -=over 4 - -=item uri -X<uri>X<ftp>X<http> - - method uri(Str $uri --> IO::Streamable); - sub uri(Str $uri --> IO::Streamable); - -Returns an appropriate C<IO::Streamable> descendant, with the type depending on the uri -passed in. Here are some example mappings: - - URI type IO type - ======== ======= - file: IO::Path - ftp: IO::Socket::INET (data channel) - http: IO::Socket::INET - -These can naturally be overridden or added to by other modules. - -=item %*PROTOCOLS dynamic variable - -For each protocol, stores a type name that should be instantiated by calling the C<uri> -constructor on that type, and passing in the appropriate uri. - -=back - -=head1 AUTHORS - - The authors of the related Perl 5 docs - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Daniel Ruoso <daniel@ruoso.com> - Lyle Hopkins <webmaster@cosmicperl.com> - Brent Laabs <bslaabs@gmail.com> - Tobias Leich <email@froggs.de> - -=for vim:set expandtab sw=4: diff --git a/S32-setting-library/IO.pod b/S32-setting-library/IO.pod deleted file mode 100644 index 107743fc..00000000 --- a/S32-setting-library/IO.pod +++ /dev/null @@ -1,1784 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 32: Setting Library - IO - -=head1 VERSION - - Created: 19 Feb 2009 - - Last Modified: 28 Oct 2014 - Version: 27 - -=head1 Overview - -This synopsis describes in depth the subroutines and methods that were -described broadly in S16. Please note that any implementation is free -to use multi-method dispatch on both subroutines as well as methods should -this increase the performance or maintainability. - -=head1 Functions - -=head2 print() -X<print()> - - sub print(*@text --> Bool) is export - -Print the given text on C<$*OUT>. - -=head2 say() -X<say()> - - sub say(*@text --> Bool) is export - -Print the given text, followed by a new line C<"\n"> on C<$*OUT>. Before -printing, call the C<.gist> method on any non-C<Str> objects. - -=head2 note() -X<note()> - - sub note(*@text --> Bool) is export - -Print the given text, followed by a new line C<"\n"> on C<$*ERR>. Before -printing, call the C<.gist> method on any non-C<Str> objects. - -=head2 dd() -X<dd()> - - sub dd(@vars --> Bool) is export - -Tiny Data Dumper. Takes the C<variables> specified and C<note>s them (on -C<$*ERR>) in an easy to read format, along with the C<name> of the variable. -So: - - my $a = 42; - dd($a); # notes "$a = 42" - -=head2 prompt() -X<prompt()> - - sub prompt($msg --> Bool) is export - -Simple Prompter. Print message on C<$*OUT> and obtains a single line of -input from C<$*IN>. - -=head2 open() -X<open()> - - sub open ($name as IO, - # mode - Bool :$r = True, - Bool :$w = False, - Bool :$rw = False, - Bool :$a = False, - # encoding - Bool :$bin = False, - Str :$enc = "Unicode", # utf-8 unless otherwise - # newlines - Any :$nl = "EOL", - Bool :$chomp = True, - --> IO::Handle ) is export - -A convenience function for opening normal files as text (by default) as -specified by its (first) parameter. It returns an instantiated L</IO::Handle> -object. The following named parameters may also be specified: - -=over 4 - -=item :r - -Open file for reading. Default is C<True>. - -=item :w - -Open file for writing by creating an empty file with the given name. The -original contents of an existing file with that name, will be B<lost>. -Default is C<False>. - -=item :rw - -Open file for reading and writing with the given name. The original contents -of an existing file with that name, will be B<lost>. Default is C<False>. - -=item :a - -Open file for appending, create one if it didn't exist yet. This may or may -not inhibit overwriting the original contents when moving the file pointer. -Default is C<False>. - -=item :bin - -Open file in binary mode (byte mode). A file opened with C<:bin> may still be -processed line-by-line, but IO will be in terms of C<Buf> rather than C<Str> -types. Default is C<False>, implying text semantics. - -=item :enc - -Encoding to use if opened in text mode. Defaults to "Unicode", which -implies figuring out which actual UTF is -in use, either from a BOM or other heuristics. If heuristics are -inconclusive, UTF-8 will be assumed. (No 8-bit encoding will ever -be picked implicitly.) - -=item :nl - -The marker used to indicate the end of a line of text. Only used in text -mode. Defaults to "EOL", which implies accepting any combination of C<"\n">, -C<"\r\n"> or C<"\r"> or any other Unicode character that has the C<Zl> -(Separator, Line) property. - -=item :chomp - -Whether or not to remove new line characters from text obtained with -C<.lines> and C<.get>. Defaults to C<True>. - -=back - -=head2 dir() -X<dir()> - - sub dir($directory as Str = $*CWD, - Mu :$test = $*SPEC.curupdir, - Bool :$absolute = False, - Bool :$Str = False, - IO::Path :$CWD = $*CWD, - --> List ) is export - -Returns a lazy list of (relative) paths in the C<$directory> as C<IO::Path> -objects, by default from the directory pointed to by C<$*CWD>. If dir() fails, -it returns an L<X::IO::Dir|S32::Exception/X::IO::Dir> failure. The following -named parameters are optional: - -=over 4 - -=item :test - -Expression against which to smart-match for inclusion in result list. By -default excludes C<curdir> (usually ".") and C<updir> (usually "..") only. - -=item :absolute - -Boolean indicating to return absolute path names, rather than relative ones. -False by default. - -=item :Str - -Boolean indicating to return C<Str>ings, rather than C<IO::Path> objects. -False by default. - -=item :CWD - -Only important if C<:absolute> is specified with a True value. The directory -to pre-pend to the relative file paths. Defaults to C<$*CWD>. - -=back - -=head2 slurp() -X<slurp()> - - sub slurp ($what = $*ARGFILES, - Bool :$bin = False, - Str :$enc = "Unicode", - --> Str|Buf ) is export - -Slurps the contents of the entire file into a C<Str> (or C<Buf> if C<:bin>). -Accepts C<:bin> and C<:enc> optional named parameters, with the same meaning -as L</open()>. The routine will C<fail> if the file does not exist, or is a -directory. - -=head2 spurt() -X<spurt()> - - sub spurt ($where, $what, - Str :$enc = $*ENC, - Bool :append = False, - Bool :$createonly = False, - --> Bool ) is export - -Writes the indicated contents (2nd positional parameter) to the location -indicated by the first positional parameter (which can either be a string, -an C<IO::Path> object, or an already opened C<IO::Handle> object). - -If a file needs to be opened for writing, it will also be C<close>d. Returns -True on success, or the appropriate C<Failure> if something went wrong. - -These named parameters are optional and only have meaning if the first -positional parameter was B<not> an C<IO::Handle>: - -=over 4 - -=item :enc - -The encoding with which the contents will be written. [conjectural] - -=item :append - -Boolean indicating whether to append to a (potentially) existing file. If -the file did not exist yet, it will be created. Defaults to C<False>. - -=item :createonly - -Boolean indicating whether to fail if the file already exists. Defaults to -C<False>. - -=back - -=head2 mkdir() -X<mkdir()> - - sub mkdir($dir as IO, $mode = 0o777 --> Bool) is export - -Creates the directory as indicated by the positional parameter. Returns -C<True> on success or an appropriate C<Failure>. - -=head2 rmdir() -X<rmdir()> - - sub rmdir($dir as IO --> Bool) is export - -Removes the (empty) directory as indicated by the positional parameter. -Returns C<True> on success or an appropriate C<Failure>. - -=head2 chdir() -X<chdir()> - - sub chdir($dir as IO, $CWD = $*CWD, - :$test = <d r> - --> Bool) is export - -Changes the current working directory to the given directory, for the scope in -which C<$*CWD> is active (if no second positional parameter is given) or for -the scope of the indicated localized C<$*CWD>. A typical use case: - - { - chdir("foo", my $*CWD); - # working directory changed to "foo" - } - # restored to what it was - -Returns C<True> if successful, or an appropriate C<Failure>, e.g if the -directory does not exist, or is not a directory, or is not readable. - -Please note that this directory has B<no> connection with whatever the -operating system thinks is the current working directory. The value of -C<$*CWD> just will always be prepended to any relative paths in any file -operation in Perl 6. - -Also note that you can use C<chdir> to set similar dynamic variables, like -C<$*TMPDIR> and C<$*HOME> this way: - - chdir("bar", my $*TMPDIR); # set $*TMPDIR in this scope - chdir("bar", my $*HOME); # set $*HOME in this scope - -=head2 copy() -X<copy()> - - sub copy ($source as IO, $dest as IO, - :$createonly = False, - --> Bool ) is export - -Copies a file, as indicated by the first positional parameter, to the -destination specified. If :createonly is set to True, copy fails if a file -already exists in the destination. Returns C<True> upon success, or an -appropriate C<Failure> if the operation could not be completed. - -=head2 rename() -X<rename()> - - sub rename ($source as IO, $dest as IO, - :$createonly = False, - --> Bool ) is export - -Moves a file, as indicated by the first positional parameter, by renaming it -to the destination specified. If :createonly is set to True, the rename fails -if a file already exists in the destination. Returns C<True> upon success, or -an appropriate C<Failure> if the operation could not be completed. - -Please use L</move()> if a file could not be moved by renaming (usually because -the destination is on a different physical storage device). - -=head2 move() -X<move()> - - sub move ($source as IO, $dest as IO, - :$createonly = False, - --> Bool ) is export - -Moves a file, as indicated by the first positional parameter, by copying its -contents to the destination specified, and then removing the file at the -original location. If :createonly is set to True, the move fails if a file -already exists in the destination. Returns C<True> upon success, or an -appropriate C<Failure> if the operation could not be completed. - -Please use L</rename()> if a file can be moved by renaming (which is usually -possible if the destination is on the same different physical storage device). -Alternately, the C<move()> function is free to try the C<rename()> first, -and if that (silently) fails, do it the hard way. - -=head2 unlink() -X<unlink()> - - sub unlink(*@files --> @removed) is export - -Delete all specified ordinary files, links, or symbolic links. Returns the -names of the files that were successfully deleted. - -=head3 chmod() -X<chmod()> - - sub chmod($permission, *@files --> @changed) is export - -Changes the permissions of a list of files. The first element of the -list must be the numerical mode, which should probably be an octal -number, and which definitely should I<not> be a string of octal digits: -C<0o644> is okay, C<0644> is not. Returns the names of the files that were -successfully changed. - - $count = chmod 0o755, 'foo', 'bar'; - chmod 0o755, @executables; - $mode = '0644'; chmod $mode, 'foo'; # BAD!!! sets mode to --w----r-T - $mode = '0o644'; chmod $mode, 'foo'; # this is better - $mode = 0o644 ; chmod $mode, 'foo'; # this is best - -=head2 link() -X<link()> - - sub link($target, $source --> Bool) is export - -Create a hard link between the target from the given source path. Returns -C<True> if successful, or an appropriate C<Failure>. - -=head2 symlink() -X<symlink()> - - sub symlink($target, $source --> Bool) is export - -Create a symbolic link between the target from the given source path. Returns -C<True> if successful, or an appropriate C<Failure>. - -=head1 IO Types - -=head2 IO - - role IO { }; - -The base role only tags that this is an C<IO> object for more generic -purposes. It doesn't specify any methods or attributes. - -=head2 IO::Spec - -This class is a collection of methods dealing with file specifications -(commonly known as file names, though it can include the entire directory path). -Most of the methods allow access to lower-level operations on file path strings. - -These operations are significantly different on some operating systems, so the -actual work is being done by subclasses such as C<IO::Spec::Unix>, -C<IO::Spec::Win32> and C<IO::Spec::Cygwin>. - -The correct C<IO::Spec> class for your system, is available in the C<$*SPEC> -dynamic variable. So typically, you would call methods on that: - - my $cleanpath = $*SPEC.canonpath("a/.//b/") # gives "a/b" - -This set of modules was inspired by Perl 5's C<File::Spec>. An implementation -may choose to inherit from C<IO::Spec>, or any of its subclasses, if that -helps in avoiding code duplication. - -The C<select> method is the only method provided by C<IO::Spec> itself. - -=head3 .select -X<.select> - - method select(IO::Spec:U: $name = $*DISTRO.name as Str --> IO::Spec:U) - -The C<.select> method takes an optional argument: a string indicating the -type of system for which to perform file specification operations. By -default, it takes C<$*DISTRO.name>. - -At startup, C<$*SPEC> is initialized to C<IO::Spec.select>. - -=head2 IO::Spec subclasses - -The following methods should be provided by the C<IO::Spec> subclasses, or -may be inherited from another class. They will never check anything with -an actual file system. In alphabetical order: - -=head3 .abs2rel -X<.abs2rel> - - method abs2rel($path as Str, $base = $*CWD --> Str) - -Takes a path and an optional base path (default C<$*CWD>) and returns a -relative path from the base path to the destination path. If the base path -is relative, then it will first be transformed to an absolute path with -L</.rel2abs>, relative to C<$*CWD>. - -On systems with the concept of volume, if C<$path> and C<$base> appear to be -on two different volumes, it will not attempt to resolve the two paths, and -will instead simply return C<$path>. - -On systems that have a grammar that indicates filenames, this ignores the -C<$base> filename as well. Otherwise all path components are assumed to be -directories. - -If C<$path> is relative, it is first converted to absolute form using -L</.rel2abs>. This means that it is taken to be relative to C<$*CWD>. - -=head3 .canonpath -X<.canonpath> - - method canonpath($path as Str --> Str) - -Perform a logical cleanup of a path and returns that. Note that this does -*not* collapse F<x/../y> sections into F<y>. This is by design. If F</foo> -on your system is a symlink to F</bar/baz>, then F</foo/../quux> is actually -F</bar/quux>, not F</quux> as a naive F<../>-removal would give you. If you -want to do this kind of processing, you probably want L</IO::Path>'s -L</.resolve> method to actually traverse the filesystem cleaning up paths -like this. - -=head3 .catdir -X<.catdir> - - method catdir(*@dir as Array[Str] --> Str) - -Concatenate two or more directory names to form a complete path ending -with a directory. Removes any trailing slashes from the resulting -string, unless the result is the L</.rootdir>. - -=head3 .catpath -X<.catpath> - - method catpath($volume, $dir, $file --> Str) - -Takes volume, directory and file portions and returns an entire path string. -Under Unix, C<$volume> is ignored, and directory and file are concatenated. -On other OSes, C<$volume> is significant. Directory separators like slashes -are inserted if need be. - -=head3 .contents -X<.contents> - -=head3 .curdir -X<.curdir> - - method curdir(--> Str) - -Returns a string representation of the current directory (Usually C<".">). - -=head3 curupdir - -Returns a test as to whether a given path is identical to the current -directory (as indicated by L</.curdir>) or the parent directory (as indicated -by L</.updir>. This is usually C<< none(<. ..>) >>. It is the default for -the C<:test> parameter to C</dir()> and L</IO::Path>'s L</.contents> method. -It can also be used to extend C<dir()> through its C<:test> named parameter: - - dir "my/directory", test => all($*SPEC.curupdir, /^ '.' /); - -This example would return all files beginning with a period that are -not C<"."> or C<".."> directories. - -=head3 .devnull -X<.devnull> - - method devnull(--> Str) - -Returns a string representation of the null device (e.g. C<"/dev/null"> on -Unix-like systems). - -=head3 .extension -X<.extension> - - method extension($path as Str --> Str) - -Returns the extension (if any) of the given path. - -=head3 .is-absolute -X<.is-absolute> - - method is-absolute($path as Str --> Bool) - -Takes as its argument a path, and returns C<True> if it is an absolute path, -C<False> otherwise. For C<IO::Spec::Win32>, it returns 1 if it's an absolute -path without a volume, and 2 if it's absolute with a volume. - -=head3 .join -X<.join> - - method join(:$volume, $dir, $file --> Str) - -A close relative of L</.catpath>, this method takes volume, directory and -basename portions and returns an entire path string. If a directory is B<".">, -it is removed from the (relative) path output, because this function inverts -the functionality of dirname and basename. - -Directory separators are inserted if necessary. Under Unix, $volume is -ignored, and only directory and basename are concatenated. On other OSes, -$volume is significant. - -This method is the inverse of L</.split>; the results can be passed to it -to get the volume, dirname, and basename portions back. - -=head3 .PATH -X<.PATH> - - method PATH($PATH = %*ENV<PATH> --> List[Str]) - -Convert a string formatted like a system's C<PATH> specification, and returns -it as a list of strings. Takes C<< %*ENVE<lt>PATHE<gt> >> by default. - -=head3 .rel2abs -X<.rel2abs> - - method rel2abs($path as Str, $base = $*CWD as Str --> Str) - -Converts a relative path to an absolute path, using an optional base directory. -If the base directory is not specified, C<$*CWD> will be assumed. - -If C<$base> is relative, then it is first converted to absolute form, relative -to C<$*CWD>. - -On systems with the concept of volume, if C<$path> and C<$base> appear to be -on two different volumes, t will not attempt to resolve the two paths, and -will instead simply return C<$path>. - -On systems that have a grammar that indicates filenames (like VMS), this -ignores the C<$base> specification as well. Otherwise all path components are -assumed to be directories. - -If C<$path> is absolute, it is cleaned up and returned using L</.canonpath>. - -=head3 .rootdir -X<.rootdir> - - method rootdir(--> Str) - -Returns a string representation of the root directory (usually C<"/">). - -=head3 .split -X<.split> - - method split($path as Str --> Hash[Str]) - -A close relative of L</.splitdir>, this function also splits a path into -volume, directory, and basename portions. Unlike L</.splitdir>, split returns -paths compatible with dirname and basename I<and> returns it arguments as -a hash of C<volume>, C<directory>, and C<basename>. - -This means that trailing slashes will be eliminated from the directory -and basename components, in Win32 and Unix-like environments. The basename -component will always contain the last part of the path, even if it is a -directory, C<'.'>, or C<'..'>. If a relative path's directory portion would -otherwise be empty, the directory is set to whatever C<curdir> is. - -On systems with no concept of volume, returns C<''> (the empty string) for -volume. The results can be passed to L</.join> to get back a path equivalent -to (but not necessarily identical to) the original path. If you want to keep -all of the characters involved, use L</.splitdir> instead. - -=head3 .splitdir -X<.splitdir> - - method splitdir($directories as Str --> List[Str]) - -The opposite of L</.catdir>. C<$directories> must be only the directory -portion of the path on systems that have the concept of a volume or that have -path syntax that differentiates files from directories. - -Unlike just splitting the directories on the separator, empty directory names -(C<''>) can be returned, because these are significant on some OSes. - -=head3 .splitpath -X<.splitpath> - - method splitpath( $path, $nofile = False ) - -Splits a path in to volume, directory, and filename portions and returns these -as a List. On systems with no concept of volume, returns '' for volume. - - my ($volume,$directories,$file) = $*SPEC.splitpath( $path ); - my ($volume,$directories,$file) = $*SPEC.splitpath( $path, $no_file ); - -For systems with no syntax differentiating filenames from directories, -assumes that the last file is a path unless C<$no_file> is C<True> or a -trailing separator or F</.> or F</..> is present. On Unix, this means that -C<$no_file> true makes this return ( '', $path, '' ). - -The directory portion may or may not be returned with a trailing '/'. - -The results can be passed to L</.catpath> to get back a path equivalent to -(but not necessarily identical to) the original path. - -=head3 .tmpdir -X<.tmpdir> - - method tmpdir(--> IO::Path) - -Returns an L</IO::Path> representation of the first writable directory from an -implicit list of possible temporary directories. Returns the current directory -if no writable temporary directories are found. The list of directories -checked depends on the platform. - -=head3 .updir -X<.updir> - - method updir(--> Str) - -Returns a string representation of the parent directory (usually C<"..">). - -=head3 Comparison of .splitpath and .split - - OS Path splitpath split - Unix /a/b/c ("", "/a/b/", "c") ("", "/a/b", "c") - Unix /a/b//c/ ("", "/a/b//c/", "") ("", "/a/b", "c") - Unix /a/b/. ("", "/a/b/.", "") ("", "/a/b", ".") - Win32 C:\a\b\ ("C:", "\\a\\b\\", "") ("C:", "\\a", "b") - VMS A:[b.c] ("A:", "[b.c]", "") ("A:", "[b]", "[c]") - -* The VMS section is still speculative, and not yet supported. - -=head3 Comparison of .catpath and .join - - OS Components catpath join - Unix ("", "/a/b", "c") /a/b/c /a/b/c - Unix ("", ".", "foo") ./foo foo - Unix ("", "/", "/") // / - Win32 ("C:", "\a", "b") C:\a\b C:\a\b - VMS ("A:", "[b]", "[c]") A:[b][c] A:[b.c] - -* The VMS section is still speculative, and not yet supported. - -=head2 IO::Path - - class IO::Path is Cool { } - -Holds a path of a file or directory. The path is generally divided -into three parts, the I<volume>, I<dirname> and I<base name>. - -On Windows, the volume is a drive letter like C<C:>, or a UNC network volume -like C<\\share\>. On UNIX-based systems, the volume part is empty. - -The basename is name of the file or directory that the C<IO::Path> object -represents, and the directory is the part of the path leading up to the -basename. - - path volume dirname basename - /usr/bin/gvim /usr/bin gvim - /usr/bin/ /usr bin - foo/bar.txt foo bar.txt - C:\temp\f.txt C: \temp f.txt - \\server\share\a \\server\share \ a - -By default, C<IO::Path> uses the C<IO::Spec> setting as found in C<$*SPEC> -when the object is created. If you want to work paths as if you were using -another OS, you can specify another C<IO::Spec> subclass with the optional -C<:SPEC> named parameter. - -There are several ways of creating an C<IO::Path>. The easiest way is to use -C<.IO> coercer: - - my $io = "foo/bar".IO; - -Of course, you can always call the C<.new> method as well: - - my $io = IO::Path.new( $full-path ); - my $io = IO::Path.new( :$volume, :$dirname, :$basename); - -Whenever a new C<IO::Path> is created, an internal absolute and cleaned version -of the specified path is stored, using the implicitly or explicitly -specified values for C<$*SPEC> and C<$*CWD>: - - my $io = IO::Path.new( "foo", :SPEC<win32>, :CWD</usr/local/src> ); - -would create an C<IO::Path> object with C<IO::Spec::Win32> semantics, with an -absolute path of C</usr/local/src/foo>. Yes, that would be strange, but it -B<is> possible. A shorter way would be: - - my $io = "foo".IO( :SPEC<win32>, :CWD</usr/local/src> ); - -The (implicit) value of C<:CWD> is only used for creating the absolute path -at instantiation time. The (implicit) value of C<:SPEC> is actually saved -in the object to be able to perform path operations with the correct semantics -at a later time. - -=head3 File test methods - -The following (single letter) methods can be used on the C<IO::Path> object: - - M Test performed Returns - = ============== ======= - r Path is readable by effective uid/gid. Bool - w Path is writable by effective uid/gid. Bool - x Path is executable by effective uid/gid. Bool - o Path is owned by effective uid. Bool - - R Path is readable by real uid/gid. Bool - W Path is writable by real uid/gid. Bool - X Path is executable by real uid/gid. Bool - O Path is owned by real uid. Bool - - e Path exists. Bool - s Size of the path in bytes. Int - z Path has zero size (an empty file). Bool - - f Path is a plain file. Bool - d Path is a directory. Bool - l Path is a symbolic link. Bool - L Actual path of symbolic link (readlink) Str - p Path is a named pipe (FIFO) Bool - S Path is a socket. Bool - b Path is a block special file. Bool - c Path is a character special file. Bool - - u Path has setuid bit set. Bool - g Path has setgid bit set. Bool - k Path has sticky bit set. Bool - -To allow for easy chaining of file tests, there is an C<.all> method that can -be fed the tests to be tried as a C<List> of strings. The value returned -will be the first non-True value, or the final True value. - - say "rwx" if $io.all: <r w x>; - - if $io.all(<f r w x s>) -> $size { - say "plain file with rwx of $size bytes"; - } - -For convenience, you can also specify the negated letter for the opposite test: - - if $io.all(<!d r w x s>) -> $size { - say "not a directory with rwx of $size bytes"; - } - -Other methods are listed here in alphabetical order: - -=head3 .absolute -X<.absolute> - - method absolute($base as Str --> Str) - -The absolute path of the path, optionally from the relative base. - -=head3 .accessed -X<.accessed> - - method accessed(--> Instant) - -Returns the C<Instant> when the file was last accessed, or C<Failure> if -this could not be determined. - -=head3 .basename -X<.basename> - - method basename(--> Str) - -Returns the base name part of the path -- that is, the last portion. Functions -equivalently to the C<basename> shell program on Unix-like systems. - -=head3 .changed -X<.changed> - - method changed(--> Instant) - -Returns the C<Instant> when the metadata of the file was last changed, or -C<Failure> if this could not be determined. - -=head3 .chdir -X<.chdir> - - method chdir(:$CWD = $*CWD --> Bool) - -Like L</chdir()>, but with L</.absolute> as the first parameter. - -=head3 .child -X<.child> - - method child($childname --> IO::Path) - -Appends C<$childname> to the end of the path, adding path separators where -needed and returns the result as a new C<IO::Path>. - -=head3 .chmod -X<.chmod> - - method chmod($permissions --> Bool) - -Like L</chmod()>, but with L</.absolute> as the second parameter. - -=head3 .copy -X<.copy> - - method copy($dest, :$createonly --> Bool) - -Like L</copy()>, but with L</.absolute> as the first parameter. - -=head3 .dir -X<.dir> - - method dir(:$test, :$absolute, :$CWD --> List[Str]) - -Like L</dir()>, but with L</.absolute> as the first parameter. - -=head3 .dirname -X<.dirname> - - method dirname(-->Str) - -Returns the directory part of the path, not including the last item. Functions -equivalently to the C<dirname> shell program on Unix-like systems. - -=head3 .extension -X<.extension> - - method extension(--> Str) - -Returns the extension of the path, if any. - -=head3 .IO -X<.IO> - - method IO(--> IO::Path) - -Returns itself. - -=head3 .is-absolute -X<.is-absolute> - - method is-absolute(--> Bool) - -Always returns C<True> since internally the path is always stored as an -absolute path. - -=head3 .is-relative -X<.is-relative> - - method is-relative(--> Bool) - -Always returns C<False> since internally the path is always stored as an -absolute path. - -=head3 .lines -X<.lines> - - method lines( --> List[Str] ) - -Returns a (lazy) list of lines of which the file consists, or a C<Failure> -if something went wrong. - -=head3 .mkdir -X<.mkdir> - - method mkdir($mode = 0o777 --> Bool) - -Like L</mkdir()>, but with L</.absolute> as the first parameter. - -=head3 .modified -X<.modified> - - method modified(--> Instant) - -Returns the C<Instant> when the contents of the file were last modified, or -C<Failure> if this could not be determined. - -=head3 .move -X<.move> - - method move($dest as IO, :$createonly --> Bool) - -Like L</move()>, but with L</.absolute> as the first parameter. - -=head3 .open -X<.open> - - method open(... --> IO::Handle) - -Like L</open()>, but with L</.absolute> as the first parameter. - -=head3 .parent -X<.parent> - - method parent(--> IO::Path) - -Removes last portion of the path and returns the result as a new C<IO::Path>. - -=head3 .pred -X<.pred> - - method pred(--> IO::Path) - -Create previous logical path and return the result as a new C<IO::Path> or -returns C<Failure> if that is not possible. - -=head3 .relative -X<.relative> - - method relative ($base as Str = $*CWD --> IO::Path) - -Transforms the path into an relative form, and returns the result as a new -C<IO::Path>. If C<$base> is supplied, transforms it relative to that base -directory, otherwise the C<$*CWD>is used. Paths that are already relative -are returned unchanged. - -=head3 .rename -X<.rename> - - method rename($dest as IO, :$createonly --> Bool) - -Like L</rename()>, but with L</.absolute> as the first parameter. - -=head3 .resolve -X<.resolve> - - method resolve(--> IO::Path) - -Returns a new IO::Path object with all symbolic links and references to the -parent directory (C<..>) are physically resolved. This means that the -filesystem is examined for each directory in the path, and any symlinks found -are followed. - - # bar is a symlink pointing to "/baz" - my $io = "foo/./bar/..".IO.resolve; # now "/" (the parent of "/baz") - -=head3 .rmdir - - method rmdir(--> Bool) - -Removes (deletes) the directory represented by the C<IO::Path>. Returns -C<True> if successful, or a C<Failure> of some kind if not. Typically fails -if the path is not a directory or the directory is not empty. - -=head3 .slurp -X<.slurp> - - method slurp(:$bin, :$enc --> Str|Buf) - -Like L</slurp()>, but with L</.absolute> as the first parameter. - -=head3 .SPEC -X<.SPEC> - - method SPEC(--> IO::Spec) - -Returns the L</IO::Spec> object that was (implicitely) specified at object -creation time. - -=head3 .spurt -X<.spurt> - - method spurt(:$enc, :$append, :$createonly, :$bin --> Str|Buf) - -Like L</spurt()>, but with L</.absolute> as the first parameter. - -=head3 .succ -X<.succ> - - method succ(--> IO::Path) - -Create next logical path and return the result as a new C<IO::Path>. - -=head3 .unlink - - method unlink(--> Bool) - -Like L</unlink()>, but with L</.absolute> as the first parameter. -Returns C<True> on success or an appropriate C<Failure>. - -=head3 .volume -X<.volume> - - method volume(-->Str) - -Returns the volume part of the path. On Unix-like OSes or systems without a -concept of volume in the path, returns the empty string. - -=head3 .words -X<.words> - - method words( :$nw = "WS" --> List[Str] ) - -Returns a (lazy) list of words of which the file consists, or a C<Failure> -if something went wrong. Also takes the following optional named parameters: - -=over 4 - -=item :nw - -The delimiter between what are to be considered words. By default assumes -C<"WS">, which indicates any whitespace character. - -=back - -=head3 Subclasses - -The C<IO::Path> class may have C<IO::Spec> specific subclasses. But basically, -these would only implicitely specify the C<IO::Class> to be specified for -the C<.new> method: - - class IO::Path::Win32 { - method new(|c) { IO::Path.new(|c, :SPEC(IO::Spec::Win32) } - } - -=head2 IO::Handle - - class IO::Handle does IO { ... } - -A handle of a file, pipe or anything else that supports reading or -writing like a file. - -The C<IO::Handle> object is usually B<not> directly instantiated, but with -L</open()> or L</IO::Path>'sL</.open>. Nonetheless, you B<can> create an -C<IO::Handle> object with just a path: - - my $handle = IO::Handle.new($filename as Str); - my $handle = IO::Handle.new($filename as Str, :SPEC(*$SPEC)); - my $handle = IO::Handle.new($filename as Str, :SPEC(*$SPEC), :CWD($*CWD)); - -This does not interact with anything at all and will appear as if the file -has been C<.close>d. From then on, the C<.path> method will return the -C<IO::Path> object that was created - -The C<.open> method B<does> interact with the file system: - - $handle.open; # same as $handle = $filename.IO.open - -It has the same optional named parameters as L</open()> and either returns -B<itself> (for historical reasons), or a C<Failure> with additional information. - -=head3 Methods handled by .path - -The filename specified with C<.new> is internally stored as an L</IO::Path> -object, obtainable with the C<.path> method. The following methods are handled -by C<.path> and work exactly the same: - - absolute the absolute, canonical path - accessed last access time (if available) - basename the basename of the path - changed last (metadata) changed time - chmod change attributes of path - dirname the directory part of the absolute path - extension the extension of the file - is-absolute is the (original) path absolute - is-relative is the (original) path relative - modified last modified time - relative the relative path against CWD - SPEC the :SPEC at instantiation time - volume the volume of the path (if any) - -The following methods also work the same as with C<IO::Path>, but it may be -less logical to use these on an C<IO::Handle> object as these return new -C<IO::Path> objects. - - child append basename to path - IO same as .path - parent remove last portion of path - pred previous logical path - resolve follow symlinks to the real path - succ next logical path - -These C<IO::Path> methods seem to only make sense if the C<IO::Handle> object -is closed. But there may be some uses for this, but it seems more like extra -rope for shooting yourself in the foot. - - copy create a copy of file - mkdir create directory - move move (rename) to other storage - rename rename (move) to other name - rmdir remove directory if empty directory - unlink remove file - -[Conjecture: perhaps the above methods should fail on IO::Handle] - -Contrary to the C<IO::Path> methods with the same name, these methods operate -only from the current file position. If the file was just opened, it's -identical as with the C<IO::Path> version. But if you have done anything -to the handle that moved the file pointer, you will get a different result. - - lines contents of file as lines - slurp obtain the contents of the file - spurt write / append contents to file - words contents of file as words - -The other methods of C<IO::Handle> are: - -=head3 .close -X<.close> - - method close(--> Bool) - -Closes the handle and returns C<True>, or a C<Failure> if something went wrong. - -=head3 .encoding -X<.encoding> - - method encoding(--> Str) - - method encoding($encoding --> Str) - -Without arguments, simply returns the current encoding used on the handle. -If supplied with a string identifying a valid encoding, change the handle -to read with that encoding from then on. Options include C<binary>, C<utf8>, -and other text encodings. An invalid encoding causes the method to return -a C<Failure>. - -=head3 .eof -X<.eof> - - method eof(--> Bool) - -Returns C<True> if the handle is exhausted, C<False> otherwise. - -=head3 .fileno -X<.fileno> - - method fileno(--> int) - -Returns the file descriptor, which is always a native integer, conforming to -C89. - -=head3 .flush -X</flush> - - method flush(--> Bool) - -Attempts to flush any buffered data, returns C<True> if successful, an -appropriate C<Failure> otherwise. - -=head3 .get -X<.get> - - method get(--> Str) - -Reads the next line and returns it. Uses the (implicit) specification of -C<:nl> with L</open> to determine where a line ends. Returns a C<Str> type -object if no more lines to be read. - -=head3 .getc -X<.getc> - - method getc(Int $chars = 1 --> Str) - -Tries to read C<$chars> characters and return them concatenated as a string. -Returns a C<Str> type object if no more lines to be read. - -=head3 .ins -X<.ins> - - method ins(--> Int) - -Returns the number of lines that have been read with L</.get> or L</.lines>. - -=head3 .opened -X<.opened> - - method opened(--> Bool) - -Return whether the file is opened. - -=head3 .p -X<.p> - - method p(--> Bool) - -Returns whether the handle is opened to a pipe. - -=head3 .print -X<.print> - - method print (*@text --> Bool) - -Stringifies each element, concatenates those strings, and writes the -result to the file. Returns C<True> if successful, a C<Failure> otherwise. - -=head3 .read -X<.read> - - method read(Int $bytes --> Buf) - -Reads and returns C<$bytes> bytes from the handle, or as many as are possible. - -=head3 .say -X<.say> - - method say (*@text --> Bool) - -This is identical to L</.print> except that it stringifies its arguments by -calling C<.gist> on them and auto-appends a newline after the final argument. - -=head3 .seek -X<.seek> - - method seek(Int $position, MoveMethod $whence --> Bool) - -Move the file pointer to C<$position>. The meaning of this position is -always in "bytes", so you better know what you're doing in a text-file. - -The C<$whence> value should be a C<MoveMethod> value, which is one of: - - name value - =========== ===== - FromStart 0 - FromCurrent 1 - FromEnd 2 - -These numerical values will also be accepted. Returns C<True> on success, -or a C<Failure> if something went wrong (e.g. when using C<$*IN> on a terminal -input). - -=head3 .t -X<.t> - - method t(--> Bool) - -Returns C<True> if the handle is opened to a tty, aka there might actually -be a person watching. - -=head3 .tell -X<.tell> - - method tell(--> Int) - -Returns the position of the file pointer in "bytes". - -=head3 .write -X<.write> - - method write(Buf $buf --> Int) - -Tries to write C<$buf> to the file. The actual number of bytes written is -returned, or a C<Failure> if something went wrong. - -=over - -This is "raw" write. C<$buf> contains plain bytes. If you want to C<write> -a C<Str>, you should C<.encode> it first, or use L</.print>. - -=back - -=head1 Here Be Dragons - -Everything below this point hasn't been reviewed properly - -=head2 IO::Socket - - role IO::Socket { - has %.options; - has Bool $.Listener; - ... - } - -Accessing the C<%.options> would on Unix be done with I<getsockopt(2)>/I<setsockopt(2)>. - -The $.Listener attribute indicates whether the socket will be a listening socket when -opened, rather than indicating whether it is currently listening. - -=over - -=item new - - method new( - :$Listener, # initializes $.Listener - ) - -The initial value of the $.Listener attribute is defined according to the following rules: - - * If $Listener is passed to .new(), then that value is used - * If neither a local address nor a remote address are passed in, throw an exception - * If no remote address is passed, then $.Listener is set to SOMAXCONN - * If no local address is used, then $Listener is set to 0 - * If both local and remote addresses are used, throw an exception that asks people to - specify $Listener - -=item open - - method open() - -If $.Listener is true, does a I<bind(2)> and a I<listen(2)>, otherwise does a -I<connect(2)>. - -It's end-user use case is intended for the case where NoOpen is passed to .new(). .new() -itself will presumably also call it. - -=item close - - method close() - -Implements the close() function from IO::Closeable by doing a shutdown on the connection -(see below) with @how set to ('Readable', 'Writeable'). - -=item shutdown - - method shutdown(Str @how) - -Does a I<shutdown(2)> on the connection. See also IO::Readable.isReadable and -IO::Writeable.isWriteable. - -$how can contain 1 or more of the strings 'Readable' and 'Writeable'. - -=item accept - - method accept( --> IO::Socket) - -=item method read(Int $bytes --> Buf) - -Reads and returns C<$bytes> bytes from the handle - -=item method write(Buf $buf --> Int) - -Implements the IO::Writeable interface by doing a I<send(2)>. - -=back - -=head2 IO::Socket::INET - - class IO::Socket::INET does IO::Socket { - has Str $.proto = 'TCP'; - has Str $.host; - has Int $.port; - has Str $.localhost; - has Int $.localport; - ... - } - -=over - -=item new - - multi method new(:$host!, :$port, *%attributes) { ... } - multi method new(:$localhost!, :$localport, :$listen! *%attributes) { ... } - -Creates a new socket and opens it. - -=back - -=head1 Conjectural Stuff - -Everything below this point should be considered as mere ideas for -future evolution, not as things that a compiler write should implement -unquestioningly. - -=head2 IO::ACL - -This is a basic abstraction; for better control, use the operating-system specific -interfaces, over which this is a thin veneer. - - class IO::ACL { - has Str $.type; # "User", "Group", "Everyone", ??? - has Str $.id; # username or groupname; unused for $type eq "Everyone" - has %.permissions; - # Unsupported values may (or may not) throw - # UnsupportedPermission when set or read - has Path $.owningObject; - ... - } - -The permissions used in C<%permissions> are: - -=over - -=item Readable - -Should be supported by all filesystems as an item to read from the hash for the group -"Everyone". - -=item Writeable - -Should be supported by all filesystems as an item to read from the hash for the group -"Everyone". - -=item Executable - -Supported on most Unix systems, anyway. Windows should be able to guess when this is -read, and throw an exception if written to. - -=item Default - -An ACL of User,fred,Default sets the user "fred" to be the owner of the file. This can be -done with groups too. Works on Unix, at least. - -=back - -The C<$.owningObject> attribute of C<ACL> shows what the ACL is set on. On a -Windows system, this can be a parent directory, as permissions are inherited. - - -=head2 IO::Pipe - - class IO::Pipe does IO::Streamable does IO::Readable does IO::Writable { - ... - } - -Will need to set IO::Readable.isReadable and IO::Writable.isWriteable depending on opening -method. - -=over - -=item close() - -If the file handle came from a piped open, C<close> will additionally -return C<Failure> (aliased to C<$!>) if one of the other system calls involved fails, or if the -program exits with non-zero status. The exception object will contain any -pertinent information. Closing a pipe -also waits for the process executing on the pipe to complete, in case you -want to look at the output of the pipe afterwards, and -implicitly puts the exit status value into the C<Failure> object if necessary. - -=item IO::Pipe.to - - method to(Str $command, *%opts --> Bool) - method to(Str *@command, *%opts --> Bool) - -Opens a one-way pipe writing to C<$command>. C<IO> redirection for -stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO> redirection -is done with feed operators. XXX how to specify "2>&1"? - -=item IO::Pipe.from - - method from(Str $command, *%opts --> Bool) - method from(Str *@command, *%opts --> Bool) - -Opens a one-way pipe reading from $command. C<IO> redirection for -stderr is specified with C<:err(IO)> or C<< :err<Str> >>. Other C<IO> redirection -is done with feed operators. XXX how to specify "2>&1"? - -=item IO::Pipe.pair - - method pair(--> List of IO::Pipe) - -A wrapper for I<pipe(2)>, returns a pair of C<IO> objects representing the -reader and writer ends of the pipe. - - ($r, $w) = IO::Pipe.pair; - -=back - -=head2 OS-specific classes - -=head3 Unix - -=head3 Path::Unix - -=over - -=item chown - - multi chown ($uid = -1, $gid = -1, *@files --> Int) - -Changes the owner (and group) of a list of files. The first -two elements of the list must be the numeric uid and gid, in -that order. A value of -1 in either position is interpreted by -most systems to leave that value unchanged. Returns the number -of files successfully changed. - - $count = chown $uid, $gid, 'foo', 'bar'; - chown $uid, $gid, @filenames; - -On systems that support C<fchown>, you might pass file handles -among the files. On systems that don't support C<fchown>, passing -file handles produces a fatal error at run time. - -Here's an example that looks up nonnumeric uids in the passwd -file: - - $user = prompt "User: "; - $pattern = prompt "Files: "; - - ($login,$pass,$uid,$gid) = getpwnam($user) - or die "$user not in passwd file"; - - @ary = glob($pattern); # expand filenames - chown $uid, $gid, @ary; - -On most systems, you are not allowed to change the ownership of -the file unless you're the superuser, although you should be -able to change the group to any of your secondary groups. On -insecure systems, these restrictions may be relaxed, but this -is not a portable assumption. On POSIX systems, you can detect -this condition this way: - - use POSIX qw(sysconf _PC_CHOWN_RESTRICTED); - $can-chown-giveaway = not sysconf(_PC_CHOWN_RESTRICTED); - -=item stat - -=item IO.stat - - $node.stat(Bool :$link); # :link does an lstat instead - -Returns a stat buffer. If the lstat succeeds, the stat buffer evaluates -to true, and additional file tests may be performed on the value. If -the stat fails, all subsequent tests on the stat buffer also evaluate -to false. - -=back - -=head3 IO::Socket::Unix - - role IO::Socket::Unix does IO::Socket { - has Str $.RemoteAddr, # Remote Address - has Str $.LocalAddr, # Local Address - } - -=over - -=item new - - method new( - Str :$RemoteAddr, - Str :$LocalAddr, - - Bool :$Listener, # Passed to IO::Socket.new() - - Bool :$Blocking, # Passed to IO::Streamable.new() - Bool :$NoOpen, # Passed to IO::Streamable.new() - - --> IO::Socket::Unix - ) {...} - -=item pair - - method pair(Int $domain, Int $type, Int $protocol --> List of IO) - -A wrapper for I<socketpair(2)>, returns a pair of C<IO> objects representing the -reader and writer ends of the socket. - - use IO::Socket; - ($r, $w) = IO::Socket::Unix.pair(AF_UNIX, SOCK_STREAM, PF_UNSPEC); - - -=back - - -=head3 IO::POSIX - -Indicates that this object can perform standard posix C<IO> -operations. It implies C<IO::Readable> and C<IO::Writeable>. - -=over - -=item method dup( --> IO) - -=item has Bool $.blocking is rw - -=item method flock(:$r,:$w --> Bool) - -=item method funlock( --> Bool) - -=item ... - -=back - -=head1 Unfilled - -=over 4 - -=item IO.ioctl - -Available only as a handle method. - -=item alarm - -=item prompt - - multi prompt (Str $prompt --> Str) - -Should there be an IO::Interactive role? - -=item Str.readpipe - -=item sysopen - -=item IO.sysseek - -=item umask - -=back - -=head1 Removed functions - -=over - -=item IO.eof - -Gone, see eoi C<IO::Seekable>. - -=item IO.fileno - -See C<IO::Handle>. - -=item /(get|set)(host|net|proto|serv|sock).*/ - -Should be implemented by an external library. - -=item lstat - -Use C<stat> with the C<:link> option. - -=item IO.name - -Changed to C<.path>, but we haven't gotten around to specifying this on all of them. - -The C<.name> method returns the name of the file/socket/uri the handle -was opened with, if known. Returns Nil otherwise. There is no -corresponding C<name()> function. - -=item pipe - -Gone, see Pipe.pair - -=item select(both) - -Gone. (Note: for sub-second sleep, just use sleep with a fractional argument.) - -=item IO.shutdown() - -Gone, see C<IO::Socket.close()>, C<$IO::Readable.isReadable>, and C<$IO::Writeable.isWriteable> - -=item socketpair - -Gone, see Socket.pair - -=item IO.sysread - -Gone, see C<IO::Readable.read()>. - -=item IO.syswrite - -Gone, see C<IO::Writeable.read()>. - -=item utime - -Gone, see C<Path.times>. - -=back - -=head2 IO::Buffered - -Indicates that this object performs buffering. The management of the -buffer is completely implementation specific. - -=over - -=item method autoflush( --> Bool) is rw - -Forces this object to keep its buffers empty - -If set to nonzero, forces a flush right away and after every write -or print on the currently selected output channel. -Default is 0 (regardless of whether the channel is really buffered -by the system or not; -C<$OUT_FH.autoflush> tells you only whether you've asked Perl -explicitly to flush after each write). -C<$*OUT> will typically be line buffered if output is to the -terminal and block buffered otherwise. -Setting this variable is useful primarily when you are -outputting to a pipe or socket, -such as when you are running a Perl program under rsh -and want to see the output as it's happening. -This has no effect on input buffering. - - -=back - -=head2 IO::Streamable - -This role represents objects that depend on some external resource, -which means that data might not be available at request. - - role IO::Streamable does IO {...} - -=over - -=item new() - - method new( - Bool :$NoOpen, - Bool :$Blocking, - --> IO::Streamable - ) {...} - -Unless the NoOpen option is passed, an open will be done on the C<IO> object when it is -created. - -If blocking is passed in, .blocking() is called (see below). - -=item method blocking( --> Bool) is rw - -This allows the user to control whether this object should do a -blocking wait or immediately return in the case of not having data -available. - -=item uri - - method uri(Str $uri --> IO::Streamable) {...} - -This should be callable on the class, and act like a kind of "new()" function. When given -a URI, it returns an C<IO::Streamable> of the appropriate type, and throws an error when an -inappropriate type is passed in. For example, calling C<IO::File.uri('http://....')> will -throw an error (but will suggest using just uri('http://...') instead). - -=back - -=head2 IO::Encoded - -This is a generic role for encoded data streams. - -=over - -=item method encoding( --> Str) is rw - -=item method locale( --> Str) is rw - -Encoding and locale are required for sane conversions. - -=back - -=head2 IO::Readable::Encoded - -This role provides encoded access to a readable data stream, implies -C<IO::Encoded>. Might imply C<IO::Buffered>, but that's not a requirement. - -=over 4 - -=item uri -X<uri>X<ftp>X<http> - - method uri(Str $uri --> IO::Streamable); - sub uri(Str $uri --> IO::Streamable); - -Returns an appropriate C<IO::Streamable> descendant, with the type depending on the uri -passed in. Here are some example mappings: - - URI type IO type - ======== ======= - file: IO::Path - ftp: IO::Socket::INET (data channel) - http: IO::Socket::INET - -These can naturally be overridden or added to by other modules. - -=item %*PROTOCOLS dynamic variable - -For each protocol, stores a type name that should be instantiated by calling the C<uri> -constructor on that type, and passing in the appropriate uri. - -=back - -=head1 AUTHORS - - The authors of the related Perl 5 docs - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Daniel Ruoso <daniel@ruoso.com> - Lyle Hopkins <webmaster@cosmicperl.com> - Brent Laabs <bslaabs@gmail.com> - Tobias Leich <email@froggs.de> - Elizabeth Mattijsen <liz@wenzperl.nl> - -=for vim:set expandtab sw=4: diff --git a/S32-setting-library/Numeric.pod b/S32-setting-library/Numeric.pod deleted file mode 100644 index ea4ecb88..00000000 --- a/S32-setting-library/Numeric.pod +++ /dev/null @@ -1,672 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Numeric - -=head1 VERSION - - Created: 19 Mar 2009 extracted from S29-functions.pod - - Last Modified: 14 Feb 2015 - Version: 20 - -This documents Int, Numeric, Rat, Complex, and Bool. - -=head1 Function Packages - -=head2 Bool - -=over 4 - -=item succ - - multi method succ ( Bool $b: --> Bool ) is export - -Returns C<Bool::True>. - -=item pred - - multi method pred ( Bool $b: --> Bool ) is export - -Returns C<Bool::False>. - -=back - -=head2 Numeric - -C<Numeric> is a role for everything that's a scalar number. So C<Num>, C<Int>, -C<Rat>, C<Complex> and other numeric types do that role. However it is an -abstract interface, so C<$number.WHAT> will never return C<Numeric>. - -Users who provide their own scalar numeric types are encouraged to implement the -C<Numeric> role. It is intended that such types support the basic arithmetic -operators to the extent possible, as well as C<==>. In addition, it is hoped that -comparison operators will at least return consistent results, even if there is no -sensible mathematical ordering of your type. That allows functions like sort to -not choke and die if they are handed a value of your type. (See also the C<Real> -role for scalar numeric types that represent real numbers.) - -The following are all defined in the C<Numeric> role: - -C<Numeric> provides some constants in addition to the basic -mathematical functions. - - constant tau is export = 6.28318_53071_79586_47692_52867_66559_00576; - constant pi is export = 3.14159_26535_89793_23846_26433_83279_50288; - constant e is export = 2.71828_18284_59045_23536_02874_71352_66249; - constant i is export = 1i; - -C<τ> and C<π> are provided as aliases for C<tau> and C<pi>, respectively. - -=over - -=item Real - - multi method Real ( --> Real ) - -If this C<Numeric> is equivalent to a C<Real>, return that C<Real>. -(For instance, if this number is a C<Complex> with a zero imaginary part.) -Fail with C<X::Numeric::Real> otherwise. - -=item Int - - multi method Int ( --> Int ) - -If this C<Numeric> is equivalent to a C<Real>, return the equivalent of -calling C<truncate> on that C<Real> to get an C<Int>. Fail with -C<X::Numeric::Real> otherwise. - -=item Rat - - multi method Rat ( Real $epsilon = 1.0e-6 --> Rat ) - -If this C<Numeric> is equivalent to a C<Real>, return a C<Rat> which is -within C<$epsilon> of that C<Real>'s value. Fail with C<X::Numeric::Real> -otherwise. - -=item Num - - multi method Num ( --> Num ) - -If this C<Numeric> is equivalent to a C<Real>, return that C<Real> as a C<Num> -as accurately as is possible. Fail with C<X::Numeric::Real> otherwise. - -=item succ - - multi method succ ( Numeric $x: --> Numeric ) is export - multi method succ ( Int $x: --> Int ) is export - -Returns the successor of C<$x>. This method is used by C<< prefix:<++> >> and -C<< postfix:<++> >> to increment the value in a container. - -=item pred - - multi method pred ( Numeric $x: --> Numeric ) is export - multi method pred ( Int $x: --> Int ) is export - -Returns the predecessor of C<$x>. This method is used by C<< prefix:<--> >> -and C<< postfix:<--> >> to decrement the value in a container. - -=item abs - - multi method abs ( Numeric $x: --> Numeric ) is export - -Absolute Value. - -=item conj - - multi method conj ( Numeric $x: --> Numeric ) is export - -The complex conjugate of the value. For non-complex types, returns self. - -=item exp - - multi method exp ( Numeric $exponent: Numeric :$base = Num::e --> Numeric ) is export - -Performs similar to C<$base ** $exponent>. C<$base> defaults to the -constant I<e>. - -=item log - - multi method log ( Numeric $x: Numeric $base = Num::e --> Numeric ) is export - -Logarithm of base C<$base>, default Natural. Calling with C<$x == 0> is an -error. - -=item log10 - - multi method log10 (Numeric $x: --> Numeric ) is export - -A base C<10> logarithm, otherwise identical to C<log>. - -=item rand - - sub term:<rand> ( --> Num ) - -Pseudo random number in range C<< 0 ..^ 1 >>. That is, C<0> is -theoretically possible, while C<1> is not. Note that there is no -unary C<rand> function in Perl 6, but there is a C<rand> method. -For picking a random integer you probably want -to use something like C<(1..6).pick> instead. - -=item sqrt - - multi method sqrt ( Numeric $x: --> Numeric ) is export - -Returns the principal square root of the parameter. - -=item roots - - method roots (Numeric $x: Int $n ) is export - -Returns a list of all C<$n>th (complex) roots of C<$x>. Returns C<NaN> if -C<< $n <= 0 >>, itself if C<$n == 0>, and is free to return a single C<NaN> -if C<$x> is C<NaN> or C<Inf>, or in case of complex numbers if one of the -components is. - -=item i - - multi postfix:<i> ( Numeric $x --> Complex ) - -Returns a complex number representing the parameter multiplied by the imaginary -unit C<i>. Note that there is no C<.i> method. To follow a variable name -with the postfix, it's necessary to use a backslash or parentheses: - - $land\i - ($land)i - -=item to-radians - - multi method to-radians ( Numeric $x: TrigBase $base --> Numeric ) is export - -Convert from C<$base> to radians. - -=item from-radians - - multi method from-radians ( Numeric $x: TrigBase $base --> Numeric ) is export - -Convert from radians to C<$base>. - -=item narrow - - multi method narrow ( Numeric $x: ) is export - -Attempts to coerce the number to the narrowest type that can represent it accurately; -for instance, a C<Rat> with a denominator of 1 maybe be coerced to an C<Int> instead; -an integral C<Num> may likewise turn into an C<Int>. (Neither C<Num> nor C<Rat> convert -to each other, however.) C<Complex> with a 0 imaginary part may narrow to a C<Real> type. -Conjecturally, wide native types could narrow to narrower native types. - -=back - - -=head2 Real - - role Real does Numeric; - -C<Real>, like C<Numeric>, is an abstract role that represents the interface of -a real scalar number (i.e. neither C<Complex> nor vector-like). For example -C<Num>, C<Int>, C<Bool> and C<Rat> implement the C<Real> role. - -Users who provide their own scalar real numeric types are encouraged to implement the -C<Real> role. Because real numbers are strictly-totally-ordered and -C<Real> types try to emulate that property, it is desirable that any two -C<Real> types be mutually compatible, even if they are not aware of each other. The -current proposal requires you to define a C<Bridge> method in your C<Real> type, which -converts your type into a neutral C<Real> type by restating it in terms of the fundamental -Perl 6 types and calling C<Bridge> on them. This then makes the default C<Real> methods -and operators all work with your C<Real> type. While the name of this method may changed, -it is hoped that something like this will remain in the spec. - -=over - -=item Complex - - multi method Complex ( --> Complex ) - -Returns a C<Complex> whose real part is this C<Real> and whose imaginary part is 0. - -=item Str - - multi method Str ( --> Str ) - -Returns the C<Real> as a C<Str>. All built-in C<Real> types format it as a decimal -number, so for example, the C<Rat> C<5/4> is returned as C<"1.2">. - -=item base - - multi method base($base, $digits?) - -Returns a C<Str> representing the invocant in base C<$base>. Fails if C<$base> -is smaller than C<2> or larger than C<36>. - -For bases above ten, the digit repertoire is enhanced with uppercase latin -characters starting from C<A>. - -The optional C<$digits> argument asks for that many digits of fraction -(which may not be negative). If omitted, a reasonable default is chosen -based on type. For Int this default is 0. For Num, the default is 8. -For Rat, the number of places is scaled to the size of the denominator, -with a minimum of 6. - -The final digit produced is always rounded. - -=item floor - - multi method floor ( Real $x: --> Int ) is export - -Returns the highest integer not greater than C<$x>. - -=item ceiling - - multi method ceiling ( Real $x: --> Int ) is export - -Returns the lowest integer not less than C<$x>. - -=item round - - multi method round ( Real $x: $scale = 1 --> Real ) is export - -With no arguments, returns the nearest integer to C<$x>. If C<$scale> -is given, rounds $x to the nearest multiple of C<$scale>. The algorithm is: - - floor($x / $scale + 0.5) * $scale - -(Other rounding algorithms will be given extended names beginning with "round".) - -=item truncate - - multi method truncate ( Real $x: --> Int ) is export - -Returns the closest integer to C<$x> whose absolute value is not greater -than the absolute value of C<$x>. (In other words, just chuck any -fractional part.) This is the default rounding function used by -implicit integer conversions. - -You may also truncate using explicit integer casts, either C<Int()> for -an arbitrarily large integers, or C<int()> for native integers. - -=item sign - - multi method sign ( Real $x: --> Int ) is export - -Returns 1 when C<$x> is greater than 0, -1 when it is less than 0, 0 when it -is equal to 0, or undefined when the value passed is undefined. - -=item srand - - multi srand ( Real $seed = default_seed_algorithm()) - -Seed the generator C<rand> uses. C<$seed> defaults to some combination -of various platform dependent characteristics to yield a non-deterministic seed. -Note that you get one C<srand()> for free when you start a Perl program, so -you I<must> call C<srand()> yourself if you wish to specify a deterministic seed -(or if you wish to be differently nondeterministic). - -=item rand - - multi method rand (Real $x: --> Num ) is export - -Pseudo random number in range C<< 0 ..^ $x >>. That is, C<0> is -theoretically possible, while C<$x> is not. For picking a random integer -you probably want to use something like C<(1..6).pick> instead. - -=item cis - - multi method cis (Real $angle: --> Complex ) is export - -Returns 1.unpolar($angle) - -=item unpolar - - multi method unpolar (Real $mag: Real $angle --> Complex ) is export - -Returns a complex number specified in polar coordinates. Angle is in radians. - -=item polymod - - method polymod(*@mods) - -Returns a sequence of mod results corresponding to the divisors in -C<@mods>. If the number of divisors is finite, returns one more result -than the number of divisors, and the final result is the remainder after -all the divisions. If the number of divisors is infinite, runs until -the remainder is 0. The C<Int> version of this method assumes all the -divisors are also integers. Coerce the invocant to C<Num> or C<Rat> -if you wish to use fractional operations. - -=back - -=head2 Num - - class Num does Real - -C<Num> is a machine-precision numeric real value. - -=head2 Complex - -C<Complex> is an immutable type. Each C<Complex> object stores two numbers, -the real and imaginary part. For all practical purposes a C<Complex> with -a C<NaN> in real or imaginary part may be considered a C<NaN> itself (and -C<(NaN+1i) ~~ NaN> is C<True>). - -Coercion of a C<Complex> to any C<Real> returns the real part (coerced, if -necessary) if the imaginary part is 0, and fails otherwise. Comparison -between a C<Real> number and a C<Complex> must be smart enough not to coerce -the C<Complex> to a real number blindly. - -=over 4 - -=item new - - multi method new(Real $re, Real $im --> Complex ) - -Constructs a C<Complex> number from real and imaginary part. This is the -method form of C<$re+$im\i>. (But use the C<< <1+2i> >> form for literals, -so that you don't have to worry about precedence or rely on constant folding.) - -=item polar - - multi method polar (Complex $nim: --> List ) is export - -Returns (magnitude, angle) corresponding to the complex number. -The magnitude is non-negative, and the angle in the range C<-π ..^ π>. - -=item re - - multi method re( --> Real ) - -Returns the real part of the complex number. - -=item im - - multi method im( --> Real ) - -Returns the imaginary part of a complex number. - -=item conj - - multi method conj(Complex $c --> Complex ) - -Returns C<< ($c.re - $c.im\i) >>, the complex conjugate. - -=item gist - - multi method gist( --> Str ) - -Returns a string representation of the form "C<1+2i>", without -internal spaces. (C<Str> coercion also returns this.) - -=item perl - - multi method perl( --> Str ) - -Returns a string representation corresponding to the unambiguous -C<val()>-based representation of complex literals, of the form "C<< <1+2i> >>", -without internal spaces, and including the angles that keep the C<+> -from being treated as a normal addition operator. - -=item floor - - multi method floor ( Complex $c: --> Complex ) is export - -Returns C<$c.re.floor + $c.im.floor>. That is, each of the real and imaginary parts -is rounded to the highest integer not greater that the value of that part. - -=item ceiling - - multi method ceiling ( Complex $c: --> Complex ) is export - -Returns C<$c.re.ceiling + $c.im.ceiling>. That is, each of the real and imaginary -parts is rounded to the lowest integer not less that the value of that part. - -=item round - - multi method round ( Complex $c: $scale = 1 --> Complex ) is export - -With no arguments, rounds both the real and imaginary parts to the nearest -integer and returns a new Complex number. If C<$scale> is given, rounds both -parts of $c to the nearest multiple of C<$scale>. Uses the same algorithm as -Real.round on each part of the number. - -=item truncate - - multi method truncate ( Complex $c: --> Complex ) is export - -Removes the fractional part of both the real and imaginary parts of the number, -using Real.truncate, and returns the result as a new Complex. - -=back - -=head2 Trigonometric functions - -The following are also defined in C<Numeric>. Most trig functions are -specified to operate in terms of radians, as the mathematical and programming -standard. Functions are provided to convert other angle specifications to and -from radians. Angle specifications are given in terms of enum TrigBase: - - enum TrigBase is export ( - Radians => 1, - Degrees => (pi / 180), - Gradians => (pi / 200), - Circles => 2*pi - ); - -=over 4 - -=item I<Standard Trig Functions> - - Numeric multi method func ( Numeric $x ) is export - -where I<func> is one of: -sin, cos, tan, asin, acos, atan, sec, cosec, cotan, asec, acosec, -acotan, sinh, cosh, tanh, asinh, acosh, atanh, sech, cosech, cotanh, -asech, acosech, acotanh. - -Performs the various trigonometric functions. The argument is always expressed -in radians. The return value from C<CORE::> versions of these functions is -always C<Num>, unless domain limits force it to be C<Complex> instead. - -=item I<Converting Angles> - -If you prefer to express angles in units other than radians, you have two -choices. First, you can convert the angles into radians, by multiplication: - - sin(90 * Degrees) - -or by using the C<to-radians> method: - - sin(90.to-radians(Degrees)); - -Alternatively, you can use the C<trigbase> pragma to install a new set of -trigonometric functions into the current lexical scope, which will handle -a different unit: - - use trigbase Degrees; - sin(90) - -The parameter to the trigbase pragma must be something that is usable as a -number. The above code fragment is more or less equivalent to: - - constant $?TRIGBASE = Degrees; - sub sin($x) { CORE::sin($x * Degrees) } - # repeat for all the other trig operators - sin(90) - -Two points must be emphasized. First, C<trigbase> has no effect on the method -forms of trig operators; C<.sin> always expects radians. Second, because it -defines dozens of subs, it's probably a good idea to use C<trigbase> in the -highest scope where it makes sense. - -The C<$?TRIGBASE> constant is not used by the trig operators themselves. It -exists only to allow modules to be C<trigbase> aware. - -=item atan2 - - multi method atan2 ( Real $y: Real $x = 1, TrigBase $base = CALLER::<$?TRIGBASE> --> Real ) - multi atan2 ( Real $y, Real $x = 1, TrigBase $base = CALLER::<$?TRIGBASE> --> Real ) - -This second form of C<atan> computes the arctangent of C<$y/$x>, and takes -the quadrant into account. Otherwise behaves as other trigonometric functions. - -=back - -=head2 Int - -An C<Int> is an immutable, integral number of arbitrary size. - -=over - -=item expmod - - multi method expmod ( Int $x: Int $y, Int $mod --> Int ) is export - -Returns C<$x> raised to the C<$y> power within modulus C<$mod>. - -=item is-prime - - multi method is-prime ( Int $x: Int $tries = 100) is export - -Returns True if C<$x> is known to be a prime, or is likely to be a -prime based on a probabalistic Miller-Rabin test. (The optional -argument tells how many times to iterate the probabalistic test, -if such is necessary.) - -Returns False if C<$x> is known not to be a prime. - -=item lsb - - multi method lsb ( Int $x: ) is export - -Returns the least significant bit position containing a 1 bit, counting -bit positions from least significant to most significant. (In other -words, it's the base 2 logarithm of number represented by that 1 bit.) - -This function returns C<Nil> on a 0 value, since there are no bits set. -Negative integers are treated as 2's complement, so always have -a lowest bit set somewhere, if only the sign bit. Hence, a -32768 -returns an lsb of 15 regardless of whether it's stored in an C<int16> -or an C<Int>. - -=item msb - - multi method msb ( Int $x: ) is export - -Returns the most significant bit position containing a 1 bit, that is, -the base 2 logarithm of the top 1 bit. - -This function returns C<Nil> on a 0 value. For negative values, the -function is dependent on the type. For native types, signed integers -are treated as unsigned, so a negative number stored in C<int64> will -always return 63. Negative integers stored in an C<Int> notionally -have an infinite number of 1 bits on top, which is a problem. -Instead of returning C<+Inf>, which is relatively useless, we return -the position of the first of that infinite supply of sign bits. -So C<msb(-1)> returns 0, C<msb(-2)> returns 1, and C<msb(-32768)> -returns 15, just as if we'd converted it from C<int16> to C<uint16> -and examined that for its top bit. - -=back - -=head2 Rat - - class Rat does Real - -An immutable rational number, represented by two C<Int>s, a numerator and -a denominator. All interface methods return values as if the numerator and -denominator were stored in a normal form: both numerator and denominator are -minimal in their magnitude, and the denominator is positive. So -C<Rat.new(2, -4).denominator> return C<2>, because the normal form is C<-1/2>. - -(An implementation is allowed to be lazy about this internally when it -determines that normalizing repeatedly is detrimental to performance, -such as when adding a column of numbers that all have an internal -denominator of 100.) - -=over - -=item new - - multi method new(Int $num, Int $denom) - -Constructs a C<Rat> object from the numerator and denominator. -Fails if C<$denom == 0>. You can use division to produce a C<Rat> -through constant folding, but generally if you know the values in -advance, you should use one of literal forms so that you don't have to -rely on precedence. You may use the C<val()>-based C<< <3/5> >> form, -or you can simply write decimal numbers with a decimal point, since -C<12.34> is essentially identical to C<< <1234/100> >> as a literal. - -=item nude - - multi method nude( --> List ) - -Returns a C<List> of numerator and denominator. - -=item denominator - - multi method denominator( --> Int ) - -Returns the denominator. - -=item numerator - - multi method numerator( --> Int ) - -Returns the numerator. - -=item gist - - multi method gist( --> Str ) - -Returns a string representation of the number in decimal. If the -number can be represented exactly in decimal, it will be. In any case, -the portion before the decimal point (the "integer" part) is guaranteed -to be exact. The precision of the fractional part is defined to be -one more digit than the size of the denominator after the integer part -has been removed, but at least 6 digits for repeating fractions. -The final digit of the fractional part is rounded. - -C<Str> coercion is identical to C<gist>. - -=item perl - - multi method perl( --> Str ) - -Returns a string representation corresponding to the unambiguous -C<val()>-based representation of rational literals. If the -number can be represented exactly in decimal, it will be. Otherwise uses -the form "C<< <3/5> >>", without internal spaces, and including the -angles that keep the C</> from being treated as a normal division -operator. - -=item base-repeating - - multi method base-repeating($base) - -Returns two strings representing the invocant in base C<$base>. Fails if C<$base> -is smaller than C<2> or larger than C<36>. - -For bases above ten, the digit repertoire is enhanced with uppercase latin -characters starting from C<A>. - -The first returned string is the non-repeating part of the representation. -The second is the repeating part. The precision is arbitrarily limited to 100000. -Above that, the repeating group will return '???'. If there is no repeating group, -the second returned string is C<''>. - -=back - -=head1 AUTHORS - - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Stefan O'Rear <stefanor@cox.net> - -=for vim:set expandtab sw=4: diff --git a/S32-setting-library/Rules.pod b/S32-setting-library/Rules.pod deleted file mode 100644 index d4dc1687..00000000 --- a/S32-setting-library/Rules.pod +++ /dev/null @@ -1,111 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Rules - -=head1 VERSION - - Created: 27 Feb 2009 - - Last Modified: 5 Jul 2013 - Version: 2 - -The document is a draft. - -=head1 Overview - -This synopsis deals with objects produced by the regexes and grammars -described in much greater detail in L<S05>. - -=head1 Classes - -=head2 Regex - - class Regex is Method {...} - -Regex objects are created through the syntax described in S05: - - / ... / - rx/ ... / - regex { ... } - -They can be stored in variables for later use, as with the C<qr//> syntax -in Perl 5. - -=over - -=item method Bool(Regex:D: ) - -In boolean context, a regex object will match against C<$_>, and return -the result as a Bool. - -=back - -=head2 Match - - class Match is Cool does Positional does Associative { - method from( --> Int ) {...} - method to( --> Int ) {...} - method chars( --> Int ) {...} - method orig() {...} - method ast() {...} - method caps() {...} - method chunks() {...} - method pos() {...} - - method bool() {...} - method Str() {...} - method Num() {...} - method ast() {...} - } - -=head2 Cursor - - class Cursor { - method pos( --> Int ) {...} - method orig() {...} - } - -=head2 Grammar - - class Grammar is Cursor - -Much as a class is a collection of named attributes and methods, a grammar -is a collection of named regexes and rules. For more on creating and using -grammars, see L<S05/Grammars>. - -=over - -=item parse / subparse -X<parse> X<subparse> - - method parse ($target, :$rule = 'TOP', Mu :$actions = Mu, *%opts) - method subparse ($target, :$rule = 'TOP', Mu :$actions = Mu, *%opts) - -Parses the C<$target> string with given <:rule>, and returns the result -as a Match object. Defaults to the C<TOP> rule. A class containing actions -may be attached using the C<actions> named argument. - -The C<parse> method automatically anchors the rule to the beginning and end -of the target string (adding C<^> and C<$> around the rule). The C<subparse> -method does not add anchors, and will match substrings against the rule. - -=item parsefile - - method parsefile (Cool $filename, :$rule = 'TOP', Mu :$actions = Mu, *%opts) - -Parse the file as with C<.parse>, but matches the grammar against the contents -of C<$filename> instead. - -=back - -See Abstractions.pod - -=head1 AUTHORS - - Tim Nelson <wayland@wayland.id.au> - Larry Wall <larry@wall.org> - Brent Laabs <bslaabs@gmail.com> - diff --git a/S32-setting-library/Str.pod b/S32-setting-library/Str.pod deleted file mode 100644 index c1138e68..00000000 --- a/S32-setting-library/Str.pod +++ /dev/null @@ -1,621 +0,0 @@ - -=encoding utf8 - -=head1 TITLE - -DRAFT: Synopsis 32: Setting Library - Str - -=head1 VERSION - - Created: 19 Mar 2009 (extracted from S29-functions.pod) - - Last Modified: 2015-07-24 - Version: 13 - -The document is a draft. - -=head1 Str - -General notes about strings: - -The C<Str> class contains strings encoded at the NFG level. Other standard -Unicode normalizations can be found in their appropriately-named types: C<NFC>, -C<NFD>, C<NFKC>, and C<NFKD>. The C<Uni> type contains a string in a mixture of -normalizations (i.e. not normalized). S15 describes these in more detail. - -The following are all provided by the C<Str> class, as well as related classes: - -=over - -=item chop - - multi method chop(Str $string: $n = 1 --> Str) is export - -Returns string with an optional number of characters removed from the end. -Defaults to removing one character. - -=item chomp - - multi method chomp(Str $string: --> Str) is export - -Returns string with one newline removed from the end. An arbitrary -terminator can be removed if the input filehandle has marked the -string for where the "newline" begins. (Presumably this is stored -as a property of the string.) Otherwise a standard newline is removed. - -Note: Most users should just let their I/O handles autochomp instead. -(Autochomping is the default.) - -=item lc - - multi method lc(Str $string: --> Str) is export - -Returns the input string after forcing each character to its lowercase -form. Note that one-to-one mapping is not in general guaranteed; -different forms may be chosen according to context. - -=item uc - - multi method uc(Str $string: --> Str) is export - -Returns the input string after forcing each character to its uppercase -(not titlecase) form. Note that one-to-one mapping is not in general guaranteed; -different forms may be chosen according to context. - -=item fc - - multi method fc(Str $string: --> Str) is export - -Does a Unicode "fold case" operation suitable for doing caseless -string comparisons. (In general, the returned string is unlikely to -be useful for any purpose other than comparison.) - -=item tc - - multi method tc(Str $string: --> Str) is export - -Converts the first character of a string to titlecase form, -leaving the rest of the characters unchanged, then returns the -modified string. If there is no titlecase mapping for the first -character, the entire string is returned unchanged. In any case, -this function never changes any character after the first. (It -is like the old Perl 5 C<ucfirst> function in that respect.) - -=item tclc - - multi method tclc(Str $string: --> Str) is export - -Forces the first character of a string to titlecase and the rest of -the characters to lowercase, then returns the modified string. - -=item wordcase - - multi method wordcase(Str $string: - :&filter = &tclc, - :$where = True --> Str) is export - -Performs a substitutional mapping of each word in the string, -defaulting to the C<tclc> mapping. Words are defined as Perl 6 -identifiers, hence admit hyphens and apostrophes when followed -by a letter. (Note that trailing apostrophes don't matter when -casemapping.) The following should have the same result: - - .wordcase; - .subst(:g, / <ident>+ % <[ \- ' ]> /, *.Str.tclc) - -The C<filter> function is always applied to the first and last word, and -additionally to any intermediate word that smartmatches with the C<where> -parameter. Assuming suitable definitions of word lists, standard English -capitalization might be handled with something like this: - - my $where = none map *.fc, @conjunctions, @prepositions; - .wordcase(:$where); - -(Note that the "standard" authorities disagree on the prepositions!) - -[XXX: Is case-insensitive matching on C<wordcase>'s part necessary?] -The smartmatching is done case insensitively, so you should store -your exceptions in C<fc> form. If the C<where> smartmatch does not -match, then the word will be forced to lowercase. - -There is no provision for an alternate regex; if you need a custom -word recognizer, you can write your own C<.subst> as above. - -=item samecase - - multi method samecase(Str $string: Str $pattern --> Str) is export - -Has the effect of making the case of the string match the case pattern in -C<$pattern>. (Used by s:ii/// internally, see L<S05>.) - -=item samemark - - multi method samemark(Str $string: Str $pattern --> Str) is export - -Has the effect of making the case of the string match the marking pattern in C<$pattern>. -(Used by s:mm/// internally, see L<S05>.) - -=item length - -This method does not exist in Perl 6. You must use either C<chars> or C<codes>, -depending on what kind of count you need. - -=item chars - - multi method chars(Str $string: --> Int) is export - -Returns the number of characters in the string. For C<Str> this corresponds to -the number of graphemes, for other types this is equivalent to C<codes>. - -=item codes - - multi method codes(Str $string: --> Int) is export - -Returns the number of codepoints in the string. For C<Str> this corresponds to -the number of characters as if it were an C<NFC> type string. - -=item bytes - -Gone. Use C<$str.encode($encoding).bytes> instead. - -=item encode - - multi method encode($encoding = $?ENC --> Buf) - -Returns a C<Blob> which represents the original string in the given -encoding. The actual return type is as specific as possible, so -C<$str.encode('UTF-8')> returns a C<utf8> object, C<$str.encode('ISO-8859-1')> a -C<blob8>. - -C<Str.encode> is functionally equivalent to C<NFC.encode>. If you mean one of -the other normalization forms, convert the C<Str> to the appropriate type first. - -=item index - - multi method index(Str $string: Str $substring, Int $pos) is export - -C<index> searches for the first occurrence of C<$substring> in C<$string>, -starting at C<$pos>. - -If the substring is found, then the value returned represents the position -of the first character of the substring. If the substring is not found, -C<Nil> is returned. Do not evaluate it as a number, because that will -assume <0> and issue a warning. - -[Note: if C<$substring> is not of the same string type as C<$string>, should -that cause an error, or should C<$substring> be converted to C<$string>'s type?] - -=item pack - - multi pack(*@items where { all(@items) ~~ Pair } --> buf8) - multi pack(Str $template, *@items --> buf8) - -C<pack> takes a list of pairs and formats the values according to -the specification of the keys. Alternately, it takes a string -C<$template> and formats the rest of its arguments according to -the specifications in the template string. The result is a sequence -of bytes. - -Templates are strings of the form: - - grammar Str::PackTemplate { - regex TOP { ^ <template> $ } - regex template { [ <group> | <specifier> <count>? ]* } - token group { \( <template> \) } - token specifier { <[aAZbBhHcCsSiIlLnNvVqQjJfdFDpPuUwxX\@]> \!? } - token count { \* - | \[ [ \d+ | <specifier> ] \] - | \d+ } - } - -In the pairwise mode, each key must contain a single C<< <group> >> or -C<< <specifier> >>, and the values must be either scalar arguments or -arrays. - -[ Note: Need more documentation and need to figure out what Perl 5 things - no longer make sense. Does Perl 6 need any extra formatting - features? -ajs ] - -[I think pack formats should be human readable but compiled to an -internal form for efficiency. I also think that compact classes -should be able to express their serialization in pack form if -asked for it with .packformat or some such. -law] - -=item rindex -X<rindex> - - multi method rindex(Str $string: Str $substring, Int $pos) is export - -Returns the position of the last C<$substring> in C<$string>. If C<$pos> -is specified, then the search starts at that location in C<$string>, and -works backwards. See C<index> for more detail. - -=item split -X<split> - - multi sub split(Str $delimiter, - Str $input, - Int $limit = Inf, - Bool :$all = False - --> List) - multi sub split(Regex $delimiter, - Str $input, - Int $limit = Inf, - Bool :$all = False - --> List) - multi method split(Str $input: - Str $delimiter, - Int $limit = Inf, - Bool :$all = False - --> List) - multi method split(Str $input: - Regex $delimiter, - Int $limit = Inf, - Bool :$all = False - --> List) - -Splits a string up into pieces based on delimiters found in the string. - -Delimiters can be specified as either a C<Regex> or a constant string type. The -C<split> function no longer has a default delimiter nor a default invocant. In -general you should use C<words> to split on whitespace now, or C<comb> to break -into individual characters. (See below.) - -If the C<:all> adverb is supplied to the string delimiter form, the delimiter -will be returned in alternation with the split values. In C<Regex> delimiter -form, the delimiters are returned as C<Match> objects in alternation with the -split values. Unlike with Perl 5, if the delimiter contains multiple captures -they are returned as submatches of single C<Match> object. (And since C<Match> -does C<Capture>, whether these C<Match> objects eventually flatten or not -depends on whether the expression is bound into a list or slice context.) - -You may also split lists and filehandles. C<$*ARGS.split(/\n[\h*\n]+/)> splits -on paragraphs, for instance. Lists and filehandles are automatically fed through -C<cat> in order to pretend to be string. The resulting C<Cat> is lazy. Accessing -a filehandle as both a filehandle and as a C<Cat> is undefined. - -=item comb - - multi sub comb(Str $matcher, - Str $input, - Int $limit = Inf, - Bool :$match - --> List) - multi sub comb(Regex $matcher, - Str $input, - Int $limit = Inf, - Bool :$match - --> List) - multi method comb(Str $input: - Str $matcher, - Int $limit = Inf, - Bool :$match - --> List) - multi method comb(Str $input: - Regex $matcher = /./, - Int $limit = Inf, - Bool :$match - --> List) - -The C<comb> function looks through a string for the interesting bits, -ignoring the parts that don't match. In other words, it's a version -of split where you specify what you want, not what you don't want. - -That means the same restrictions apply to the matcher rule as do to -split's delimiter rule. - -By default it pulls out all individual characters. Saying - - $string.comb(/pat/, $n) - -is equivalent to - - map {.Str}, $string.match(rx:global:x(0..$n):c/pat/) - -You may also comb lists and filehandles. C<+$*IN.comb> counts the characters on -standard input, for instance. C<comb(/./, $thing)> returns a list of single -character strings from anything that can give you a C<Str>. Lists and -filehandles are automatically fed through C<cat> in order to pretend to be -string. This C<Cat> is also lazy. - -If the C<:match> adverb is applied, a list of C<Match> objects (one per match) -is returned instead of strings. This can be used to access capturing subrules -in the matcher. The unmatched portions are never returned -- if you want that, -use C<split(:all)>. If the function is combing a lazy structure, the return -values may also be lazy. (Strings are not lazy, however.) - -=item lines - - multi method lines(Str $input: Int $limit = Inf --> List) is export - -Returns a list of lines, i.e. the same as a call to C<$input.comb(/ ^^ \N* /, -$limit)> would. - -=item words - - multi method words(Str $input: Int $limit = Inf --> List) is export - -Returns a list of non-whitespace bits, i.e. the same as a call to -C<$input.comb(/ \S+ /, $limit)> would. - -=item flip - -The C<flip> function reverses a string character by character. - - multi method flip(Str $str: --> Str) is export - -This method will misplace combining characters on non-C<Str> types. - -=item sprintf - - multi method sprintf(Str $format: *@args --> Str) is export - -This function is mostly identical to the C library sprintf function. - -The C<$format> is scanned for C<%> characters. Any C<%> introduces a -format token. Format tokens have the following grammar: - - grammar Str::SprintfFormat { - regex format_token { '%': ['%' | <index>? <precision>? <directive>] } - token index { \d+ '$' } - token precision { <flags>? <vector>? <precision_count> } - token flags { <[ \x20 + 0 \# \- ]>+ } - token precision_count { [ <[1..9]>\d* | '*' ]? [ '.' [ \d* | '*' ] ]? } - token vector { '*'? v } - token directive { <[csduoxefgXEGbpniDUOF]> } - } - -Directives guide the use (if any) of the arguments. When a directive -(other than C<%>) is used, it indicates how the next argument -passed is to be formatted into the string. - -The directives are: - - % a literal percent sign (must be literally '%%') - c a character with the given codepoint - s a string - d an integer, in decimal - b an integer, in binary - o an integer, in octal - x an integer, in hexadecimal - X like x, but using uppercase letters - e a floating-point number, in scientific notation - f a floating-point number, in fixed decimal notation - g a floating-point number, in %e or %f notation - E like e, but using an uppercase "E" - G like g, but with an uppercase "E" (if applicable) - -Compatibility: - - i a synonym for %d - u a synonym for %d - D a synonym for %d - U a synonym for %u - O a synonym for %o - F a synonym for %f - -Perl 5 (non-)compatibility: - - n produces a runtime exception - p produces a runtime exception - -=item fmt - - multi method fmt(Scalar $scalar: Str $format = '%s' --> Str) - multi method fmt(List $list: - Str $format = '%s', - Str $separator = ' ' - --> Str) - multi method fmt(Hash $hash: - Str $format = "%s\t%s", - Str $separator = "\n" - --> Str) - multi method fmt(Pair $pair: Str $format = "%s\t%s" --> Str) - -A set of wrappers around C<sprintf>. A call to the scalar version -C<$o.fmt($format)> returns the result of C<sprintf($format, $o)>. A call to the -list version C<@a.fmt($format, $sep)> returns the result of C<@a.map({ -sprintf($format, $_) }).join($sep)>. A call to the hash version -C<%h.fmt($format, $sep)> returns the result of C<%h.pairs.map({ sprintf($format, -$_.key, $_.value) }).join($sep)>. A call to the pair version C<$p.fmt($format)> -returns the result of C<sprintf($format, $p.key, $p.value)>. - -=item substr - - multi sub substr(Str $string, Int $start, Int $length? --> Str) is export - multi sub substr(Str $string, &start, Int $length? --> Str) is export - multi sub substr(Str $string, Int $start, &end --> Str) is export - multi sub substr(Str $string, &start, &end --> Str) is export - multi sub substr(Str $string, Range $start-end --> Str) is export - - multi method substr(Str $string: Int $start, Int $length? --> Str) is export - multi method substr(Str $string: &start, Int $length? --> Str) is export - multi method substr(Str $string: Int $start, &end --> Str) is export - multi method substr(Str $string: &start, &end --> Str) is export - multi method substr(Str $string: Range $start-end --> Str) is export - -C<substr> returns a substring of C<$string> between the given points. The first -character can be specified as either an integer or a C<Callable> taking the -length of the string as its only argument. The endpoint can be specified by -either an C<Int> specifying the length of the substring, or a C<Callable> taking -the length of the string as its only argument and returning the last character -to take. The bounds of the substring can be specified by a C<Range> instead. - -If the specified length or endpoint goes past the end of the string, or if no -endpoint is specified, the rest of the string from the starting point will be -returned. - -Here is an example of its use: - - $initials = substr($first_name,0,1) ~ substr($last_name,0,1); - -The function fails if the start position and/or length is negative or -undefined. (If the length argument is not given, it defaults to the rest of the -string.) Either of start position or end position may be specified relative to -the end of the string using a C<WhateverCode> whose argument will be the -position of the end of the string. While it is illegal for the start position to -be outside of the string, it is allowed for the final position to be off the end -of the string. - -=item substr-rw - - multi sub substr-rw(Str $string, Int $start, Int $length? --> Str) is rw is export - multi sub substr-rw(Str $string, &start, Int $length? --> Str) is rw is export - multi sub substr-rw(Str $string, Int $start, &end --> Str) is rw is export - multi sub substr-rw(Str $string, &start, &end --> Str) is rw is export - multi sub substr-rw(Str $string, Range $start-end --> Str) is rw is export - - multi method substr-rw(Str $string: Int $start, Int $length? --> Str) is rw is export - multi method substr-rw(Str $string: &start, Int $length? --> Str) is rw is export - multi method substr-rw(Str $string: Int $start, &end --> Str) is rw is export - multi method substr-rw(Str $string: &start, &end --> Str) is rw is export - multi method substr-rw(Str $string: Range $start-end --> Str) is rw is export - -A version of C<substr> that returns a writable reference to a part of a -string variable: - - my $string = "one of the characters in the Flinstones is: barney"; - $string ~~ /(barney)/; - substr-rw($string, $0.from, $0.to) = "fred"; - -This writable reference can be the target of an alias, for repeated -operations: - - my $r := substr-rw($string, $0.from, $0.to); - $r = "fred"; # "barney" replaced by "fred" - $r = "wilma"; # "fred" replaced by "wilma" - -Please note that only the start point is kept by the reference: any changes to -the length of the string before the start point, will render the reference -useless. So it is probably safest to keep only one writable reference per -string, or make sure that all replacement strings have the same size. - -=item trim - - multi method trim() is export; - multi method trim-leading() is export; - multi method trim-trailing() is export; - -The C<trim> method returns a copy of the string with leading and trailing -whitespace removed. The methods C<trim-leading> and C<trim-trailing> are -similar, but with only leading or trailing whitespace removed, respectively. - -=item unpack - -B<XXX To be defined> - -=item match - - method match(Str $self: Regex $search, *%adverbs --> Match) is export - -Returns the result of checking the given string against C<$search>. See S05 for -details. - -=item subst - - method subst(Str $self: Regex $search, Str $replacement, *%adverbs --> Str) is export - -Returns a string with the portion of the string matching C<$search> being -replaced with C<$replacement>. See S05 for details. - -=item trans - - method trans(Str $self: - *@changes where { all(@changes) ~~ Pair }, - *%adverbs - --> Str) is export; - -Takes a list of C<Pair>s and replaces each occurence of a C<Pair>'s key with its -respective value. See S05 for details. - -=item indent - - multi method indent($str: Int() $steps --> Str) is export - multi method indent($str: Whatever $steps --> Str) is export - -Returns a re-indented string wherein C<$steps> number of spaces have been added -to each line. If a line already begins with horizontal whitespace, the new -spaces are added to the end of those. - -If the whitespace at the beginning of the line consists of only C<\x20> -spaces, C<\x20> spaces are added as indentation as well. If the whitespace -at the beginning of the line consists of some other kind of horizontal -whitespace, that kind of whitespace is added as indentation. If the whitespace -at the beginning of the line consists of two or more different kinds of -horizontal whitespace, again C<\x20> spaces are used. - -If C<$steps> is negative, removes that many spaces instead. Should any line -contain too few leading spaces, only those are removed and a warning is issued. -At most one such warning is issued per C<.indent> call. - -If C<$steps> is C<*>, removes just enough indentation to make some line have -zero indentation. - -Empty lines don't participate in re-indenting at all. That is, a line with -0 characters will still have 0 characters after the call. It also will not -cause a warning to be issued. - -The method will assume hard tabs to be equivalent to C<< ($?TABSTOP // 8) >> -spaces, and will treat any other horizontal whitespace character as equivalent -to one C<\x20> space. If the indenting doesn't "add up evenly", one hard tab -needs to be exploded into the equivalent number of spaces before the unindenting -of that line. - -Decisions on how to indent each line are based solely on characters on -that line. Thus, an C<.indent> call on a multiline string therefore amounts -to C< .lines».indent.join("\n") >, modulo exotic line endings in the -original string, and the proviso about empty lines. - -=item IO - - method IO(--> IO::Path) is export - -Returns an IO::Path, using the string as the file path. - -=item path - - method path(--> IO::Path) is export - -A deprecated form of C<IO>. - -=item succ - - method succ(--> Str) is export - -Increments the string to the next numeric or alphabetic value, and returns the -resulting string. The autoincrement operator C<++> uses C<succ> to determine -the new value. - -The last portion of the string before the first period (which may be the entire -string) is incremented, using C<< <rangechar> >> to determine which characters -are eligible to be incremented. See L<S03/Autoincrement precedence> for -details. - -=item pred - - method pred(--> Str) is export - -Decrements the string to the next numeric or alphabetic value, and returns the -resulting string. The autodecrement operator C<--> uses C<pred> to determine the -new value. - -When attempting to decrement a string, such as C<"a0">, where the result would -remove the leftmost characters, C<pred> returns failure instead. - -The last portion of the string before the first period (which may be the entire -string) is incremented, using C<< <rangechar> >> to determine which characters -are eligible to be incremented. See L<S03/Autoincrement precedence> for details. - -=back - -=head1 AUTHORS - - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Brent Laabs <bslaabs@gmail.com> - diff --git a/S32-setting-library/Temporal.pod b/S32-setting-library/Temporal.pod deleted file mode 100644 index 0277c144..00000000 --- a/S32-setting-library/Temporal.pod +++ /dev/null @@ -1,295 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 32: Setting Library - Temporal - -=head1 VERSION - - Created: 19 Mar 2009 - - Last Modified: 10 May 2014 - Version: 23 - -=head1 Time and time again - -Two chief aspects of a Perl 6 synopsis seem to contribute to it having -some extra volatility: how far it sits from the rest of the data model -of the language, and how everyday the topic in question is. C<S32> has -always been volatile for these reasons; C<S32::Temporal> doubly so. - -The truth is that while there are many interests to satisfy in the case -of a C<Temporal> module, and many details to take into account, there's -also the danger of putting too much in. Therefore, Perl 6's C<Temporal> -module takes the C<DateTime> module on CPAN as a starting point, adapts -it to the Perl 6 OO system, and boils it down to bare essentials. - -One of the unfortunate traditions that Perl 6 aims to break is that of -having a set of "core" modules which could better serve the community on -CPAN than in the Perl core. For this reason, this module doesn't handle -all the world's time zones, locales, date formatters or calendars. -Instead, it handles a number of "natural" operations well enough for -most people to be happy, and shows how those who want more than that can -load a module, or roll their own variants. Put differently, the below -are the aspects of time that are felt to be stable enough to belong in -the core. - -Note that in this document, the term "POSIX time" means the number of -seconds since midnight UTC of 1 January 1970, not counting leap seconds. -This is the same as the output of the ISO C C<time> function. -Unlike in Perl 5, C<time> does not return fractional seconds, since C<POSIX> -does not define the concept during leap seconds. You want -to use C<now> for that instead. - -=head1 C<time> - -Returns the current POSIX time as an C<Int>. Use C<now> for an -epoch-agnostic measure of atomic seconds (i.e., an C<Instant>). -Note that both C<time> and C<now> are not functions, but terms -of the pseudo-constant variety; as such they never take an argument. -Saying C<time()> doesn't work unless you happen to have a function -of that name defined. - -=head1 C<DateTime> - -A C<DateTime> object, which is immutable, describes a moment in time as it -would appear on someone's calendar and someone's clock. You can create a -C<DateTime> object from an C<Instant> or from an C<Int>; in the latter -case, the argument is interpreted as POSIX time. - - my $now = DateTime.new(now); - my $now = DateTime.new(time); - -These two statements are equivalent except that C<time> doesn't know about -leap seconds or fractions of seconds. Ambiguous POSIX times (such as -915148800, which could refer to 1998-12-31T23:59:60Z or -1999-01-01T00:00:00Z) are interpreted as non-leap seconds (so in this case, -the result would be 1999-01-01T00:00:00Z). - -Or you can use named arguments: - - my $moonlanding = DateTime.new( :year(1969), :month(7), :day(16), - :hour(20), :minute(17) ); # UTC time - -This form allows the following arguments: - - :year required - :month defaults to 1 range 1..12 - :day defaults to 1 range 1..31 - :hour defaults to 0 range 0..23 - :minute defaults to 0 range 0..59 - :second defaults to 0 range 0.0..^62.0 - -Another multi exists with C<Date :date> instead of C<:year>, C<:month> and -C<:day> (and the same defaults as listed above). - -All of the aforementioned forms of C<new> accept two additional named -arguments. C<:formatter> is a callable object that takes a C<DateTime> and -returns a string. The default formatter creates an ISO 8601 timestamp (see -below). C<:timezone> must be an Int or an object that supports an .Int method. -The Int value of C<:timezone> must reflect the timezone offset, in seconds -from UTC. The default time zone is C<0> (i.e., UTC). -The system's local time zone is available as C<$*TZ>. - -A shorter way to send in date and time information is to provide a -single string with a full L<RFC 3339|http://tools.ietf.org/html/rfc3339> -date and time (a subset of ISO 8601). The example from above -would then be - - my $moonlanding = DateTime.new( '1969-07-16T20:17:00Z' ); # UTC time - -The general form is C<[date]T[time][offset]>, with C<[date]> given as -C<YYYY-MM-DD> and C<[time]> given as C<hh:mm:ss>. The final C<Z> is a short -form for C<+0000>, meaning UTC. (Note that while this form of C<new> -accepts all of C<+0000>, C<-0000>, and C<Z>, the default formatter for -C<DateTime> always expresses UTC as C<Z>.) The general notation for the -C<[offset]> is C<+hhmm> or C<-hhmm>. The time zone of the new object is -assumed to be a static offset equal to the C<[offset]>. The C<[offset]> is -optional; if omitted, a C<:timezone> argument is permitted; if this too is -omitted, UTC is assumed. If the year is less than zero or greater than 9999, -the default formatter will always print the sign. -Finally, the constructor also accepts a C<:formatter> argument. - -With all the above constructors, if you attempt to pass in values that -are outside of the ranges specified in the list above, you'll get an -exception. An exception will also be thrown if the given day (like 31 April -2000 or 29 February 2006) or second (like 23:59:60 on 1 January 2000) -doesn't exist. The same checks are run when you produce an object with -C<clone>: - - my $dt = DateTime.new(:year(1999), :month(1), :day(29)); - say $dt.clone(:year(2000), :month(2)); # 2000-02-29T00:00:00Z - say $dt.clone(:year(1999), :month(2)); # WRONG; 1999 was a common year - -To convert an object from one time zone to another, use the C<in-timezone> -method: - - my $dt = DateTime.new('2005-02-01T15:00:00+0900'); - say $dt.hour; # 15 - $dt = $dt.in-timezone(6 * 60 * 60); # 6 hours ahead of UTC - say $dt.hour; # 12 - -Date calculations are done on the proleptic Gregorian calendar, which means -that we ignore any diurnal upheaval that may have taken place in 1582 and -calculate all dates the same way. The year 1 BCE is represented as 0000 -(a leap year), which adjusts all other BCE dates by one. For example, 5000 BCE -is represented as -4999. - -The C<utc> method is shorthand for C<in-timezone(0)>, and the C<local> -method is short for C<in-timezone($*TZ)>. - -The C<truncated-to> constructor allows you to "clear" a number of time values -below a given resolution: - - my $dt = DateTime.new('2005-02-01T15:20:35Z'); - say $dt.truncated-to('hour'); # 2005-02-01T15:00:00Z - -Arguments to C<truncated-to> is one of the following string values: - - second seconds - minute minutes - hour hours - day days - week weeks - month months - year years - -An argument of C<'week'> to C<truncated-to> yields an object with the date of the last Monday -(or the same date, if it already is a Monday) and with hours, minutes, and -seconds all set to zero: - - say $dt.truncated-to('week'); # 2005-01-31T00:00:00Z - -The C<later> and C<earlier> constructors allows you to move a number of time -units forward or backward in time. - - $dt.later(minutes => 44); - $dt.earlier(week => 1); - -(Both C<later> and C<earlier> accept zero or negative integers, with the obvious -extended semantics.) - -There's one additional constructor: C<now>. It works just like -C<DateTime.new(now)> except that there is no positional parameter and the -C<:timezone> argument defaults to C<$*TZ>. - -=head2 Accessors - -There are methods C<year>, C<month>, C<day>, C<hour>, C<minute>, C<second>, -C<timezone>, and C<formatter>, giving you the corresponding values of the -C<DateTime> object. The C<day> method also has the synonym C<day-of-month>. - -The method C<Instant> returns an C<Instant>, and the method C<posix> -returns a POSIX time. - -The method C<week> returns two values, the I<week year> and I<week number>. -(These are also available through the methods C<week-year> and C<week-number>, -respectively.) The first week of the year is defined by ISO as the one which -contains the fourth day of January. Thus, dates early in January often end -up in the last week of the prior year, and similarly, the final few days of -December may be placed in the first week of the next year. - -There's a C<day-of-week> method, which returns the day of the week as a -number 1..7, with 1 being Monday and 7 being Sunday. - -The C<day-of-week-in-month> method returns a number 1..5 indicating the -number of times a particular day-of-week has occurred so far during that -month, the day itself included. For example, June 9, 2003 is the second -Monday of the month, and so this method returns 2 for that day. - -The C<days-in-month> method returns the number of days in the current -month of the current year. So in the case of January, C<days-in-month> -always returns 31, whereas in the case of February, C<days-in-month> -returns 28 or 29 depending on the year. - -The C<day-of-year> method returns the day of the year, a value between 1 -and 366. - -The method C<is-leap-year> returns a C<Bool>, which is true if and only -if the current year is a leap year in the Gregorian calendar. - -The method C<whole-second> returns the second truncated to an integer. - -The C<Date> method returns a C<Date> object, and is the same as -C<Date.new($dt.year, $dt.month, $dt.day)>. - -The method C<offset> returns the object's current offset from UTC in seconds. -This returns the Int value of C<:timezone>. - -=head1 C<Date> - -C<Date> objects represent a day without a time component. Like C<DateTime> -objects, they are immutable. They allow easier manipulation by assuming -that integers always mean days. - -Days, Months and days of week are 1-based. - -=head2 Constructors - - Date.today(); # today's date - Date.new(DateTime.now); # same - Date.new('2010-12-20'); # YYYY-MM-DD format - Date.new(:year(2010), :month(12), :day(20)); - Date.new(2010, 12, 20); - Date.new(2010, 1, 20).clone(month => 12); - Date.new(2010, 12, 24).truncated-to('week'); - Date.new(2010, 12, 24).later(weeks => 10); - -The constructors die with a helpful error message if month or day are out of -range. - -=head2 Instance methods - -C<Date> objects support all of the following accessors, which work just -like their C<DateTime> equivalents: - - year - month - day - day-of-month - day-of-week - week - week-year - week-number - day-of-week - day-of-week-in-month - days-in-month - day-of-year - is-leap-year - -The C<Str> method returns a string of the form 'yyyy-mm-dd'. - -=head2 Arithmetics - - $d.succ # Date.new('2010-12-25') - $d.pred # Date.new('2010-12-23') - $d - Date.new('1984-03-02') # 9793 # (difference in days) - $d - 42 # Date.new('2010-11-12') - $d + 3 # Date.new('2010-12-27') - 3 + $d # Date.new('2010-12-27') - -=head1 AUTHORS - - Carl Mäsak <cmasak@gmail.com> - Martin Berends <mberends@autoexec.demon.nl> - Moritz Lenz <moritz@faui2k3.org> - Olivier Mengué <dolmen@cpan.org> - Kodi Arfer - (and others named in FOOTNOTE at bottom) - -=head1 FOOTNOTE - -The authors of the current rewrite want to mention, with thanks, the -indirect contribution made by the previous authors: - - The authors of the related Perl 5 docs - Rod Adams <rod@rodadams.net> - Larry Wall <larry@wall.org> - Aaron Sherman <ajs@ajs.com> - Mark Stosberg <mark@summersault.com> - Carl Mäsak <cmasak@gmail.com> - Moritz Lenz <moritz@faui2k3.org> - Tim Nelson <wayland@wayland.id.au> - Daniel Ruoso <daniel@ruoso.com> - Dave Rolsky <autarch@urth.org> - Matthew (lue) <rnddim@gmail.com> diff --git a/S99-glossary.pod b/S99-glossary.pod deleted file mode 100644 index 96338676..00000000 --- a/S99-glossary.pod +++ /dev/null @@ -1,2983 +0,0 @@ -=encoding utf8 - -=head1 TITLE - -Synopsis 99: Glossary - -=head1 VERSION - - Created: 26 June 2013 - - Last Modified: 26 Feb 2015 - Version: 8 - -This document tries to define many of the terms used within the Perl 6 -community. It does not have an L</apocalypse> or L</exegesis -predecessor>. It is intended as both a quick introduction to terms -used on the L</#perl6> L</channel> on L</freenode>, as well as a more -permanent, and deeper source of explanations in the context of Perl 6. - -If you, as a reader, miss a term in a glossary, just add the term with the -explanation. Or if you are not sure what the missing term means, just add a -header for the term. Without doubt, someone else more knowledgeable will add -the explanation later for you and everybody else. - -=head1 A - -=head2 Abstract class - -An abstract L</class> defines the L</interface> of a class. Its L</method>s are left -undefined. In Perl 6, abstract classes is one of the related abstractions implemented as -L</role>s. - -=head2 ack - -An improved version of L</grep>, written in Perl (L<http://beyondgrep.com>). - -Also used by old folks to indicate acknowledgement. - -=head2 actions - -A class used to generate an L</AST> from the results of parsing text with a -L</grammar>. The method to attach a generated AST is called "make", to retrieve -an AST you can call "made" or "ast". See L<S05-regex/Action objects>. - -=head2 advent calendar - -Articles about Perl 6 for every days of December before Christmas. -At L<https://perl6advent.wordpress.com/>. - - -=head2 adverb - -See L<adverbial pair>. - -=head2 adverbial pair - -A generalized form of L</pair notation>. They all start with the colon, like: - - adverbial pair | pair notation - ================|============== - :foo<bar> | foo => 'bar' - :foo(bar) | foo => bar - :$foo | foo => $foo - :foo | foo => True - :!foo | foo => False - -=head2 AFAICS - -As Far As I Can See. - -=head2 AFAICT - -As Far As I Can Tell. - -=head2 AFAIK - -As Far As I Know. - -=head2 afk - -Away From Keyboard. Logged in, but there's no one looking at the screen. - -=head2 ALAP - -As Late As Possible - -=head2 Any - -The class from which most things derive, except for L</Junction>s. -Any is derived from L</Mu>. - -=head2 any() - -A Junction with "or" semantics. - -=head2 API - -Application Programming Interface. Ideally, someone using your system or -library should be able to do so with knowledge only of the API, but not -necessarily knowing anything about the internals or implementation. - -=head2 Apocalypse - -A document originally written by L</TimToady>, in which he processed the -initial barrage of RFC's that came out of the Perl community. Now only kept -as an historical document for reference. See also L</Exegesis> and -L</Synopsis>. - -=head2 arity - -Number of L</operand>s expected by an L</operator>. - -=head2 argument - -=head2 array - -=head2 AST - -Acronym for -L<B<A>bstract B<S>yntax B<T>ree|http://en.wikipedia.org/wiki/Abstract_syntax_tree>. -Used in many places, including L</actions>, L</PAST>, and L</QAST>. - -=head2 atomic - -See L</CAS>. - -=head2 attribute - -Per-object storage slot. Other languages call it "Field", "Member", "Slot" or -"Property". - -=head2 auth - -Way of deliberately ambiguously expressing L</author> or L</authority>. - -=head2 author - -=head2 authority - -=head2 autopun - -"Are you ignorant or apathetic?" - "I don't know, and I don't care." - -=head1 B - -=head2 backlog - -That part of a discussion on an L</IRC> channel that you've missed. If it -is not or no longer available in your IRC client, you can go to sites such -as L<http://irc.perl6.org> to see what has been logged for you. - -=head2 backtrack - -Feature of a combinatorial algorithm which goes back one step toward the -trunk after failing exploring a branch of the potential solution space. A -string match is such an algorithm. Here, backtracking usually means moving -back the L</cursor>. In a non-greedy match, it means moving the cursor -forward. - -=head2 backend - -Denote a VM targeted by L</Rakudo>. Can be L</MoarVM>, L</JVM> or -L</Parrot>. - -=head2 Bailador - -Spanish for "dancer", The Bailador module -(L<https://github.com/tadzik/Bailador/>) is a port of Perl 5's Dancer web -framework (L<http://perldancer.org/>). - -=head2 bare string - -A non-quoted alphanumeric string. In Perl 6, only allowed at the left of a -L</fat comma>. - -=head2 biab - -Back In A Bit. Only L</afk> for a little while. - -=head2 binary - -An operator is binary or of L</arity> two if its L</category> is L</infix> -or L</postcircumfix>. - -=head2 blast - -"B<Bl>ock, B<A>lternatively B<St>atement". Several constructs in Perl 6 -expect either a single L</statement>, or a L</block>. Thus, a blast: - - try { dangerous(); functions() }; - # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Block - try dangerous-function(); - # ^^^^^^^^^^^^^^^^^^^^ Statement - -Particularly cute, because L</phaser>s expect blasts. - -=head2 block - -A source code section delimited by braces and may have an explicit L</signature>. -Used for L</control flow> and as L</scope>. -A L</return> in a block returns from the enclosing L<subroutine>. -A block is a L</first class entity> which makes it useful for L<functional programming>. - -=head2 blorst - -"B<Bl>ock, B<OR> B<St>atement". Different way to say L</blast>. - -=head2 Bool - -L<Boolean|/boolean> type. - -=head2 boolean - -L<Value|/value> of type L</Bool>. Apart the class itself, can be either -C<True> or C<False>. - -=head2 boolean context - -A L</context> that forces an L<expression|/Expression> to give a L</boolean> -value. The L</prefix> L</operator>s C<so>, C<not> and their respective -higher L</precedence> C<?> and C<!> forms force a boolean context with C<!> -and C<not> doing a negation. The L</predicate> part of a L</control flow> -L</statement> forces a boolean context. A class can define a C<Bool> method -to handle the boolean context. For L<natives|/"Native value">, within -L</MoarVM>, it is handled by C</MVMBoolificationSpec> member of the -L</STable> structure. - -=head2 bootstrap - -Starting up a system that uses itself to define, build or compile itself, is -a practical exercise on solving the chicken and egg problem. This phase is -called bootstrap. -L<Documentation|https://github.com/MoarVM/MoarVM/blob/master/docs/bootstrap.markdown> -about bootstrapping the L</6model> of L<MoarVM> - -=head2 bot - -A program that does automatic tasks on one or more L</IRC> channel by acting like a -regular user (as far as the server is concerned) and performing some tasks that -may involve answering to users requests. L</camelia>, L</dalek> and L</yoleaux> -are bots on the L</#perl6> channel. - -=head2 boxing - -Operation transforming a L<native value|/"Native value"> into an object. -The reverse operation is unboxing. The relation between boxed/native should -not be confused with L</container>/containee. - -=head2 branch - -=head2 brb - -Be Right Back. Only L</afk> for a little while. - -=head2 BS - -Bounded Serialization. - -=head2 BSON - -BSON is the binary counterpart to the textual L</JSON> data format. -Used by Mongodb and supported by the -L<MARTIMM/BSON|https://github.com/MARTIMM/BSON/> L</project>. - -=head2 Bug report - -The way to report problems to the implementors. For the interpreters -themselves, use L</RT>. It is good practice to include the interpreter -L</version> in a bug report. A short piece of example code that -demonstrates the bug without requiring any further set-up is usually very -well received, too - see also L</golfing> For the user packages hosted on -L</github>, you can report issues. - -=head2 bundle - -A bundle is a special L</module> that directs L</Panda> to install a list of modules. -See also: L</Task::Star>. - -=head2 bytecode - -Bytecode is to a L</Virtual Machine> what L</machine code> is to a CPU -but, unlike machine code, is portable. From L</source code> L</Rakudo> -can generate bytecode for the L</JVM> and L</MoarVM> virtual machines. -When executing a script, rakudo does not need to compile the used -L</module>s because they should already be available as bytecode -installed by L<Panda>. - - -=head1 C - -=head2 callable - -=head2 caller - -The piece of code (or its lexical environment) that called a given piece of -code. Generally only known at run time. - -=head2 CALLER:: - -A L</pseudo-scope> to access L</symbol>s in the L</caller>'s L</scope>. - -=head2 camel case - -A naming convention where a word boundaries in a multiple word identifier is -indicated with medial capitalization. For example, "isDeeply". Popular in -Java, C++, C#, and Visual Basic. - -See L</kebab case>, L</snake case>. - -=head2 Camelia - -The butterfly-like logo of Perl 6 as can be observed at L<http://perl6.org>. - -=head2 camelia - -The L</bot> on #perl6 channel that will evaluate code for you in various versions of -Perl 5, Perl 6 and L</NQP>. - -=head2 capture - -A regex can record substrings of the L</match>ed string that are matched -capturing parts of the regex. That part (and the matched text) is a capture. - -For example - - if '..42' ~~ / \.+ (\d+) / { - # ^^^^^ capture - say $0; - # ^^ capture variable - } - -C<(I<...>)> is the capture syntax while its non-capturing counterpart is the -grouping syntax : C<[I<...>]>. - -=head2 CAS - -An atomic Compare And Swap. Primitive for lock-free multi-threaded read/write -access. - -=head2 category - -In L</grammar>s, regex of a L</multi> form a category that are distinguished -by their L</longname>. That includes the L<signature> but also the value of -the L</:sym> adverb. An L<expression|/Expression> consists of tokens that -belong either in the category L</term> or one of the L</operator>'s -categories. - -A regex definition for one of the term kinds : - - token term:sym<name> { ... } - -=head2 CFG - -1) Context Free Grammar. -2) see L</Control Flow Graph>. - -=head2 character - -A L</string> is a sequence of characters. Like in Perl 5, there is no -character type in Perl 6 so when someone says a I<character> about a -L</value>, he means a string with one character. In L</Unicode> a -character is called a L</grapheme> and may be composed of many L</codepoints>. -But a string represented in the L</NFG> normalization form proper to -Perl 6 has a codepoint per character. That leads to O(1) performance -for many string operations. Depending on the level of abstraction, the -length of a given string differs. The abstractions are bytes, codepoints and -graphemes and the relevant methods are respectively L<.bytes>, L<.codes>, -L<.chars>. - -=head2 channel - -Short for L</IRC> channel. - -Or a concurrent queue. - -=head2 christmas - -Release date for a Perl 6 implementation. It was a recurring joke because -the year was not specified. But at FOSDEM 2015, TimToady announced that the -target date will be Christmas 2015. - -=head2 circularity saw - -A pun on "circular saw". When bootstrapping a language in terms of itself, -we must rely on circular definitions in various places. Obviously if we -were really to use those circular definitions to implement our language, -we'll just get stuck in an infinite regress. So instead we grab our trusty -"circularity saw" to cut those circular definitions in a spot deep down, -hopefully in a way that the resulting splice will be very difficult for the -end-user to notice in day-to-day use. - -=head2 circumfix - -If a syntactic construct, for example a pair of parentheses, surrounds another -piece of syntax, the surrounding first part is called a circumfix. - - say (2 + 3); - # ^^^^^^^ circumfix - say <a b c>; - # ^^^^^^^ circumfix - -=head2 class - -A basic software structure in L</OOP>. -See the L<Wikipedia entry|http://en.wikipedia.org/wiki/Class_%28computer_programming%29>. - -=head2 CLI - -Command Line Interface, what you see in a Terminal (window). - -=head2 clog - -To L</backlog>. - -Etymology: There is a website C<irclog.perlgeek.de> providing either IRC -logs or IR clogs, depending on how you interpret the domain name. - -=head2 Closure Parameter - -A routine parameter that is a callable with particular constraints on its -own parameters. For example, you may only want to accept callables that -take a C<Str> as their argument: - - sub call-me(&callback:(Str)) { ... } - -Not to be mistaken for L<Subsignatures|/Subsignature>. - -See also L<S06-routines/Closure parameters>. - -=head2 CLR - -Common Language Runtime, as used by Niecza/mono/.NET. - -=head2 codepoint - -=head2 combining mark - -=head2 comment - -Parts of a program intended for user consumption that are not used to -generate code. Beside the C<#> that starts a comment ending with the -current line, Perl 6 supports many syntactic forms for different kinds of -comments. Like inline comments that can be used as L</whitespace>, or -comments that appear after a name declaration that are included in the -L</pod> documentation. - -=head2 compilation unit - -A L</compilation unit> is a set of files or a string that is compiled at -once. It involves the L</serialization> of code and data. - -=head2 compile time - -=head2 compiler - -In a L</dynamic language> like Perl 6, the compiler is also referred to as -L</interpreter>. In simpler dynamic languages like Perl 5, the interpreter -does not go through conceptual phases similar to the one for a compiler of -non-dynamic language, the term compiler is rarely used. - -When transforming L</concrete syntax> to L</bytecode>, the first conceptual -phase is called L<parsing|/parse> and generates a L</parse tree>. Next the -parse tree is transformed into an abstract syntax tree which is a form that -can be optimised. Next the abstract tree is transformed to L</bytecode> in a -L</compilation unit>. Then, this bytecode is executed. Depending on the -type of the data manipulated by the L</program>, bytecode can be transformed -into optimised bytecode or into L</machine code>. These last two operations -are forms of L</JIT>. - -=head2 compiler constant - -A L</variable> with a C<?> L</twigil>. -See L<http://design.perl6.org/S02.html#Twigils> and L<S24|http://design.perl6.org/S24.html>. - -=head2 COMPILING:: - -A L</pseudo-scope> to access lexical L</symbol>s in the L</scope> being -compiled. - -=head2 composer - -A composer is a syntax for defining L</value>s. When values are L</object>s, -their composer is a L</Huffmanization> of a L</constructor> -L<expression|/Expression>. For an example, see the L</fat comma>. - -=head2 compunit - -See L</compilation unit>. - -=head2 concurrency - -Property of simultaneous computations sharing resources. It necessitates -some form of collaboration to guaranty the consistency of the said -resources. Computations are materialized by L</process>es or -L</thread>s. Collaboration involves synchronization primitives -likes mutexes, locks, semaphores. Perl 6 provides high level -abstractions like L</feed>s, L</junction>s, L</hyperoperator>s, -L</promise>s, L</channels> so that the programmer is usually spared -the explicit use of threads and the endless problems they involve. - -Compare with L</parallelism>. -See L<S17-concurrency>. - -=head2 concrete - -An L</object> L</value> is concrete when it is not the L</class> itself. - -=head2 concrete syntax - -=head2 container - -=head2 context - -A context specifies the kind of value expected from an L<expression|/Expression>. -A context may be L</boolean context>, L</numeric context>, L</item context>, -L</list context> or L</hash context>. -Some L</prefix> L</operator>s are used to force the context. - -Context is also information that can affect parsing - -=head2 context variable - -A L</variable> with a C<*> L</twigil>. Used to set up contextual -information that can be shadowed by calls deeper in the L</call -stack>. Heavily used in the Perl 6 compiler because Perl 6 is a very -contextual language, so gathered information affects the parsing. See -L</keyword> for an example. - -See also L</lexotic>, L<http://design.perl6.org/S02.html#Twigils> and -L<S24|http://design.perl6.org/S24.html>. Also called dynamic -variable. - -=head2 control flow - -Without control flow statements, a program's execution would be purely -sequential. A control flow statement generally uses a predicate and -branches to one of its substatements according to the predicate value. - -=head2 Control Flow Graph - -In L</spesh>, a L</dominance> graph generated from L</bytecode> analysis so -that L</Single Static Assignment> can be done. - -=head2 constant - -A L</variable> that has an unchangeable L</value>. - -=head2 constructor - -The OO way to I<construct> an object. L<Composer>s are constructor -L</Huffmanization>s that are available for the most common types like -L</pair>s. - -=head2 CORE:: - -A L</pseudo-scope> to access L</symbol>s of the outermost lexical L</scope>, -definition of standard Perl. - -=head2 CPAN - -Comprehensive Perl Archive Network. A content delivery system for Perl -distributions. - -=head2 credentials - -=head2 CUR - -Short for C<CompUnitRepo>, the type of objects that inhabit C<@?INC>. - -=head2 CURL - -Short for C<CompUnitRepo::Local>, the type of C<CompUnitRepo> objects that -refer to the local file system. - -=head2 CURLI - -Short for C<CompUnitRepo::Local::Installation>. - -=head2 cursor - -=head1 D - -=head2 dalek - -An L</IRC> L</bot> that reports when various projects have been updated. It -used to give L</karma> to those who pushed the changes to the project. - -=head2 DarkPAN - -Perl code in production use at companies that has never been uploaded to -CPAN. As in "how will this change affect the DarkPAN", which can't be -answered because you generally don't have access to that code. - -=head2 dead code - -Code that is never called. For example - - sub f() { - say 42; - return; - # everything below this is dead code, - # because the return; above prevents it from running - say 23; - } - -=head2 debugger - -A piece of software that helps you to track down errors in your software. -It typically allows things like stepping through code, setting breakpoints -and inspecting variables. - -=head2 declarator - -a L</keyword> that introduces a L</symbol> and defines its L</scope> and -L</extent>. Perl 6 declarators are L</has>, L</my>, L</state>, L</our>, -respectively for L<object variable|/object> , L<lexical variable|/lexical>, -<stateful variable|/stateful> and L<package variable|/package variable>. Also -the L</twigil> C</*> in the name of a package or lexical variable sets its -extent to L</dynamic>. - -=head2 destructuring - -=head2 dev - -Either a developer (person), or a development version of a program, or a -branch for development in a repository. - -=head2 DFS - -Depth First Search. See L<also|http://xkcd.com/761/>. - -=head2 dies_ok - -A C<Test> function that succeeds when its argument, a Code object, dies at -run time. See L<S24|http://design.perl6.org/S24.html>. - -=head2 diffy - -An L</operator> that produces a resulting L</value> of a L</type> different -from its L</argument>s. For example, all the comparison operators like C<==> -and C<lt> are diffy (because they produce C<Bool>s), the range operators are -diffy (because they produce ranges), but C<+> and C<~> and C<x> are not -diffy because they (sorta, kinda) emit what they accept. - -The reason we care about operators being diffy or not is that you can -basically only reduce on non-diffy stuff. So C<[+]> makes sense, but C<[..]> -doesn't. (C<[==]> actually does makes sense even though it's diffy, but -that's because it's also chaining.) You also can't make assignment -metaoperators from diffy operators. So C<+=> makes sense, but C<..=> -doesn't. - -=head2 DIHWIDT - -"Doctor, It Hurts When I Do This." Well, stop doing it then. - -=head2 dispatcher - -The piece of code in the runtime that determines which (multi) method or -subroutine to invoke. - -=head2 distribution - -A collection of 1 or more L</compunit>s for installing locally, or for -loading from a remote location. - -=head2 DRY - -Don't Repeat Yourself - -=head2 DSL - -L</Domain specific language>. See L</slang>. - -=head2 Domain specific language - -A special-purpose language used for a particular problem domain. For -instance, some web frameworks (such as L<Dancer|http://perldancer.org/>) use -a DSL so that programmers can write code in terms of routes and actions -rather than lower level details of parsing HTTP requests and generating HTTP -responses. See also -L<https://en.wikipedia.org/wiki/Domain-specific_language> - -=head2 dominance - -See L</Control Flow Graph> - -=head2 DYNAMIC:: - -A L</pseudo-scope> to access contextual L</symbol>s in my or any -L</caller>'s lexical L</scope>. - -=head2 dynamic - -=head2 dynamic language - -=head2 dynamic typing - -=head2 dynamic variable - -the dynamic here is unrelated to the one in L</dynamic typing>. -See L</context variable>. - -=head2 DWIM - -Acronym for "B<D>o B<W>hat B<I> B<M>ean". A programming language designer -motto. - -=head1 E - -=head2 eager - -One of the opposites of L</lazy>. - -=head2 ecosystem - -The L<ecosystem|https://github.com/perl6/ecosystem> is a repository of Perl -6 modules installable by L</Panda>. L</Rakudo *> releases include a tested -subset of the ecosystem. - -=head2 edsel - -Something that intends to please everyone by catering for everybody's taste, -yet in the end pleasing nobody, because nobody is catered for enough. - -=head2 empty list - -A list which contains no value. Denoted C<()>. - -=head2 EPIC FAIL - -An internet expression describing the very dramatic, spectacular or just funny failure of an endeavor. -See the L<relevant Wikipedia entry|https://en.wikipedia.org/wiki/Failure#Internet_memes>. - -=head2 EVAL - -A Perl 6 command that takes a string as an argument and executes its content -as Perl 6 code. - -=head2 exception - -=head2 Exegesis - -A document originally written by L</TheDamian>, in which he tried to explain -the L</Apocalypse>s to the common (wo)man. Now only kept as an historical -document for reference. See also L</Synopsis>. - -=head2 export - -See L</import>. - -=head2 EXPORT - -=head2 Expression - -An expression is a part of a statement that is constituted of operators and -their operands and gives a value. The semantic of an expression may depend -on its L</context>. An expression is all or part of a L</statement>. - -=head2 extent - -The extent is the interval of time a L</first class> entity lives. The -extent is different from the L</scope> of a name. -A L</lexical variable> can be still alive when its name is out of scope if -some reference still exists. - -=head2 Extop - -An extension to the default L</bytecode> L</instruction set> in L</Parrot> -or L</MoarVM>. Used to support L</opcode>s specific to a language. - -=head1 F - -=head2 FAIL - -=head2 FAILBACK - -when available in a class, called when all other attempts by the -L</dispatcher> have failed. - -=head2 fat comma - -Contrary to Perl 5, C<< => >>, the fat comma does not simply separate two -values but makes a L</Pair> out of them. The left value can be a L</bare -string>. This is the only place where Perl 6 accepts a bare string. Example: - - foo => bar - -=head2 fiddly - -Used of an L</operator> that doesn't participate in forming metaoperators at -all. (Because that would be "too fiddly" to get to work, presumably.) C<?? -!!> is such an operator. The method call operator is another. (And hence -C<.=> is actually a special case, not a "real" metaoperator.) List -assignment is also fiddly. (But item assignment is not.) - -No meta in fiddly things. So you can't reduce, negate, reverse, sequence, -cross, zip, hyperify or assignify fiddly operators. - -=head2 FIFO - -L<First In First Out|https://en.wikipedia.org/wiki/FIFO>, a fairly common -data structure in programming languages. In Perl 6 an array behaves as such -when used as a L</queue>. See also L</LIFO>. - -=head2 flap - -Sometimes a test will fail under some conditions, but not others; when this -test passes some test runs and fails others, it's called flapping. - -=head2 first class entity - -An entity that is accessible as a L</value> during L</runtime>. - -=head2 fork - -The creation of another process. - -Also, a feature of L</github> that copies a repository from one user to -another, to allow users to make changes to a repository without needing -permissions on the original project. After a user makes changes they will -likely submit a L</pull request>. - -=head2 FOSS - -Free and Open-Source Software. - -=head2 fossil - -Something in a generally current document that is no longer true but which -has not yet been fixed by correcting or removing it. - -=head2 FP - -Short for L</functional programming> - -=head2 frame - -=head2 freenode - -An L</IRC> server that hosts L</channel>s related to Perl 6 projects accessible -through an IRC client at C<irc.freenode.org>. - -=head2 FSVO - -For Some Value Of. - -=head2 FTFY - -Fixed That For You. - -=head2 fudge - -Way to temporarily mark tests in the L</spectest> for a specific Perl 6 -version as I<todo> (so that a failure of the test will be marked ok, and a -pass will be marked as an exception), or as I<skip> if they cause a -L</compile time> or L</runtime> exception. - -=head2 functional programming - -A programming style that mostly or exclusively relies on functions, L</pure> -or not. Perl 6 supports functional programming but does not force it on -you. - -=head1 G - -=head2 GC - -Garbage collecting. - -=head2 gensym - -A B<gen>erated B<sym>bol. Used primarily in L</macro> parlance, a gensym acts as -a "handle" on something anonymous, allowing a macro author to refer to -synthetically created bits of a program after creating them. Gensyms -generally look ugly, partly so as not to collide with anything else. The -L</symbol>s `#:G847`, `#:G848` and `#:G850` below from -L<http://lists.warhead.org.uk/pipermail/iwe/2005-July/000130.html> are -gensyms: - - (LET* ((#:G847 X) (#:G848 FOO)) - (MULTIPLE-VALUE-BIND (#:G850) 1 (COMMON-LISP::%PUT #:G847 - #:G848 #:G850))) - -Current consensus is that we won't need gensyms for Perl 6 macros, because -we'll have Qtree nodes which, being objects, come pre-equipped with a -"handle": their object identity. - -=head2 GIL - -L<Global Interpreter Lock|https://en.wikipedia.org/wiki/Global_Interpreter_Lock>. - -=head2 gimme - -=head2 gist - -A summary, or a method on objects that is invoked by L</say> to print out -the object in a human readable format. - -Or a paste server with L</git> capabilities used by denizens of -L</IRC>. See L<https://gist.github.com> for the last usage. - -=head2 git - -The distributed source revision system used by many, if not all Perl 6 -projects, generally hosted on L</github>. A good -L<glossary|https://www.kernel.org/pub/software/scm/git/docs/gitglossary.html> -about git. A good L<reference|http://git-scm.com/book>. - -=head2 git submodule - -A way to use a git L<repositories|/repository> from one git repository. -L<More information|http://git-scm.com/book/en/Git-Tools-Submodules> - -=head2 github - -Online open source repository hoster using L</git>. The L</ecosystem> is -hosted on github. - -=head2 given - -Keyword for the Perl 6 switch L</statement>. - -=head2 GLOBAL:: - -A L</pseudo-scope> for L</interpreter>-wide L</package> L</symbol>s, really -UNIT::GLOBAL. - -=head2 GLR - -The Great List Refactor: a refactoring of the reification of lazy lists, so -that lazy evaluation is only done when it is really needed. Expected to -provide a performance benefit of several factors in certain, loop-like -situations. - -=head2 GLRR - -Further Refinement of the L</GLR>. - -=head2 golf - -Shortest possible way (least amount of typed characters) to get a program to -do what you want, or to describe a problem or bug. - -In the case of bug hunting, the aim is only partly "fewest characters" and -partly "fewest concepts". The aim being to show exactly what concepts are -necessary to trigger the surprising behavior. - -=head2 golfing - -The process of creating the shortest possible program to prove what you -want. Sometimes also a form of L</obfuscation>. - -=head2 good * - -Good morning/afternoon/evening. Since the contributors are in many -different timezones, one contributor's morning is another contributor's -evening. - -=head2 gorilla/banana problem - -"You wanted a banana but what you got was a gorilla holding the banana and -the entire jungle." says Joe Armstrong, Erlang creator, complaining of -traditional L</OO> inheritance based environment inflexibility. In non -L</dynamic language>s, you can't dynamically add L</attribute>s/L</method>s -for an L</object>/L</class> so you end up shoving everything you may ever -need in a deep class hierarchy. In Perl 6, the gorilla/banana problem is -solved with L</role>s that group methods or attributes. A role can be -dynamically added to a class or an object. - -=head2 gradual typing - -According to wikipedia I<Gradual typing is a type system in which -variables may be typed either at compile-time (which is L</static typing>) -or at L</runtime> (which is L</dynamic typing>)>. -Perl 6 supports gradual typing. - - -=head2 grammar - -A feature of Perl 6 that uses L</regex>es to implement a grammar for parsing -text. Perl 6 implementations use grammars themselves to parse the language. -The results of parsing with a grammar can be further passed on to -L</actions>. A grammar is composed of methods introduced by one of the -three keywords C<rule>, C<L</token>>, C<regex>. There is L</backtrack>ing -only in C<regex> and C<rule> implies L</whitespace>s between subrules. - -Parsing is done conceptually in two phases, L<lexing> and L<syntax -analysis>. Lexing breaks the input string in tokens that are the -input of L<syntax analysis|/Syntax analysis>. In Perl 6, things are -not so clear cut and both phases are defined in the L</grammar>. - - -=head2 grapheme - -=head2 green threads - -Threads that are scheduled by the virtual machine, not by the operating -system. - -=head2 grep - -Command line utility to search text for lines matching a L</regex>. See -L<http://en.wikipedia.org/wiki/Grep>. - -=head1 H - -=head2 hash - -A data type, conveniently available in variables starting with the percent -sign C<%> and provided by types conformant to the C<Associative> role like -the C<Hash> type. Often called associative table in other languages. - -=head2 hash context - -=head2 heap - -Dynamically allocated memory pool used for memory management. Unused parts are reclaimed -by the L</GC>. See L<Memory management|https://en.wikipedia.org/wiki/Memory_management#DYNAMIC>. - -=head2 High Level Language - -A high level language provides abstractions that decouples it from specific -operating systems and processors. Perl 6 is such a language and provides -some interoperability with other HLLs when they are compiled with the rakudo -toolkit. Some of these abstractions like arrays, associative tables, -integers, floats, strings and objects are common to many languages but -specific semantic and underlying type L</representation>s may differ. Also, -a given language may provide many flavors of them. Perl 6 provides common -L</concrete syntax> to access them. C<MVMHLLConfig> is the L</MoarVM> C -level structure that hooks to the underlying language specific -representations. The L</metamodel> allows one to express specific semantics -proper to a given L</OO> language. L</Rakudo> provides interoperability -with languages which compilers follow C language linking conventions. - -=head2 HLL - -See L</High Level Language>. - -=head2 HN - -Hacker news as seen on L<https://news.ycombinator.com>. - -=head2 HN'ed - -Being mentioned on Hacker news (L<https://news.ycombinator.com>). - -=head2 HOW - -Higher Order Workings. Also the name of the method you can call on -B<any> object to find out the meta-class of that object (of which the -type object of an object is the instantiation). - -=head2 HPMoR - -Harry Potter and the Methods of Rationality. An inexplicably good Harry -Potter fanfic with far more significance than the word "fanfic" might lead -you to believe. See L<http://hpmor.com>. - -=head2 Huffmanization - -L<Huffman coding|http://en.wikipedia.org/wiki/Huffman_coding> is a -compression algorithm that encodes common symbols with a short code. By -analogy, we call huffmanization alternative and shorter syntax for common -syntax constructs. The cost of huffmanization is the cost of learning -additional syntax. In Perl 6, L</composer>s are a form of huffmanization. - -=head2 hyper - -Process data asynchronously when possible, but return the result data in the -order it would have been if the source data had been processed in a single -thread/process. - -=head2 hypothetical variable - -=head2 hysterical raisins - -Pun on historical reasons. - -=head1 I - -=head2 IC - -I see. - -=head2 iffy - -Used of an operator that either returns a C<Bool> result, I<or something -like it> (such as a match object). All the comparison operators are iffy, as -are conditional operators like C<&&>, C<?^>, and C<or>. C<%%> is iffy, but -C<%> isn't. The junctive operators are iffy. - -The reason that we care about iffy operators is that you can only append the -C<!> metaoperator to an operator that's iffy. - -=head2 IIRC - -If I Remember Correctly. - -=head2 IIUC - -If I Understand Correctly. - -=head2 implementation - -=head2 import - -L<Module|/module>s interact with each other through named entities called -symbols. The operation that makes symbols from a module available to -another module is called import while the operation of using such a name is -called import. - -=head2 infix - -An operator that can appear between two terms, like the C<+> in C<40 + 2>. - -=head2 inline - -=head2 install - -=head2 installer - -=head2 Int - -A built-in arbitrary-sized integer type. See L<http://doc.perl6.org/type/Int>. - -=head2 int - -=head2 interface - -An interface is an L</abstract class>. - -=head2 Intermediate Representation - -In a compiler, Intermediate data structures that are generated from the -L</source code> to generate L</object code> or L</bytecode>. In L</Rakudo> -: L</parse tree>, and L<Abstract Syntax Tree|/AST>. The L</parser> -generates an IR that is transformed to an L</AST>. Sometimes the -information can be regenerated from the bytecode. In Rakudo the L</Single -Static Assignment> form is inferred from the bytecode. - -=head2 interpreter - -An interpreter is the entity that executes L</bytecode> generated from -L</source code> in a given L</language>. It relies on the underlying -L</VM>. It may load L<extops>, that is bytecode L</ops> that are -specific to the said language. - - -=head2 instruction set - -An instruction set is a set of instructions specific to a L</bytecode> -or a microprocessor. Also L</NQP> defines an instruction set. Its -opcodes are documented in -L<ops.markdown|https://github.com/perl6/nqp/blob/master/docs/ops.markdown>. - -=head2 invocant - -A L</method> has generally one invocant but may have many according to its -L</signature>. As a L<parameter>(s), the parameters before the C<;>. As an -L<argument>, the left L</operand> of the C<.> L</operator>. In the -L<expression|/Expression> C<42.say>, C<42> is the invocant. When missing, -like in C<.say>, the invocant is C<$_>. - -=head2 invokedynamic - -An L</opcode> that makes possible the support of L</dynamic language>s in -L</JVM>. A L<presentation|http://www.infoq.com/presentations/invokedynamic> -about invokedynamic. - -=head2 IR - -See L</Intermediate Representation> - -=head2 IRC - -Internet Relay Chat. Perl 6 developers and users usually hang out on the -L</#perl6> L</channel> on L</freenode>. See also -L<http://perl6.org/community/irc>. - -=head2 ISTR - -I Seem To Remember. - -=head2 item - -=head2 item context - -=head2 Iterable - -=head2 iteration - -A way to go through all the values of an L</Iterable> object like a L</list> -or a L</hash>. Generally, iterator L</object>s are invisible from user code -because syntactical forms iterate for the user and pass the resulting value -to the expression or the block acting on the value. Example: - - for 1..20 { .say } - .say for 1..20 - -=head2 IWBN - -It Would Be Nice. - -=head1 J - -=head2 jakudo - -L</Rakudo> running on the L</JVM>. - -=head2 JAST - -Intermediate representation of code used in the JVM backend of Rakudo and -NQP. - -=head2 JIT - -L<Just-in-time compilation|https://en.wikipedia.org/wiki/Just-in-time_compilation>, -a technique for improving the performance of virtual machines. - -=head2 JSON - -A popular data format. Its L<specification|http://json.org/> The -ecosystem includes many JSON related L</projects>. Its binary -counterpart is L</BSON>. The class L</JSON::Pretty> is part of the -core. Thre is also support for more JSON and BSON in the L</Rakudo -Star> or the L</ecosystem>. - -=head2 Junction - -A compound type that is transparent to many operations. See -L<http://doc.perl6.org/type/Junction>. - -=head2 JVM - -Java Virtual Machine. The virtual machine for the Java programming language. -Now many programming languages including Perl 6 have L</compiler>s targeting -the JVM. - -=head1 K - -=head2 karma - -A measure of appreciation on L</IRC>. Karma is set by "incrementing" a pseudo: -"jnthn++ # moar commit". It is purely notional on L</#perl6> and other Perl 6 related channels because L</dalek> -does not track karma anymore. - -=head2 kebab case - -A naming convention where a word boundaries in a multiple word identifier is -indicated with a dash (-) character. For example, "is-deeply". Popular in Lisps -and Perl 6. - -See L</camel case>, L</snake case>. - -=head2 keyword - -An alphabetical string that has a predefined meaning in the language -source code. In most languages keywords are reserved, that is they -cannot be used as L</symbol>. Not in Perl 6, the compiler knows by -context if an alphabetical string is a keyword, a L</function> name -used for a call or a sigiless L</parameter>. This will allow to add -new keywords to Perl 6 in the future without breaking existing -programs. - -=head2 KISS - -L<Keep It Simple, Stupid!|https://en.wikipedia.org/wiki/KISS_principle>, a -famous motto in computer science. - -=head1 L - -=head2 lambda - -An anonymous function. A block with explicit parameters: C<< -> $a { say -$a } >> The C<< -> >> itself, or C<< <-> >> for writeable parameter. - -=head2 language - -=head2 lazy - -The property of a list not to evaluate elements until they are needed. - -=head2 laziness - -According to L</WP> "lazy evaluation, or call-by-need is an evaluation -strategy which delays the evaluation of an expression until its value is -needed (non-strict evaluation)". In Perl 6, strings and lists can be lazy -but other values are not. That is, their content is evaluated when needed -so they can be potentially infinite. As of January 2015, lazy strings are -not supported. They may even not make the cut for the 6.0 specification. - -=head2 lexical - -Lexical properties are derived from the structure of the source code itself, -not from any information from run time. - -=head2 lexical pad - -A data structure that holds the values of lexical variables. - -=head2 lexical scope - -=head2 lexical symbol - -=head2 lexing - -=head2 lexotic - -A dynamic operation with a lexically scoped target. For example, C<return> -has a dynamic effect (it peels back the call stack), but the thing it's -returning from is a lexically defined routine. - -=head2 lexpad - -Short for L</lexical pad>. - -=head2 LGTM - -Looks good to me. - -=head2 LHF - -Low Hanging Fruit. - -=head2 library - -The compilation of a L</compilation unit> of source code written in a -non-dynamic language like C results in a library. - -=head2 LIFO - -L<Last In First Out|https://en.wikipedia.org/wiki/LIFO_(computing)>, a -fairly common data structure in computer science. In Perl 6 arrays behave -as such when used as a L</stack>. See also L</FIFO>. - -=head2 line noise - -Used to qualified unreadable code. Often used by people that don't understand -the syntax of the used language. Perl is often deemed line noise, especially -because of its abundance of L</metacharacters>, like L</sigil>s. For the -trained reader, they are very useful because the sigil denote an associated -L</role> - -See L</TheDamian> L</answer|http://www.linuxvoice.com/interview-damian-conway/> -to the question I<Perl looks like a regular expression>. - -=head2 List - -=head2 list context - -=head2 list to remember - -A facet of a language's design that puts the onus on the user to remember -which of a group of similar constructs have certain behaviors (or requires -frequent consultation of documentation to the same effect.) A goal of -language design is to minimize the amount of material a user must remember, -by using consistent behaviors across similar constructs, or by exposing these -behaviors through syntax. A natural language analogy to "list to remember" -would be irregular verb conjugations. - -=head2 lmddgtfy - -Let Me DuckDuckGo That For You. L<http://lmddgtfy.net> - -=head2 LMGTFY - -Let Me Google That For You. L<http://lmgtfy.com/> - -=head2 local - -A local variable, in L</QAST>, is local to a L</frame>. A L</HLL> lexical variable -may end up as local in QAST if it is not captured by outer L</scope>. When the QAST is compiled and L</JIT>ed -to an executable, the value accessible thru the local, modulo some L</SSA> magic, is accessible in a processor -register. There is no relationship with the local scope in Perl 5. - -=head2 LoL - -B<L>ist B<o>f B<L>ist - -=head2 longname - -Because Perl 6 has the capability of L</multiple dispatch>, several methods -or subroutines may have the same name but different parameters (different in -number or in type). Perl decides which routine to call by looking at the -B<longname> which consists of the name of the routine and the type signature -of its invocant arguments. See also L</shortname>, L</multi-method>, and -L</multi-sub>. - -=head2 LTA - -Less Than Awesome. - -=head2 LTM - -See L<Longest Token Matching|http://design.perl6.org/S05.html#Longest-token_matching>. - -=head2 lvalue - -=head1 M - -=head2 machine code - -Code specific to the L</instruction set> of a hardware architecture. Compare -with L</bytecode>. - -=head2 magic variable - -L<Variable|/variable> that has a behavior of its own and that is denoted by -a sigiless name with a non alphanumeric character. Unlike Perl 5 that has a -profusion of magic variables, Perl 6 includes only the magic variables -L</$_>, L</"$/">, L</$¢> and L<$!>. They are L</block> L</scope>d and are implicitly -defined at the beginning of each block. - -=head2 MAIN - -When present, a L</multi>L<sub> that is the entry point of a L</program> L</runtime>. -The code in L</phaser>s intended to run at compile time are executed before MAIN. -Like in Perl 5, a MAIN sub is not necessary. - -=head2 MAST - -L</MoarVM> specific L</AST>. When the Perl 6 L</backend> is MoarVM, L</QAST>, the AST obtained from early stages of -L</source code> L</compilation> is converted into MAST. The MAST is then used to generate MoarVM -L</bytecode>. - -=head2 Match - -L<Value|/value> resulting from a L</match>. -In L</list context>, gives the positional L</capture>s list. -In L</hash context>, gives the named L</capture> hash. -In L</numeric context>, gives the matched string length. -In L</boolean context>, gives C<True> like any non-class object. - -=head2 match - -A match is an operation that tests a L</string> against a L</grammar> or a -L</regex>. and returns an L</object> of L<Match> type in case of success, -otherwise a L</Nil> - -Matching against a C<regex> is a special case of L</smart match>ing. - -See also L</parse>. - -=head2 memory - -=head2 META.info - -A L</JSON> file that lies in the root of a L</repository> for a project written -in Perl 6. It describes a project and list its dependencies. -Documented in L<spec.pod|https://github.com/perl6/ecosystem/blob/master/spec.pod>. - -=head2 metamodel - -The metamodel describes some L<OO> behaviors, like where to find a -L</method>. This permits implementation of different OO behaviors in the -same L</VM>. The Perl 6 implementation of the metamodel is called -L</6model>. The metamodel should not be confused with the -L</representation>. - -=head2 method - -Methods are L</sub>s that are called with an L</invocant>. - -=head2 MI - -Multiple inheritance. - -=head2 mischan - -A case of having put a message on the wrong (IRC) channel. - -=head2 MMD - -See L</multi-method dispatch>. - -=head2 MoarVM - -A virtual machine designed specifically for L</NQP> and its L</MOP>: -L</6model>. A document about MoarVM -L<purpose|https://github.com/MoarVM/MoarVM/blob/master/docs/reveal.md>. -MoarVM has some similarities with the Hotspot VM so you may peruse its -L<glossary|http://openjdk.java.net/groups/hotspot/docs/HotSpotGlossary.html> -for entries missing from the present one. - -=head2 modifier - -It is an L</adverb> that affects the behavior of a L</rule> or a -L</match> The supported modifier for rules are L</:ignorecase>, -L</:ignoremark>, L</:sigspace>, L</:ratchet>, and L</:Perl5>, and their -respective abbreviations C<:i>, C<:s>, C<:r>, and C<:P5>. - -:g :ov :x :ex :pos - -=head2 module - -=head2 MOP - -Meta-Object Protocol. - -=head2 MRO - -Method Resolution Order. - -=head2 Mu - -The mystical class from which all other classes are derived (無). - -=head2 multi - -L</sub>s, L</method>s, or L</rule>s that have the same name but are -distinguished by their signatures. Keyword that introduces them. The -operation that dispatches a call to the appropriate method is called -L</multi-method dispatch>. - -=head2 multiple dispatch - -Dynamically selecting which routine to execute based on name and type of -arguments. - -=head2 multi-method - -=head2 multi-sub - -=head2 multi-method dispatch - -=head2 mumble - -Placeholder; something that's left unclear deliberately. Either because the -speaker doesn't know or because it's an unimportant detail. - -=head2 my - -=head2 MY:: - -A L</pseudo-scope> to access L</symbol>s in the current L</lexical scope> -(aka $?SCOPE). - -=head1 N - -=head2 named parameter - -=head2 namespace - -=head2 native - -Something that does not pertain the Perl interpreter proper but -to the L</backend> or the underlying system. -See also: L</pure Perl> - -=head2 Native Call - -Calling a routine from an external C/C++ library, provided by the -NativeCall library (which is now bundled with L</Rakudo>). - -=head2 Native value - -A native value is an L</int>, L</num>, L</str>. A native value cannot be -undefined. - -=head2 name - -Syntactical convention to denote an entity in a program source code. Such an -entity can be a routine, a variable... See also : L</symbol>, L</scope>, -L</sigil>, L</role>, L</adverbial pair>. - -=head2 NC - -L</Native Call> - -=head2 NCI - -L</Native Call> Interface - -=head2 need - -=head2 NFA - -Nondeterministic Finite Automaton, an algorithmic technique used by the -regex engine. See: -L<https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton>. - -=head2 NFG - -Proposed L</Unicode Normalization Form> for Perl 6, in which composed -characters always get their own codepoint. If a codepoint doesn't exist for -that composed character, one is assigned dynamically. - -Documentation for this can hypothetically be found in L<S15>. - -=head2 Niecza - -An implementation of Perl 6 targeting the .NET platform. - -=head2 Nil - -Means there is no value. This is different from C<()>, the L</empty list>. - -=head2 NST - -No Such Thing. - -=head2 nom - -The name of the main branch of current L</Rakudo> in L</git>. Originally -named so for its "new object model". - -=head2 Normalization Form - -=head2 NPE - -Null Pointer Exception. - -=head2 null-PMC access - -=head2 Num - -=head2 number - -=head2 numeric context - -=head2 NQP - -Short for B<N>ot B<Q>uite B<P>erl, a subset of Perl 6 suitable for tasks -such as implementing L</Rakudo>. Targets L</Parrot>, the L</JVM> and -L</MoarVM>. - -=head2 NSA - -Native, Shaped Arrays. - -=head1 O - -=head2 obfuscation - -Code deliberately unreadable often using esoteric language features. -Sometimes combined with L</golfing>. - -=head2 object - -=head2 object code - -For non L</dynamic language>s, from a L</compilation unit>, the L</compiler> -generates object code or library. A latter phase links object code to -generate an executable. For dynamic languages like Perl 6, the equivalent -of object code is the L</bytecode> and the linking phase is more complex and -involves the deL</serialization> of information. - -=head2 On Stack Replacement - -According to the hotspot -L<glossary|http://openjdk.java.net/groups/hotspot/docs/HotSpotGlossary.html>: -The process of converting an interpreted (or less optimized) L</stack frame> -into a compiled (or more optimized) stack frame. - -=head2 OO - -Object oriented. See L</OOP>. - -=head2 OOP - -Acronym for L<Object-oriented programming|https://en.wikipedia.org/wiki/Object-oriented_programming>. - -=head2 op - -Ops are L</opcode>s that belong to the L</NQP> L<interpreter> or that are -dynamically charged by the interpreter of another language. The word L</extops> -is used to denote the latter ops - -=head2 opcode - -An opcode is an instruction in a L</bytecode> or L</AST>. Documentation about L</MoarVM> -L<opcodes|https://github.com/MoarVM/MoarVM/blob/master/docs/bytecode.markdown>. - -=head2 open source - -=head2 operand - -See L</operator>. - -=head2 operating system - -=head2 operator - -An expression is made of operators and operands. More precisely it is made -of an operator and operands that can be subexpressions or L</value>s. -Operators are an alternative syntax for a L</multi-method>. With that -syntax, what would be the L</argument>s of the function are named operands -instead. Operators are classified into -L<categories|http://design.perl6.org/S02.html#Grammatical_Categories> of -categories. A category has a precedence, an arity, and can be L</fiddly>, -L</iffy>, L</diffy>. Perl 6 is very creative as to what is an operator, so -there are many categories. Operators are made of many tokens, possibly with -a subexpression. For example, C<@a[0]> belongs to the postcircumfix -category, is broken into the operand C<@a> and the postcircumfix operator -C<[0]> where C<0> is the postcircumfixed subexpression. - -The C<< <O(I<...>)> >> construction gives information about an operator -that completes the information provided by its category. Below -C<%conditional> is the category, C<< :reducecheck<ternary> >>, which -specifies calling C<.ternary> to post-process the L<parse subtree|/parse -tree> and C<< :pasttype<if> >> specifies the NQP L</opcode> generated in the -L</AST> from the parse subtree. - - <O('%conditional, :reducecheck<ternary>, :pasttype<if>')> - -=head2 opt - -An optimization, usually in either the context of L</spesh> or L</JIT>. - -=head2 OS - -Operating system. See L<http://en.wikipedia.org/wiki/Operating_system>. - -=head2 OSR - -L</On Stack Replacement> - -=head2 our - -=head2 OUR:: - -A L</pseudo-scope> to access L</symbol>s in the current package (aka $?PACKAGE). - -=head2 OUTER:: - -A L</pseudo-scope> to access L</symbol>s in the next outer L</lexical scope>. - -=head1 P - -=head2 package - -=head2 package manager - -See L</project manager> - -=head2 pad - -See L</lexical pad>. - -=head2 Pair - -The simplest object containing a key and value pair. - -=head2 pair notation - -Way of expressing key/value pairs, using the L</fat comma>, creating a L</Pair> -object, for instance: - - foo => 1 - -Compare with the L</adverbial pair> notation. - -=head2 Panda - -A Perl 6 L</package manager> designed to make it easier to download, compile and install -L</module>s according to the transitive dependencies specified in the -C<META.info> metadata files of said modules. Unlike other L</package -manager>s, panda supports many L</VM>s, namely the three VMs supported by -the L</Rakudo> compiler: L</MoarVM>, L</Parrot> and L</JVM>. The official -set of modules is called the L</ecosystem> according to the L</github> -repository name that contains the module list pointing to their respective -repositories. - -=head2 panda bootstrap script - -=head2 parakudo - -L</Rakudo> running on L</Parrot>. - -=head2 parameter - -In a L</signature>, defines how the corresponding L</argument> is bound when -the L</block>, L</sub> or L</method> with a signature is called. Is often -designated as "formal parameter" in the literature about other languages. A -parameter can be L</positional> or L</named>, either can be L</variadic> or -not. - -=head2 parrakudo - -See L</parakudo>. - -=head2 PARENT:: - -A L</pseudo-scope> to access lexical L</symbol>s in the unit's L<DSL> -(usually L<CORE|/CORE::>). - -=head2 Parrot - -A virtual machine designed to run Perl 6 and other L</dynamic language>s. -Mostly historic. - -=head2 parser - -The parser is the L</compiler> part that transforms the L</source code> into -a L</parse tree>. A parser is specified by a L</grammar>. The code used by -the parser leverages three different engines: the L<expression|/Expression> -parser, a recursive engine, an L</NFA> based engine. L</LTM> is a feature of -the L</NFA> engine. One difference between C<|> and C<||> is that the former -involves an L</NFA>, while the latter involves the recursive engine. That's -why the former is faster than the latter. - -See also L</grammar>. - -=head2 parse tree - -=head2 PAST - -L</Parrot> L</AST>. - -=head2 PAUSE - -Perl Authors Upload SErvice. The place where authors upload their -distributions to L</CPAN>. - -=head2 pb - -Short for "problem". As in "that's not the pb". - -=head2 PBP - -"Perl Best Practices". The book by Damian Conway outlining best practices -when programming Perl 5. - -=head2 PDD - -Parrot Design Document. Numbered documents detailing various parts of the -design of Parrot. - -Could also be used to refer to "Presentation-Driven Development", the -practice of implementing a feature after having submitted a presentation -about said feature. - -=head2 PEG - -Parsing Expression Grammar. See L</grammar>. - -=head2 Perlito - -A L</compiler> project that has frontends for Perl 5 and Perl 6, as well as -multiple backends. - -=head2 phaser - -A piece of code (a L</blast>) that runs at a particular phase in the -program's lifecycle, for example during L<compilation|/compiler> (C<BEGIN>), -the first time a loop is entered (C<FIRST>), or after all regular code has -run (C<END>). - -=head2 PIO - -An implementation specific internal object for doing I/O. Originally a -Parrot I/O object, now a Perl I/O object. - -=head2 PIR - -Parrot Intermediate Representation. - -=head2 PMC - -Parrot Magic Cookie. - -=head2 pod - -B<P>lain B<O>l' B<D>ocumentation, a documentation format understood by Perl -6. See L<S26|http://design.perl6.org/S26.html> for details. - -=head2 pod6 - -Used to specify Perl 6's version of L</pod>, as opposed to Perl 5's. - -=head2 pointy block - -See L</lambda>. - -=head2 POLA - -Principle Of Least Astonishment. - -=head2 POLS - -Principle Of Least Surprise. - -=head2 Positional - -A L</role> denoting an linearly ordered composite data structure that can be -iterated. - -=head2 positional parameter - -=head2 postcircumfix - -An operator that follows a term directly and encloses another term inside it. -For example: - - my $friend = @names[15]; - # ^--^ circumfix - # post--^ - -=head2 postfix - -An operator that comes after the term it belongs to. - -=head2 PPI - -Perl 5 module for parsing, analyzing and manipulating Perl 5 source code. -L<https://metacpan.org/pod/PPI>. - -=head2 pragma - -A pragma is a module which influences some aspect of the compile time or -run time behaviour of Perl. - -=head2 precedence - -The order in which operators bind terms together; tighter precedence -evaluates before looser precedence. See L<S03/Operator precedence> for -details. - -=head2 precomp - -Precompiled L</compilation unit>. - -=head2 prefix - -An operator that comes before the term it belongs to, for example - - say ?42; # True - # ^ prefix operator - -=head2 predicate - -L<Expression|/expression> used in a L</boolean context> by a -L</control flow> L</statement>. - -=head2 precomposed codepoint - -A composite codepoint (that is, formed of many L</codepoint>s), for which -L</Unicode> assigns a codepoint. Thanks to L</NFG>, a composite non precomposed -codepoint (aka a L<synthetic one|/synthetic codepoint>) has its own dynamically -assigned codepoint. - - -=head2 private - -=head2 process - -Basic execution unit in a multitasking operating system. Processes differ -from L</thread>s in the sense that they are directly managed by the -operating system itself. - -=head2 PROCESS:: - -A L</pseudo-scope> to access L</process>-related globals (superglobals) -L</symbol>s. - -=head2 producer - -=head2 program - -=head2 project - -A project is a L</version>ed L</repository>. -It typically contains a C<bin> folder and a C<lib> and C<t> hierarchy. -They respectively contain executable scripts, Perl 6 libraries and tests. -The list of projects is maintained in the L<ecosystem> repository. -The L</META.info> file drives the compilation and installation of the -project by the L</project management software>. - -=head2 project manager - -A L</program> that fetches, compiles and installs L</project>. -L</panda> is such a program. - - -=head2 pseudo-scope - -=head2 pseudo-package - -a L</package> name which meaning is contextual or predefined by the language. -For example C<MY> denotes the current L</lexical scope> and its L</symbol>s -can be listed with C<MY::.keys>. - -=head2 promise - -=head2 proto - -A proto is a generic L</dispatcher> to L</multi>s by the same L</shortname>. - -=head2 proxy - -=head2 PR - -Short for L</pull request>. - -=head2 prove - -Perl 5 script to run tests through a L</TAP> harness. -See L<prove|http://perldoc.perl.org/prove.html>. - -=head2 PSA - -Problem, Solution, Acceptance. - -=head2 PSGI - -=head2 pull request - -A feature of L</github> that's used after a user has L</fork>ed a project -and made changes to it that they wish to have in the main project. - -=head2 pugs - -A Perl 6 implementation in Haskell, led by the efforts of Audrey Tang. The -first truly usable Perl 6 implementation, it was actively developed 2005 -through 2007. - -=head2 punctuational variable - -Another name for L</magic variable>. - -=head2 pun - -When a role is used as a class, punning is the implicit operation that -converts the role to the class using the metaclass compose method. In -a wider, non-Perl 6 context, it can refer to any implicit conversion. - -=head2 pure - -A L</function>, L</method> or L</op> is pure if it has no side effect, -and the value it gives is depends only of its arguments so it is -L<referentially transparent|/referential transparent> giving the opportunity -of optimizations. - -=head2 pure perl - -Use to qualify Some source code, or L</project> that does not depend -on non Perl resources like a L</shared library> generated from C code. - -=head2 p5 - -Short for Perl 5, the (older brother|parent) of Perl 6. - -=head2 p6 - -Short for Perl 6, the (spunky little sister|child) of Perl 5. - -=head2 P6W - -See L</Weekly Changes>. - -=head1 Q - -=head2 QAST - -Successor to L</PAST>. - -=head2 queue - -=head1 R - -=head2 race - -Process data asynchronously when possible, and don't care in which order the -result data is returned. - -=head2 Rakudo - -An implementation of Perl 6 originally targeting L</Parrot>, it now targets -Parrot, the L</JVM>, and L</MoarVM> through L</NQP>. - -=head2 Rakudo * - -Rakudo Star, a useful and at most monthly, at least quarterly distribution -of Rakudo which includes modules and L</Panda>. - -=head2 R* - -See L</Rakudo *>. - -=head2 rakudobrew - -Quick and dirty command line tool for managing L</Rakudo> -installations on Unix boxes. It can fetch the latest code from L</github>, build against -your choice of L</backend>s, and simplify version upgrades. - -Definition adapted from from L</http://iinteractive.com/notebook/2015/06/02/rakudobrew.html>. - -=head2 Rakudo Star daily - -Daily build reports on rakudo-star to track module tests on each L</backend>. -Its L<README|https://github.com/coke/rakudo-star-daily> - -=head2 rakudobug - -A bug in L</Rakudo>. Usually used in contexts such as "/me submits -rakudobug". - -=head2 range - -=head2 referential transparency - -=head2 regex - -Short for B<Reg>ular B<Ex>pressions, an easy way of parsing text for certain -kinds of information. - -=head2 regexp - -An alternative abbreviation of L</regex> that usually occurs in non-Perl 6 -contexts. - -=head2 reification - -Certain composite objects like L</range> are defined in the abstract. They -are partially or totally reified on demand, that is, their composant objects -are created only when they are needed. Without that laziness, some objects -would consume too much L</memory> or would not even fit in memory like the -infinite L</range>: C<1..Inf> See also L</laziness>. - -=head2 reify - -=head2 REPL - -Read Eval Print Loop. Read a line of code, evaluate, print, wait for new -line of code. Commonly used to experiment with code and get results whenever -a line is finished. - -=head2 repository - -A repository contains the information pertaining to a software or its -L</module>s. That is the source code, its history and ancillary information -like a wiki, a bug tracking system, a static web site, depending on the -hosting service containing the repository. Usually Perl 6 related -information is stored in L</github> repositories. The official list of Perl -6 modules is the L</ecosystem> which is also stored in a repository. When -installing a module, the L</panda> L</package manager> uses the ecosystem to -fetch the appropriate repositories for transitive dependencies. - -=head2 REPR - -Representation. - -=head2 representation - -In MoarVM, low level C code associated to a data type. Typically an NQP call -for a type translates into a MoarVM instruction (opcode) that calls a -function in the representation table of that type. - -=head2 require - -Require is the L</runtime> loading of a L</module> and the related L</import>s - -=head2 revert - -Revert is L</git> terminology. It adds a new commit to revert some changes in -a branch. It is different from a reset that throws away changes. - -=head2 roast - -The Perl 6 L<specification tests|/spectest>, which live here: -L<https://github.com/perl6/roast/>. Originally developed for L</pugs>, it -now serves all Perl 6 implementations. Why roast? It's the B<r>epository -B<o>f B<a>ll B<s>pec B<t>ests. - -=head2 role - -A role can be composed with zero or more other roles, then instantiated into -a L</class>. The L</sigil> of a variable name indicates that the defined -value in the container denoted by the variable belongs to a class composed -from the associated role. For example, the sigil C<@> denotes the -C<Positional> role. So a variable C<@a> may contain a value of type C<List> -because C<List.does(Positional)>. - -=head2 RC - -1) Release Candidate, a last chance to find terrible bugs or -non-portabilities before the actual release. - -2) L</Rosetta Code> - -3) Request Context. - -=head2 reposession - -In precompilation, if an object inside a module, changes an object in another -precompiled module, it needs to indicate that it is now responsible for its -serialization: this is called "repossession" of the object by the module. - -=head2 Repository - -=head2 Root Object - -See L<root object|http://en.wikipedia.org/wiki/Tracing_garbage_collection>. -In L</MoarVM>, routines that handles roots are declared -L<here|https://github.com/MoarVM/MoarVM/blob/master/src/gc/roots.h>. - -=head2 Rosalind - -L<Rosalind|http://rosalind.info/> is a platform for learning bioinformatics -and programming through problem solving. Some of the problems are solved -through elegant Perl 6 code snippets. - -=head2 Rosetta Code - -L<Rosetta Code|http://rosettacode.org>, a site for comparing snippets from -different languages in how they solve various tasks. - -=head2 RPA - -Resizable L</PMC> Array. - -=head2 RSN - -Real Soon Now. - -=head2 RT - -Request Tracker (L<http://rt.perl.org/>). To open a ticket, email> -C<rakudobug@perl.org>. - -=head2 rule - -=head2 runtime - -=head1 S - -=head2 sanity test - -A test for a basic feature that robs your sanity if it doesn't work, and the -fact that it doesn't work goes unnoticed. - -=head2 say - -=head2 SC - -A L</serialization context> groups together things, usually from the same -L</compilation unit>. - -=head2 scalar - -=head2 scope - -Association of a name with an entity delimited by a L</block>. - -=head2 script - -A L</program> executable in its L</source code> form. Implicitly depends -on the C<setting> or explicitely L</use> L</module>s from the -L</ecosystem> - -=head2 segfault - -See L</segmentation fault>. - -=head2 segmentation fault - -Something that should never, ever happen. Complain on #perl6 if you see one. - -=head2 self-clocking code - -=head2 semicolon - -A L</character> used to separate or terminate L</statement>s. - -=head2 serialization - -The serialization saves information obtained at compilation time from a -L</compilation unit> to be deserialized at load time to perform various -initialization tasks. The saved information involves named constants, -strings, among many other things. - -=head2 serialization context - -=head2 SETTING:: - -A L</pseudo-scope> to access L</lexical symbol>s in the unit's L</DSL> -(usually CORE). - -=head2 setting - -Library set that is loaded by default. When possible, the setting is loaded -lazily to optimize loading time. - -=head2 shared library - -L</operating system> level L</library> dynamically loaded by a L</process>. -When different processes load the same library, it is loaded once in memory, so -the shared adjective. - -=head2 shortname - -The name of a routine only; without the type signature of its invocant -arguments. See L</longname>. - -=head2 sigil - -In Perl, the sigil is the first character of a variable name. It must be -either C<$>, C<@>, C<%>, or C<&> respectively for a scalar, array, hash, or -code variable. See also L</twigil> and L</role>. Also sigilled variables -allow short conventions for L<variable interpolation> in a double quoted -string, or even C<postcircumfix> L<expression|/Expression>s starting with -such a variable. - -=head2 signature - -A signature is used by L</block>s, L</sub>s or L<L/methods> to specify the L</arguments> they -can receive when they are called. - -=head2 Single Static Assignment - -=head2 sink context - -L<Context|/context> of an expression whose value is ignored. Often called -"void" context in other languages. - -=head2 sixplanet - -L<sixplanet|http://planeteria.org/perl6/> is a collation of blogs related to -Perl 6. If planeteria.org is down, a replacement can be found on -L<http://pl6anet.org/>. - -=head2 slang - -Short for sublanguage. A slang is a L</grammar> derived from the Perl 6 -grammar, and its associated L</actions>. Alternatively the Perl 6 syntax -can be seen as the combination of many slangs (the regex slang, the -quotation slang...) Defining a slang has a cost because it usually involves -generating new L</NFA> tables; except for the space taken by the said -tables, it is compilation time cost. Slang is a principled way to create -Domain Specific Languages (DSLs). - -=head2 smart match - -=head2 snake case - -A naming convention where a word boundaries in a multiple word identifier is -indicated with an underscore (_) character. For example, "is_deeply". Popular -in Perl 5, Python, and other scripting languages. - -See L</camel case>, L</kebab case>. - -=head2 SMOP - -Small/Simple Matter Of Programming. The thing you do when not specifying, -documenting, discussing, lurking or idling. See also -L<here|http://en.wikipedia.org/wiki/Small_matter_of_programming>. - -=head2 slurpy - -A parameter that will "slurp up" any excess named or positional parameters -and present them as a hash or list respectively. - -=head2 slushy - -A specification that has frozen chunks in it, but remains frustratingly -fluid. Ranges from S02 and S03 which are nearly frozen, to S16 which is -more like a glass of ice water. - -=head2 source code - -Textual form of a L</program>. - -=head2 spectest - -Alternative name for L</roast> after the name of its target name in -L</rakudo compiler>. A program that passes the Perl 6 L</test suite> -is a valid Perl 6 L</compiler>. -L<Link|https://github.com/perl6/roast> to the L</github> -L</repository> that contains the said test suite. - -=head2 special variable - -Variable with one of the L</twigil> C<?>, C<*> or C<=>; or L</magic variable>. -The said twigils respectively correspond to L</compiler constant>s, L</context variable>s -or L</pod> data. - -See L<S28|http://design.perl6.org/S28.html>. - -=head2 spesh - -A functionality of the L</MoarVM> platform that uses run-time gathered data -to improve commonly used pieces of L</bytecode>. It is much like a L</JIT> -compiler, except that those usually output L</machine code> rather than -bytecode. - -=head2 splat - -=head2 SSA - -See L</Single Static Assignment>. - -=head2 stack frame - -See L</frame>. - -=head2 STable - -Representation independent data structure associated with the type of an -object. Part of the L</6model>. See -L<http://jnthn.net/papers/2013-yapceu-moarvm.pdf>. - -=head2 stage - -Can denote steps either on bootstrapping NQP, or compilation stages. - -For bootstrapping stages, see L</bootstrap>. - -Compilation proceeds on successive stages. Later stages are -L</backend dependent>. When there is a dumper available, you can see -the output of one stage with the switch C<--target=I<stage_name>>. -The argument is case insensitive. The backend independent stages are -C<parse> and C<ast>. The L</JVM> backend specific states are C<jast>, -C<classfile>, C<jar>, C<jvm>. For L</MoarVM>, they are C<mast>, -C<mbc>. C<moar>. - -=head2 star - -See L</Rakudo *>. - -=head2 stash - -=head2 state - -=head2 statement - -=head2 static frame - -Data pertaining to a L</frame> gathered at compile time. - -=head2 static typing - -In a language with stating typing, at L</runtime>, values don't need -to be annotated with their type. -See L</type erasure>. - -Compare with L</dynamic typing>, L</gradual typing> - -=head2 STM - -Software Transactional Memory. - -=head2 Str - -Name of the string type. - -=head2 string - -A sequence of characters. See L</characters> for the definition of -string length according to the different abstractions underlying a -L</Unicode> string. There is some speculation of string being -L</lazy> in some future Perl 6 version. - -=head2 sub - -Short for subroutine. - -=head2 Subroutine - -A subroutine is like a L</block>, but its L</runtime> context is stacked. -When a subroutine is called, its context is pushed in the context stack -and the code pointer moves to its block. When executing a return, the context stack -is popped and the return argument becomes the value of the calling expression. - -=head2 Subsignature - -Similar to destructuring bind in Lisp, pattern matching in Haskell/the ML -family of languages. - -Allows you to specify a construction pattern in place of a normal parameter; -the argument supplied at call time will be used to populate variables in the -pattern. For example: - - sub quicksort (@data, $reverse?, $inplace?) { ... } - -versus - - sub quicksort ([$pivot, *@data], $reverse?, $inplace?) { ... } - -See L<S06-routines/"Unpacking a single list argument">, -L<S06-routines/"Unpacking tree node parameters">. - -Not to be confused with L<Closure parameters|/"Closure Parameter">. - -=head2 supply - -=head2 symbol - -Fancy alternative way to denote a name. Generally used in the context of -L</module>s linking, be it in the L</OS> level, or at the Perl 6 L</VM> level -for modules generated from languages targeting these VMs. The set of -L</import>ed or exported symbols is called the symbol table. - -=head2 :sym - -=head2 Synopsis - -The current human-readable description of the Perl 6 language. Still in -development. Much more a community effort than the L</Apocalypse>s and -L<Exegeses|/Exegesis> were. The current state of the language is reflected -by L<roast>, its L</test suite>, not the synopses where speculative material -is not always so flagged. This is even more true of material that is deemed to -pertain to 1.0 version of the language but has not been yet implemented. - -=head2 syntax analysis - -See L</parser>. - -=head2 Syntax sugar - -See L</Huffmanization>. - -=head2 synthetic codepoint - -A L<codepoint> for a L</grapheme> composed of many L</codepoint>s that has not a -</precomposed codepoint> defined by L</Unicode>. L</NFG> dynamically assigns its own -codepoint for such a composition. - - -=head1 T - -=head2 tail call - -=head2 TAP - -L<Test Anything Protocol|http://en.wikipedia.org/wiki/Test_Anything_Protocol>. - -=head2 Task::Star - -A L</bundle> that directs L</Panda> to install L</Rakudo *> L</module>s. - -=head2 TCO - -L<tail call> optimization. - -=head2 term - -=head2 test suite - -The Perl 6 test suite is L</roast> - -=head2 ASCII operator - -The ASCII variant of a non-ASCII Unicode operator or symbol. -For instance, C<<< >>+<< >>> is the -"ASCII" form of the C<»+«> hyper-addition operator, and C<(elem)> -corresponds to the C<∈> ("Is this an element of that set?") operator that -comes from set theory. ASCII operators are a workaround to the problem that -people don't know how to type Unicode yet. Culturally, while we encourage -people to use the Unicode symbols in a vague sort of way, we do not -disparage the use of the ASCII variants. Well, maybe just a little... - -=head2 TheDamian - -L</IRC> screen name for Damian Conway, writer of the original -L<Exegeses|/Exegesis>. - -=head2 thinko - -A thinkographical error; i.e. a small mistake made by improperly expecting -code to L</DWIM> or from an interrupted thought process. - -=head2 thread - -An execution unit more lightweight than a L</process>. Threads allow -parallelization of code for concurrent performance but it is tricky to -modify information shared by the different threads of a process. Perl 6 -provides many primitives that create threads when needed so direct thread -use is possible but should be done only when necessary. - -=head2 thunk - -A piece of code that isn't immediately executed, but doesn't have an -independent scope. - -Examples for thunks: - - my $a; - $a = 1 if 1; - # ^^^^^^ thunk - - class MyClass { - has $.attr = 42 + 23; - # ^^^^^^^ thunk - - method x($attr = say 42) { - # ^^^^^^ thunk - } - } - - $a = 1 || say 2; - # ^^^^^ thunk - -=head2 TimToady - -L</IRC> screen name for Larry Wall, creator of Perl. The name comes from the -pronunciation of L</TMTOWTDI> as a word. - -=head2 TIMTOWTDI - -An alternative form of L</TMTOWTDI>, explicitly including the "is" from -the contraction "There's". - -=head2 tl;dr - -L<Too Long; Didn't Read|http://en.wiktionary.org/wiki/TL;DR>. Also denotes -a summary for those who are prone to claim tl;dr. - -=head2 TMI - -Too Much Information. - -=head2 TMTOWTDI - -"There's More Than One Way To Do It", the Perl motto. - -=head2 token - -A token is a keyword that introduces a lexing L</rule> in a grammar - -=head2 topic - -Expression whose value is aliased to L<$_>. - -=head2 trait - -=head2 TTIAR - -Two Terms In A Row. A common error message often resulting from a missing -L</semicolon> between two L</statement>s or putting an operator directly -after a L</sub>. - -=head2 tpyo - -Typo. - -=head2 tuit - -The mystical unit of effort in the open source community. Sometimes -materialized in wooden nickels. - -=head2 twigil - -A secondary L</sigil>. For example, C<%*ENV> has a sigil of C<%> and -a twigil of C<*>. - -See L<http://design.perl6.org/S02.html#Twigils> and L<S24|http://design.perl6.org/S24.html>. - -=head2 type - -The type of a value C<$val> can be obtained using C<$val.WHAT> which the corresponding -type object. When a value is L<native|/native value>, the <.WHAT> macro operates on the -corresponding L<boxed|/boxing> value. - -=head2 type erasure - -Type annotation for a value of L</static type> is unnecessary at L</runtime> -The absence of that annotation at compared to L</compile time> is called type -erasure. - -=head1 U - -=head2 UAX - -Unicode Standard Annex. Unicode standard material that is not part of the -core. Some are specific to some languages while others are generic, like -L<UAX 15|http://www.unicode.org/reports/tr15/> which covers L</Unicode -Normalization Form>s. - -=head2 UCD - -See L</Unicode Character Database>. - -=head2 unboxing - -See L</boxing>. - -=head2 unspace - -A way to put L</whitespace> in your code that is ignored by the parser. -Introduced with a backslash. - -=head2 ufo - -See L<here|https://github.com/masak/ufo/>. - -=head2 UGT - -"Universal Greeting Time" - i.e., it's always "morning". - -=head2 unary - -An operator is unary if its L</arity> is one. Operators belonging to the -L<categories|/category> L</prefix>, L</postfix> and L</circumfix> are unary. - -=head2 Unicode - -Unicode is a standard defining the encodings, representation and handling of -text in most writing systems. This standard includes a useful L<Unicode -glossary|http://www.unicode.org/glossary/>. For Perl 6 handling of Unicode, -see the -L<documentation|https://raw.githubusercontent.com/perl6/specs/master/S15-unicode.pod>. -See also L</NFG> for an encoding specific to Perl 6. - -=head2 Unicode Character Database - -It consists of a number of data files listing Unicode character properties -and related data. It also includes data files containing test data for -conformance to several important Unicode algorithms. See -L<also|http://www.unicode.org/ucd/>. - -=head2 Unicode Normalization Form - -See L</UAX> L<15|http://unicode.org/reports/tr15/>. -Perl 6 defines an additional one : L</NFG>. - -=head2 unit - -See L</compilation unit>. - -=head2 UNIT - -Symbols in the outermost lexical scope of a compilation unit. - -=head2 unmanaged size - -The amount of memory a L</REPR> has behind it that is not under -the direct management of the L</GC>. Used for L</heap> profiling. - -=head2 unslushing - -See L</slushy>. - -=head2 use - -Use is the compilation time loading of a L</module>. That means, -contrary to L</require> that the L</import>ed L<symbols> are known at -compilation time to the rest of the compilation of the code - -=head1 V - -=head2 value - -=head2 variable - -A variable is a name for a L</container>. - -=head2 variable interpolation - -See L</sigil> and L<S02/Q forms>. - -=head2 variadic - -=head2 ver - -Short way to indicate L</version>. - -=head2 version - -Can be obtained with C<I<perl6 -v>> with I<perl6> depending on your -L</implementation>. This command gives something like that below for -L</Rakudo> on L</MoarVM> - - This is perl6 version 2014.08-187-gdf2245d built on MoarVM version 2014.08-55-ga5ae111 - -Strangely the L</NQP> related information is missing. - -=head2 visibility - -An L</object variable> declared with the L<!> L</twigil> can be in scope but -is not visible. - -=head2 Virtual Machine - -A virtual machine is the Perl compiler entity that executes the -L</bytecode>. It can optimize the bytecode or generate L</machine code> -L<Just in Time|/JIT>. Such as L</Parrot>, L</JVM> and L</MoarVM>. - -=head2 VM - -See L</Virtual Machine>. - -=head2 v5 - -Stands for "Perl, version 5" and is used in code to indicate that the code -is Perl 5: - - use v5; - -=head2 v6 - -Stands for "Perl, version 6" and is used in code to indicate that the code -is written in Perl 6: - - use v6; - -=head1 W - -=head2 warnocked - -This lemma will never be explained. - -=head2 WAT - -L<https://www.destroyallsoftware.com/talks/wat>. Often used as the opposite -of L</DWIM>. - -=head2 Weekly Changes - -Mostly weekly L<report|http://p6weekly.wordpress.com/> about changes in the -Perl 6 World. See also: L</sixplanet>. - -=head2 wfm - -Works For Me. - -=head2 Whatever - -L<http://doc.perl6.org/type/Whatever>. - -=head2 whitespace - -The negative space between syntactic constructs within a language. -Typically consists of spaces, tabs, newlines, form feeds, and other -"invisible" characters. For the purposes of parsing Perl 6, L</comment>s are -also considered whitespace. See also L</unspace>. - -=head2 WIP - -Work In Progress. - -=head2 world - -The world is the data about a package that is serialized when -compiling a L</compilation unit>. -the nqp and rakudo compiler have a World class handling the said data. -See L<NQP::World|https://github.com/perl6/nqp/blob/master/src/NQP/World.nqp> and -L<Rakudo::World|https://github.com/rakudo/rakudo/blob/nom/src/Perl6/World.nqp>. - - -=head2 WP - -Wikipedia. - -=head2 ww - -Short for C<wrong window>. When on IRC, someone types something in a -channel that was intended for another channel, or for a private message. - -=head1 X - -=head2 XS - -Perl 5's mechanism for bridging the gap between pure-Perl code and compiled -system libraries. Writing XS modules involves C code and some knowledge of Perl -5's inner workings, and installing them needs a compiler. The Perl 6 equivalent -is C<NativeCall>; see L<S21|S21: Calling foreign code>. - -=head2 XY Problem - -Sometimes people want to achieve X, and think Y is the best way to do it. So -they ask "How do I do Y?", but doing Y is actually harder or less idiomatic -than solving X some other way. So the person asking how to do Y has an XY -problem. - -=head1 Y - -=head2 YAPAE - -Yet Another Potentially Awkward Explanation. -A term referring to the L<"curious corners"|https://perl6advent.wordpress.com/2014/12/04/composers-coercers-and-the-case-of-a-camels-curious-corner/> -of any given language, specifically the kind of example (mis)features of a -programming language which are thrown by various sides in a flame war. - -These examples are understood to be places where the actual design choices -of a given language become visible. - -=head2 yoleaux - -The L</bot> on #perl6 that is your personal assistant. -See L<https://github.com/dpk/yoleaux> and L<http://dpk.io/yoleaux>. - -=head2 YOU_ARE_HERE - -=head1 Z - -=head2 Zavolaj - -Zavolaj was a module to support L</Native Call>s into L<libraries|/library>. -It is now part of L</Rakudo> - -=head2 Zen slice - -A Zen slice is a slice of an object without specification of the elements. -As such it is empty, yet it is supposed to return the object in its -entirety. Usually used as a way of interpolating entire hashes / arrays in -strings. - -=head1 * - -Oh, um... L</Whatever>. - -=head2 #perl6 - -L</IRC> L</channel> on L</freenode> that hosts discussions related to Perl 6. -Archived on L<http://irclog.perlgeek.de/perl6/>. - -=head2 . - -=head2 .. - -=head2 ... - -=head1 : - -Everybody wants the colon. - -=head2 :ignorecase - -=head2 :ignoremark - -=head2 :ratchet - -=head2 ? - -=head2 ( - -=head3 () - -See L</empty list>. - -=head2 * - -=head2 @_ - -The Perl 5 style argument list. Something you should stop using, and use -subroutine signatures instead. - -=head2 $_ - -The "topic variable". Set by any construct that's a "topicalizer", like the -L</given> statement or a for loop. - -=head2 $/ - -A L</magic variable> which L</value> is the current L</Match>, or L</nil> -if none. - -=head2 $¢ - -L</cursor> - -=head2 $! - -A L</magic variable> which L</value> is the current L</Exception> - -=head2 %_ - -=head2 ++ - -Way to increase L</karma> on IRC. -A L</prefix> or L</postfix> incrementation L</operator>. - -=head2 & - -L<Sigil|/sigil> of a L</callable> L</variable>. Also used at the end of a -line in an L</IRC> message to indicate the user is away, doing something -else in the background. For instance: - - sleep& - -=head2 6model - -The "new object model"/L</MOP> that's currently in rakudo. L</MoarVM> uses -this internally. On L</Parrot> and L</JVM>, it sits on top of the native object -model. - -=head1 AUTHORS - - Elizabeth Mattijsen (liz@wenzperl.nl) - Moritz Lenz - Larry Wall - -=for vim:set expandtab sw=4: diff --git a/html/hilite-full.png b/html/hilite-full.png deleted file mode 100644 index f400dd4e657137e5efcd3006d45cd23a2b2cb185..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 588 zcmV-S0<-;zP)<h;3K|Lk000e1NJLTq000&M000&U1^@s6#I$TX00006VoOIv0RI60 z0RN!9r;`8x00(qQO+^RS0vQw{7Tk9=p8x;>?ny*JR5*>bl)sAGKoG{iSzWLXn^*xg zM%Yha1SWYF7YUdo2loPL@(5|ty0AGo(&TMY8TT%1s|+!Tk@nA|xa=bB?drH91A}HI z_P5`DJ1gKn1=(V~UVjlnd`gn!iijYkgi;Dp%3%86wAM-p@pZG=d~U6<TCJ2ZhMTFi zcBzzNr4&mkUDkEYbzO5+Ra{jSFPBSYc~`bD#v}l+-|s<0==FM#QiAAVQ~uMBEXy3D z1=d=-iJ|O*Gjr?N0xR{f3n2uE2to+Fkl#?2WmF{qjK^b`{)cWbGq)7li9R?s?o>=f zxLhvi_xoTXlw}!&H5V2_004|J-QeMH=xSfF?=v$4|LP!EO6jby6Z!fhcDr5F0sttA z!qri5NY!jM>+FzbM?|e?9v%_l$Di*wole08^E`L&-wfY9t=RX|0{m`iDz=Ab??Tjy z^ZAS{%kX;e7TfJMXn~FSeBNraPAk$hb&#ScT9?N6Is}a>wqE_ZyTkE#3|cgqOx*a@ z?QJ(Ww0fTB4r;w@sy4<1+wjo^@#Anf1h4RPI(@X0sA4}}-rOJ+BI+>_ftjB?Jk89> zXf$$4Vh7`^Z&>B}&4LHae7{&M-Zy{N&j}%fX6AbU0|3992K4}>0ImT%7p?(Z0Q>|{ a0l;6PtUSy5o%xgi0000<MNUMnLSTZ#kqXQJ diff --git a/html/hilite-small.png b/html/hilite-small.png deleted file mode 100644 index 018bbb405d96b3111c6938328bbcd25d6afc2a28..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 450 zcmV;z0X_bSP)<h;3K|Lk000e1NJLTq000mG000mO1^@s6AM^iV00006VoOIv0RI60 z0RN!9r;`8x00(qQO+^RS0vQw{7Tk9=p8x;>WJyFpR5*=&lCf^$KoEw%9r;jn;b=$! zMmzy7(Diu>nlwm3Y0}=q(D+28>+&|K5IqHmHqGs>*K@^b9dB$h(#X4#=i6_8+W?eh z`CCLbS(X{^J<d6-wK(UltyM&JWm!G}u-$G$UDp~rgrFe=t*T0^s#5R0dhgXar`B4v z*6Mn_4geWI2tfdj$0Np=q=DucYdjt|GZ}#Q9)NHD50}fOcPQ3$It6~Asw4na#Tdh6 zGHC$U41g{GpuTzJa5#K9SQN$ockB8C;GAm=7K=qEhc+;t970F|0B?U^IiJs+liT~* zY{vcVQx^~o@;nDXL^@fttJmP?_Xqa-eKPntkL7atbp}OIAR<X$vuFVEE4=S^oKB}+ z^|+qT=iEI%rvPhhlWv~piGJI_7}KaHfSAFL&8DN@Zut0t5<m!{R#h2|M!olJSG<ad s)D2)T7`&`js}0bfRJU|E9KHbj1A>ItGL+7HBLDyZ07*qoM6N<$f&f#)^8f$< diff --git a/html/index.html b/html/index.html deleted file mode 100644 index cf0296fa..00000000 --- a/html/index.html +++ /dev/null @@ -1,410 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> -<head> -<meta charset="UTF-8" /> -<title>Perl 6 Design Documents - - - - - - - - - - - - -
- - camelia perl bug logo - -

Perl 6 Design Documents

- -
-
- - - - - - -
- -
-

The Synopsis documents are the design documents used to guide Perl 6 language, compiler, and test development. As design documents, they're frequently subjected to the rigors of cross-examination through implementation and use in practice. In other words, they may change slightly or radically, but the expectation is that they are ``very close`` to the final shape of Perl 6.

- -

In the past the Synopses have often been referred to as "the formal Perl 6 specification" and "specs", but this usage is being deprecated in favor of treating tests from the "roast" test suite as official specifications. This is consistent with Synopsis 1, which says "Perl 6 is anything that passes the official test suite." -

- - - - - -
-
, it means -find the Ith occurrence. Use C<:nth(3)> for the general form. So - - s:3rd/(\d+)/@data[$0]/; - -is the same as - - s:nth(3)/(\d+)/@data[$0]/; - -which is the same as: - - m/(\d+)/ && m:c/(\d+)/ && s:c/(\d+)/@data[$0]/; - -The argument to C<:nth> is allowed to be a list of integers, but such a list -should be monotonically increasing. (Values which are less than or equal to -any previous value will be ignored.) So: - - - :nth(2,4,6...*) # return only even matches - :nth(1,1,*+*...*) # match only at 1,2,3,5,8,13... - -This option is no longer required to support smartmatching. You can grep a list -of integers if you really need that capability: - - :nth(grep *.oracle, 1..*) - -If both C<:nth> and C<:x> are present, the matching routine looks for submatches -that match with C<:nth>. If the number of post-nth matches is compatible with -the constraint in C<:x>, the whole match succeeds with the highest possible -number of submatches. The combination of C<:nth> and C<:x> typically only -makes sense if C<:nth> is not a single scalar. - -=item * - -With the new C<:ov> (C<:overlap>) modifier, the current regex will -match at all possible character positions (including overlapping) -and return all matches in list context, or a disjunction of matches -in item context. The first match at any position is returned. -The matches are guaranteed to be returned in left-to-right order with -respect to the starting positions. - - $str = "abracadabra"; - - if $str ~~ m:overlap/ a (.*) a / { - @substrings = slice @(); # bracadabr cadabr dabr br - } - -=item * - -With the new C<:ex> (C<:exhaustive>) modifier, the current regex will -match every possible way (including overlapping) and return a list of -all matches. - -The matches are guaranteed to be returned in left-to-right order with -respect to the starting positions. The order within each starting -position is not guaranteed and may depend on the nature of both the -pattern and the matching engine. (Conjecture: or we could enforce -backtracking engine semantics. Or we could guarantee no order at all -unless the pattern starts with "::" or some such to suppress DFAish -solutions.) - - $str = "abracadabra"; - - if $str ~~ m:exhaustive/ a (.*?) a / { - say "@()"; # br brac bracad bracadabr c cad cadabr d dabr br - } - -Note that the C<~~> above can return as soon as the first match is found, -and the rest of the matches may be performed lazily by C<@()>. - -=item * - -The new C<:rw> modifier causes this regex to I the current -string for modification rather than assuming copy-on-write semantics. -All the captures in C<$/> become lvalues into the string, such -that if you modify, say, C<$1>, the original string is modified in -that location, and the positions of all the other fields modified -accordingly (whatever that means). In the absence of this modifier -(especially if it isn't implemented yet, or is never implemented), -all pieces of C<$/> are considered copy-on-write, if not read-only. - -[Conjecture: this should really associate a pattern with a string variable, -not a (presumably immutable) string value.] - -=item * - -The new C<:r> or C<:ratchet> modifier causes this regex to not backtrack by default. -(Generally you do not use this modifier directly, since it's implied by -C and C declarations.) The effect of this modifier is -to imply a C<:> after every atom, including but not limited to -C<*>, C<+>, and C quantifiers, as well as alternations. Explicit -backtracking modifiers on quantified atoms, such as C<**>, will override this. -(Note: for portions of patterns subject to longest-token analysis, a C<:> -is ignored in any case, since there will be no backtracking necessary.) - -=item * - -The C<:i>, C<:m>, C<:r>, C<:s>, C<:dba>, C<:Perl5>, and Unicode-level modifiers can be -placed inside the regex (and are lexically scoped): - - m/:s alignment '=' [:i left|right|cent[er|re]] / - -As with modifiers outside, only parentheses are recognized as valid -brackets for args to the adverb. In particular: - - m/:foo[xxx]/ Parses as :foo [xxx] - m/:foo{xxx}/ Parses as :foo {xxx} - m/:foo/ Parses as :foo - -=item * - -User-defined modifiers will be possible: - - m:fuzzy/pattern/; - -=item * - -User-defined modifiers can also take arguments, but only in parentheses: - - m:fuzzy('bare')/pattern/; - -=item * - -To use parens for your delimiters you have to separate: - - m:fuzzy (pattern); - -or you'll end up with: - - m:fuzzy(fuzzyargs); pattern ; - -=item * - -Any grammar regex is really just a kind of method, and you may -declare variables in such a routine using a colon followed by any -scope declarator parsed by the Perl 6 grammar, including C, -C, C, and C. (As quasi declarators, C -and C are also recognized.) A single statement (up through -a terminating semicolon or line-final closing brace) is parsed as normal Perl 6 code: - - token prove-nondeterministic-parsing { - :my $threshold = rand; - 'maybe' \s+ - } - -Such declarations do not terminate longest-token-matching, -so an otherwise useless declaration may be used as a peg -to hang side effects on without changing how the subsequent -pattern matches: - - rule breaker { - :state $ = say "got here at least once"; - ... - } - -=back - -=head2 Allowed modifiers - -Some modifiers are allowed in all possible places where modifiers can occur, -but not all of them. - -In general, a modifier that affects the compilation of a regex (like C<:i>) -must be known at compile time. A modifier that affects only the calling -behaviour, and not the regex itself (eg. C<:pos>, C<:overlap>, C<:x(4)>) may -only appear on constructs that involve a call (like C and C), and -not on C. Finally overlapping is disallowed on substitutions, while -adverbs that affect modifications (eg. C<:samecase>) are only allowed on -substitutions. - -These principle result in the following rules: - -=over - -=item * - -The C<:ignorecase>, C<:ignoremark>, C<:sigspace>, C<:ratchet> and C<:Perl5> -modifiers and their short forms are allowed everywhere: inside a regex, -and on C, C and C constructs. An implementation may require -that their value is known at compile time, and give a compile-time error -message if that is not the case. - - rx:i/ hello / # OK - rx:i(1) /hello/ # OK - my $i = 1; - rx:i($i) /hello/ # may error out at compile time - -=item * - -The C<:samecase>, C<:samespace> and C<:samemark> modifiers (and their short -forms) are only allowed on substitutions (C and C). - -=item * - -The C<:overlap> and C<:exhaustive> modifiers (and their short forms) are only -allowed on matches (ie C), not on substitutions or regex quotes. - -=item * - -The C<:pos>, C<:continue>, C<:x> and C<:nth> modifiers and their aliases are -only allowed on constructs that involve immediate calls, eg. C and C -(but not on C). - -=item * - -The C<:dba> adverb is only allowed inside a regex. - -=back - -=head1 Changed metacharacters - -=over - -=item * - -A dot C<.> now matches I character including newline. (The C -modifier is gone.) - -=item * - -C<^> and C<$> now always match the start/end of a string, like the old -C<\A> and C<\z>. (The C modifier is gone.) On the right side of -an embedded C<~~> or C operator they always match the start/end -of the indicated submatch because that submatch is logically being -treated as a separate string. - -=item * - -A C<$> no longer matches an optional preceding C<\n> so it's necessary -to say C<\n?$> if that's what you mean. - -=item * - -C<\n> now matches a logical (platform independent) newline, not just C<\x0a>. -See TR18 section 1.6 for a list of logical newlines. - -=item * - -The C<\A>, C<\Z>, and C<\z> metacharacters are gone. - -=back - -=head1 New metacharacters - -=over - -=item * - -Because C is default: - -=over - -=item * - -An unquoted C<#> now always introduces a comment. If followed -by a backtick and an opening bracket character, -it introduces an embedded comment that terminates with the closing -bracket. Otherwise the comment terminates at the newline. - -=item * - -Whitespace is now always metasyntactic, i.e. used only for layout -and not matched literally (but see the C<:sigspace> modifier described above). - -=back - -=item * - -C<^^> and C<$$> match line beginnings and endings. (The C -modifier is gone.) They are both zero-width assertions. C<$$> -matches before any C<\n> (logical newline), and also at the end of -the string if the final character was I a C<\n>. C<^^> always -matches the beginning of the string and after any C<\n> that is not -the final character in the string. - -=item * - -C<.> matches an I, while C<\N> matches an I matches>. (The C modifier is gone.) In particular, C<\N> matches -neither carriage return nor line feed. - -=item * - -The new C<&> metacharacter separates conjunctive terms. The patterns -on either side must match with the same beginning and end point. -Note: if you don't want your two terms to end at the same point, -then you really want to use a lookahead instead. - -As with the disjunctions C<|> and C<||>, conjunctions come in both -C<&> and C<&&> forms. The C<&> form is considered declarative rather than -procedural; it allows the compiler and/or the -run-time system to decide which parts to evaluate first, and it is -erroneous to assume either order happens consistently. The C<&&> -form guarantees left-to-right order, and backtracking makes the right -argument vary faster than the left. In other words, C<&&> and C<||> establish -sequence points. The left side may be backtracked into when backtracking -is allowed into the construct as a whole. - -The C<&> operator is list associative like C<|>, but has slightly -tighter precedence. Likewise C<&&> has slightly tighter precedence -than C<||>. As with the normal junctional and short-circuit operators, -C<&> and C<|> are both tighter than C<&&> and C<||>. - -=item * - -The C<~~> and C operators cause a submatch to be performed on -whatever was matched by the variable or atom on the left. String -anchors consider that submatch to be the entire string. So, for -instance, you can ask to match any identifier that does not contain -the word "moose": - - !~~ 'moose' - -In contrast - - !~~ ^ 'moose' $ - -would allow any identifier (including any identifier containing -"moose" as a substring) as long as the identifier as a whole is not -equal to "moose". (Note the anchors, which attach the submatch to the -beginning and end of the identifier as if that were the entire match.) -When used as part of a longer match, for clarity it might be good to -use extra brackets: - - [ !~~ ^ 'moose' $ ] - -The precedence of C<~~> and C fits in between the junctional and -sequential versions of the logical operators just as it does in normal -Perl expressions (see S03). Hence - - !~~ 'moose' | 'squirrel' - -parses as - - !~~ [ 'moose' | 'squirrel' ] - -while - - !~~ 'moose' || 'squirrel' - -parses as - - [ !~~ 'moose' ] || 'squirrel' - -=item * - -The C<~> operator is a helper for matching nested subrules with a -specific terminator as the goal. It is designed to be placed between an -opening and closing bracket, like so: - - '(' ~ ')' - -However, it mostly ignores the left argument, and operates on the next -two atoms (which may be quantified). Its operation on those next -two atoms is to "twiddle" them so that they are actually matched in -reverse order. Hence the expression above, at first blush, is merely -shorthand for: - - '(' ')' - -But beyond that, when it rewrites the atoms it also inserts the -apparatus that will set up the inner expression to recognize the -terminator, and to produce an appropriate error message if the -inner expression does not terminate on the required closing atom. -So it really does pay attention to the left bracket as well, and it -actually rewrites our example to something more like: - - $ = '(' [ $GOAL || ] - -Note that you can use this construct to set up expectations for -a closing construct even when there's no opening bracket: - - ~ ')' \d+ - -Here returns true on the first null string. - -By default the error message uses the name of the current rule as an -indicator of the abstract goal of the parser at that point. However, -often this is not terribly informative, especially when rules are named -according to an internal scheme that will not make sense to the user. -The C<:dba("doing business as")> adverb may be used to set up a more informative name for -what the following code is trying to parse: - - token postfix:sym<[ ]> { - :dba('array subscript') - '[' ~ ']' - } - -Then instead of getting a message like: - - Unable to parse expression in postfix:sym<[ ]>; couldn't find final ']' - -you'll get a message like: - - Unable to parse expression in array subscript; couldn't find final ']' - -(The C<:dba> adverb may also be used to give names to alternations -and alternatives, which helps the lexer give better error messages.) - -=back - -=head1 Bracket rationalization - -=over - -=item * - -C<(...)> still delimits a capturing group. However the ordering of these -groups is hierarchical rather than linear. See L. - -=item * - -C<[...]> is no longer a character class. -It now delimits a non-capturing group. - -A character class is now specified using C<< <[...]> >>. -See also L >>)>. - -=item * - -C<{...}> is no longer a repetition quantifier. -It now delimits an embedded closure. It is always considered -procedural rather than declarative; it establishes a sequence point -between what comes before and what comes after. (To avoid this -use the C<< >> assertion syntax instead.) A closure -within a regex establishes its own lexical scope. - -=item * - -You can call Perl code as part of a regex match by using a closure. -Embedded code does not usually affect the match--it is only used -for side-effects: - - / (\S+) { print "string not blank\n"; $text = $0; } - \s+ { print "but does contain whitespace\n" } - / - -An B reduction using the C function generates the -I object (I or I for short) -for this match: - - / (\d) { make $0.sqrt } Remainder /; - -This has the effect of capturing the square root of the numified -string, instead of the string. The C part is matched and -returned as part of the C object but is not returned -as part of the abstract object. Since the abstract object usually -represents the top node of an abstract syntax tree, the abstract object -may be extracted from the C object by use of the C<.made> method. - -A second call to C overrides any previous call to C. -C is also available as a method on each match object. - -Within a closure, the instantaneous -position within the search is denoted by the C<$¢.pos> method. -As with all string positions, you must not treat it -as a number unless you are very careful about which units you are -dealing with. - -The C object can also return the original item that we are -matching against; this is available from the C<.orig> method. - -The closure is also guaranteed to start with a C<$/> C object -representing the match so far. However, if the closure does its own -internal matching, its C<$/> variable will be rebound to the result -of I match until the end of the embedded closure. (The match -will actually continue with the current value of the C<$¢> object after -the closure. C<$/> and C<$¢> just start out the same in your closure.) - -=item * - -It can affect the match if it calls C: - - / (\d+) { $0 < 256 or fail } / - -Since closures establish a sequence point, they are guaranteed to be -called at the canonical time even if the optimizer could prove that -something after them can't match. (Anything before is fair game, -however. In particular, a closure often serves as the terminator -of a longest-token pattern.) - -=item * - -The general repetition specifier is now C<**> for greedy matching, -with a corresponding C<**?> for frugal matching. (All such quantifier -modifiers now go directly after the C<**>.) Space is allowed on either -side of the complete quantifier, but only the space before the C<**> will -be considered significant under C<:sigspace> and match between repetitions. -(Sigspace after the entire construct matches once after the all repetitions -are found.) - -The next token constrains how many times the pattern on the left must match. - -If the next thing is an integer, then it is parsed as either as an exact -count or a range: - - . ** 42 # match exactly 42 times - ** 3..* # match 3 or more times - -This form is considered declarational. - -If you supply a closure, it should return either an C or a C object. - - 'x' ** {$m} # exact count returned from closure - ** {$m..$n} # range returned from closure - - / value was (\d **? {1..6}) with ([ \w* ]**{$m..$n}) / - -It is illegal to return a list, so this easy mistake fails: - - / [foo] ** {1,3} / - -The closure form is always considered procedural, so the item it is -modifying is never considered part of the longest token. - -For backwards compatibility with previous versions of Perl 6, if the token -following ** is not a closure or literal integer, it is interpreted as +% -with a warning: - - / x ** y / # same as / x+ % y / - / x ** $y / # same as / x [$y x]* / - -No check is made to see if $y contains an integer or range value. This -compatibility feature is not guaranteed to exist forever. - -=item * - -Negative range values are allowed, but only when modifying a reversible -pattern (such as C could match). For example, to search the -surrounding 200 characters as defined by 'dot', you could say: - - / . ** -100..100 / - -Similarly, you can back up 50 characters with: - - / . ** -50 / - -[Conjecture: A negative quantifier forces the construct to be -considered procedural rather than declarational.] - -=item * - -Any quantified atom may be modified by an additional constraint that -specifies the separator to look for between repeats of the left side. -This is indicated by use of a C<%> between the quantifier and -the separator. The initial item is iterated only as long as the -separator is seen between items: - - + % '|' # repetition controlled by presence of character - + % # repetition controlled by presence of subrule - + % [ \!?'==' ] # repetition controlled by presence of operator - +%\h+ # repetition controlled by presence of whitespace - -Any quantifier may be so modified: - - * % ',' # 0 or more comma-separated elements - + % ',' # 1 or more - ? % ',' # 0 or 1 (but ',' never used!?!) - ** 2..* % ',' # 2 or more - -The C<%> modifier may only be used on a quantifier; any attempt -to use it on a bare term will result in a parse error (to minimize -possible confusion with any hash notations we choose to support in -Perl 6 regexes). - -A successful match of a C<%> construct generally ends "in the middle" at the C<%>, -that is, after the initial item but before the next separator. -Therefore - - / + % ',' / - -can match - - foo - foo,bar - foo,bar,baz - -but never - - foo, - foo,bar, - -The only time such a match doesn't end in the middle is if the left -side can match 0 times (and does so), in which case the whole construct -matches the null string. - - '' ~~ / * % ',' / # matches because of the * - -If you wish to allow the match to end after either side, use C<%%> instead. -Therefore - - / + %% ',' / - -can match any of - - foo - foo, - foo,bar - foo,bar, - foo,bar,baz - foo,bar,baz, - -If you wish to quantify each match on the left individually, you must place it in brackets: - - [*]+ % ',' - -It is legal for the separator to be zero-width as long as the pattern on -the left progresses on each iteration: - - .+ % # match sequence of identical characters - -The separator never matches independently of the next item; if the -separator matches but the next item fails, it backtracks all the way -back through the separator. Likewise, this matching of the separator -does not count as "progress" under C<:ratchet> semantics unless the -next item succeeds. - -When significant space is used under C<:sigspace>, -each matching element enables the immediately following whitespace -to be considered significant. Space after the C<%> does nothing. If you write: - - ms/ + % ',' / - #1 #2 #3 #4 #5 - -it ignores whitespace #1 and #4, and rewrites the rest to: - - / [ <.ws> ]+ % [ ',' <.ws> ] <.ws> / - #2 #5 #3 - -Since #3 is redundant with #2 (because C<+> requires an element), -it suffices to supply either #2 or #3: - - ms/ + % ',' / # ws after comma and at end - ms/ +% ',' / # ws after comma and any element - -So the first - - ms/ + % ',' / # ws after comma and at end - -is like - - / [','<.ws>]*<.ws> / - -while the second - - ms/ +% ',' / # ws after comma and any element - -is like - - / <.ws>[','<.ws><.ws>]* / - -and - - ms/ +% ','/ - -excludes all significant whitespace like this: - - / [',']* / - -Note that with a C<*> instead of a C<+>, space #3 would not be -redundant with #2, since if 0 elements are matched, the space -associated with it (#2) is not matched. In that case it makes sense -to put space on both sides of the C<*>: - - ms/ * % ',' / - -=item * - -C<< <...> >> are now extensible metasyntax delimiters or I -(i.e. they replace Perl 5's crufty C<(?...)> syntax). - -=back - -=head1 Variable (non-)interpolation - -=over - -=item * - -In Perl 6 regexes, variables don't interpolate. - -=item * - -Instead they're passed I to the regex engine, which can then decide -how to handle them (more on that below). - -=item * - -The default way in which the engine handles a string scalar is to match it -as a C<< "..." >> literal (i.e. it does not treat the interpolated string -as a subpattern). In other words, a Perl 6: - - / $var / - -is like a Perl 5: - - / \Q$var\E / - -To interpolate a C object, use C<< <$var> >> instead. - -If C<$var> is undefined, a warning is issued and the match fails. - -When matching against a Stringy type that is not Str, the variable must -be interpretable as a value of that Stringy type (or a related type -that can be coerced to that type). For example, when regex matching a -Buf type, the variable will be matched under the Buf type's semantics, -not Str semantics. - -[Conjecture: when we allow matching against non-string types, doing a -type match on the current node will require the syntax of an embedded -signature, not just a bare variable, so there is no need to account for -a variable containing a type object, which is by definition undefined, -and hence fails to match by the above rule.] - -However, a variable used as the left side of an alias or submatch -operator is not used for matching. - - $x = <.ident> - $0 ~~ <.ident> - -If you do want to match C<$0> again and then use that as the submatch, -you can force the match using double quotes: - - "$0" ~~ <.ident> - -On the other hand, it is non-sensical to alias to something that is -not a variable: - - "$0" = <.ident> # ERROR - $0 = <.ident> # okay - $x = <.ident> # okay, temporary capture - $ = <.ident> # okay, persistent capture - # same thing - -Variables declared in capture aliases are lexically scoped to the -rest of the regex. You should not confuse this use of C<=> with -either ordinary assignment or ordinary binding. You should read -the C<=> more like the pseudoassignment of a declarator than like -normal assignment. It's more like the ordinary C<:=> operator, -since at the level regexes work, strings are immutable, so captures -are really just precomputed substr values. Nevertheless, when you -eventually use the values independently, the substr may be copied, -and then it's more like it was an assignment originally. - -Capture variables of the form C<< $ >> may persist beyond -the lexical scope; if the match succeeds they are remembered in the -C object's hash, with a key corresponding to the variable name's -identifier. Likewise bound numeric variables persist as C<$0>, etc. - -You may capture to existing lexical variables; such variables may -already be visible from an outer scope, or may be declared within -the regex via a C<:my> declaration. - - my $x; / $x = [...] / # capture to outer lexical $x - / :my $x; $x = [...] / # capture to our own lexical $x - -=item * - -An interpolated array: - - / @cmds / - -is matched as if it were an alternation of its literal elements. Ordinarily it -matches using junctive semantics: - - / [ $(@cmds[0]) | $(@cmds[1]) | $(@cmds[2]) | ... ] / - - -However, if it is a direct member of a C<||> list, it uses sequential -matching semantics, even it's the only member of the list. Conveniently, -you can put C<||> before the first member of an alternation, hence - - / || @cmds / - -is equivalent to - - / [ $(@cmds[0]) || $(@cmds[1]) || $(@cmds[2]) || ... ] / - -Or course, you can also - - / | @cmds / - -to be clear that you mean junctive semantics. - -Note the usage of $(...) to prevent the subscripts from being parsed as -regex syntax rather than an actual subscript. - -Since C<$x> is interpolated as if you'd said C<"$x">, if C<$x> contains -a list, it is stringified first. To get alternation you must use the -C<@$x> or C<@($x)> form to indicate that you're intending the scalar -variable to be treated as a list. - -An interpolated array using junctive semantics is declarative -(participates in external longest token matching) only if it's -known to be constant at the time the regex is compiled. - -As with a scalar variable, each element is matched as a literal. -All such values pay attention to the current C<:ignorecase> -and C<:ignoremark> settings. - -When you get tired of writing: - - token sigil { '$' | '@' | '%' | '&' | '::' } - -you can write: - - token sigil { < $ @ % & :: > } - -as long as you're careful to put a space after the initial angle so that -it won't be interpreted as a subrule. With the space it is parsed -like angle quotes in ordinary Perl 6 and treated as a literal array value. - -=item * - -Alternatively, if you predeclare a proto regex, you can write multiple -regexes for the same category, differentiated only by the symbol they -match. The symbol is specified as part of the "long name". It may also -be matched within the rule using C<< >>, like this: - - proto token sigil {*} - multi token sigil:sym<$> { } - multi token sigil:sym<@> { } - multi token sigil:sym<%> { } - multi token sigil:sym<&> { } - multi token sigil:sym<::> { } - -(The C is optional and generally omitted with a grammar.) - -This can be viewed as a form of multiple dispatch, except that it's -based on longest-token matching rather than signature matching. The -advantage of writing it this way is that it's easy to add additional -rules to the same category in a derived grammar. All of them will -be matched in parallel when you try to match C<< // >>. - -If there are formal parameters on multi regex methods, matching -still proceeds via longest-token rules first. If that results in a -tie, a normal multiple dispatch is made using the arguments to the -remaining variants, assuming they can be differentiated by type. - -The C calls into the subdispatcher when it sees a C<*> that -cannot be a quantifier and is the only thing in its block. Therefore -you can put items before and after the subdispatch by putting -the C<*> into curlies: - - proto token foo { {*} } - -This works only in a proto. See L for a discussion of the -semantics of C<{*}>. (Unlike a proto sub, a proto regex -automatically remembers the return values from C<{*}> because -they are carried along with the match cursor.) - -=item * - -The use of a hash variable in patterns is reserved. - -=item * - -Variable matches are considered declarative if and only if the variable -is known to represent a constant, Otherwise they are procedural. -Note that role parameters (if readonly) are considered constant -declarations for this purpose despite the absence of an explicit -C declarator, since roles themselves are immutable, and -will presumably be replacing the parameter with a constant value when -composed (if the value passed is a constant). Macros instantiated -with constants would also make those constants eligible for declarative -treatment. - -=back - -=head1 Extensible metasyntax (C<< <...> >>) - -Both C<< < >> and C<< > >> are metacharacters, and are usually (but not -always) used in matched pairs. (Some combinations of metacharacters -function as standalone tokens, and these may include angles. These are -described below.) Most assertions are considered declarative; -procedural assertions will be marked as exceptions. - -For matched pairs, the first character after C<< < >> determines the -nature of the assertion: - -=over - -=item * - -If the first character is whitespace, the angles are treated as an -ordinary "quote words" array literal. - - < adam & eve > # equivalent to [ 'adam' | '&' | 'eve' ] - -Note that the space before the ending > is optional and therefore -< adam & eve> would be acceptable. - -=item * - -A leading alphabetic character means it's a capturing grammatical -assertion (i.e. a subrule or a named character class - see below): - - / ? ? / - -The first character after the identifier determines the treatment of -the rest of the text before the closing angle. The underlying semantics -is that of a function or method call, so if the first character is -a left parenthesis, it really is a call to either a method or function: - - - -If the first character after the identifier is an C<=>, then the identifier -is taken as an alias for what follows. In particular, - - - -is just shorthand for - - $ = - -Note that this aliasing does not modify the original C<< >> -capture. To rename an inherited method capture without using the -original name, use the dot form described below on the capture you -wish to suppress. That is, - - - -desugars to: - - $ = <.bar> - -Likewise, to rename a lexically scoped regex explicitly, use the C<&> -form described below. That is, - - - -desugars to: - - $ = <&bar> - -Multiple aliases are allowed, so - - - -is short for - - $ = $ = - -Similarly, you can alias other assertion, e.g.: - - # a character class, same as $=<[abc]> - # a Unicode property, same as $=:Letter> - # a negated Unicode property lookup - -If the first character after the identifier is whitespace, the -subsequent text (following any whitespace) is passed as a regex, so: - - - -is more or less equivalent to - - - -To pass a regex with leading whitespace you must use the parenthesized form. - -If the first character is a colon followed by whitespace, the rest -of the text is taken as a list of arguments to the method, just as -in ordinary Perl syntax. So these mean the same thing: - - - - -No other characters are allowed after the initial identifier. - -Subrule matches are considered declarative to the extent that -the front of the subrule is itself considered declarative. If a -subrule contains a sequence point, then so does the subrule match. -Longest-token matching does not proceed past such a subrule, for -instance. - -This form always gives preference to a lexically scoped regex declaration, -dispatching directly to it as if it were function. If there is no such -lexical regex (or lexical method) in scope, the call is dispatched to the -current grammar, assuming there is one. That is, if there is a -C visible from the current lexical scope, then - - - -means the same as - - - -However, if there is no such lexically scoped regex (and note that within -a grammar, regexes are installed as methods which have no lexical alias -by default), then the call is dispatched as a normal method on the current -C (which will fail if you're not currently within a grammar). So -in that case: - - - -means the same as: - - - -A call to C<< >> will fail if there is neither any lexically -scoped routine of that name it can call, nor any method of that name -that be reached via method dispatch. (The decision of which dispatcher -to use is made at compile time, not at run time; the method call is not -a fallback mechanism.) - -=item * - -A leading C<.> explicitly calls a method as a subrule; the fact -that the initial character is not alphanumeric also causes the named -assertion to not capture what it matches (see L. For -example: - - / / # $/ and $/ both captured - / <.ident> / # only $/ captured - / <.ident> <.ws> / # nothing captured - -The assertion is otherwise parsed identically to an assertion beginning with -an identifier, provided the next thing after the dot is an identifier. As with -the identifier form, any extra arguments pertaining to the matching engine -are automatically supplied to the argument list via the implicit C invocant. -If there is no current class/grammar, or the current class is not derived -from C, the call is likely to fail. - -If the dot is not followed by an identifier, it is parsed as a "dotty" -postfix of some type, such as an indirect method call: - - <.$indirect(@args)> - -As with all regex matching, the current match state (some derivative -of C) is passed as the first argument, which in this case -is simply the method's invocant. The method is expected to return -a lazy list of new match state objects, or C if the match fails -entirely. Ratcheted routines will typically return a list containing only -one match. - -=item * - -Whereas a leading C<.> unambiguously calls a method, a leading C<&> -unambiguously calls a routine instead. Such a regex routine must -be declared (or imported) with C or C scoping to make its -name visible to the lexical scope, since by default a regex name is -installed only into the current class's metaobject instance, just -as with an ordinary method. The routine serves as a kind of private -submethod, and is called without any consideration of inheritance. -It must still take a C as its first argument (which it can -think of as an invocant if it likes), and must return the new match -state as a cursor object. Hence, - - <&foo(1,2,3)> - -is sugar for something like: - - <.gather { take foo($¢,1,2,3) }> - -where C<$¢> represents the current incoming match state, and the -routine must return C for failure, or a lazy list of one or -more match states (C-derived objects) for successful matches. - -As with the C<.> form, an explicit C<&> suppresses capture. - -Note that all normal C objects are really such routines in disguise. -When you say: - - rx/stuff/ - -you're really declaring an anonymous method, something like: - - my $internal = anon regex :: ($¢: ) { stuff } - -and then passing that object off to someone else who will call it -indirectly. In this case, the method is installed neither into -a class nor into a lexical scope, but as long as the value stays -live somehow, it can still be called indirectly (see below). - -=item * - -A leading C<$> indicates an indirect subrule call. The variable must -contain either a C object (really an anonymous method--see -above), or a string to be compiled as the regex. The string is never -matched literally. - -If the compilation of the string form fails, the error message is converted -to a warning and the assertion fails. - -The indirect subrule assertion is not captured. (No assertion with leading punctuation -is captured by default.) You may always capture it explicitly, of course: - - / / - -An indirect subrule is always considered procedural, and may not participate -in longest-token matching. - -=item * - -A leading C<::> indicates a symbolic indirect subrule: - - / <::($somename)> / - -The variable must contain the name of a subrule. By the rules of -single method dispatch this is first searched for in the current -grammar and its ancestors. If this search fails an attempt is made -to dispatch via MMD, in which case it can find subrules defined as -multis rather than methods. This form is not captured by default. -It is always considered procedural, not declarative. - -=item * - -A leading C<@> matches like a bare array except that each element is -treated as a subrule (string or C object) rather than as a literal. -That is, a string is forced to be compiled as a subrule instead of being -matched literally. (There is no difference for a C object.) - -This assertion is not automatically captured. - -=item * - -The use of a hash as an assertion is reserved. - -=item * - -A leading C<{> indicates code that produces a regex to be interpolated -into the pattern at that point as a subrule: - - / (<.ident>) <{ %cache{$0} //= get_body_for($0) }> / - -The closure is guaranteed to be run at the canonical time; it declares -a sequence point, and is considered to be procedural. - -=item * - -In any case of regex interpolation, if the value already happens to be -a C object, it is not recompiled. If it is a string, the compiled -form is cached with the string so that it is not recompiled next -time you use it unless the string changes. (Any external lexical -variable names must be rebound each time though.) Subrules may not be -interpolated with unbalanced bracketing. An interpolated subrule -keeps its own inner match results as a single item, so its parentheses never count toward the -outer regexes groupings. (In other words, parenthesis numbering is always -lexically scoped.) - -=item * - -A leading C or C indicates a code assertion: - - / (\d**1..3) / - / (\d**1..3) / - -Similar to: - - / (\d**1..3) { $0 < 256 or fail } / - / (\d**1..3) { $0 < 256 and fail } / - -Unlike closures, code assertions are considered declarative; they are -not guaranteed to be run at the canonical time if the optimizer can -prove something later can't match. So you can sneak in a call to a -non-canonical closure that way: - - token { foo .* .* bar } - -The C block is unlikely to run unless the string ends with "C". - -=item * - -A leading C<[> indicates an enumerated character class. Ranges -in enumerated character classes are indicated with "C<..>" rather than "C<->". - - / <[a..z_]>* / - -Whitespace is ignored within square brackets: - - / <[ a .. z _ ]>* / - -A reversed range is illegal. In directly compiled code it's a compile-time -error to say - - / <[ z .. a ]> / # Reversed range is not allowed - -In indirectly compiled code, a similar warning is issued and the assertion fails: - - $rx = '<[ z .. a ]>'; - / <$rx> /; # warns and never matches - -=item * - -A leading C<-> indicates a complemented character class: - - / <-[a..z_]> <-alpha> / - / <- [a..z_]> <- alpha> / # whitespace allowed after - - -This is essentially the same as using negative lookahead and dot: - - / . . / - -Whitespace is ignored after the initial C<->. - -=item * - -A leading C<+> may also be supplied to indicate that the following -character class is to be matched in a positive sense. - - / <+[a..z_]>* / - / <+[ a..z _ ]>* / - / <+ [ a .. z _ ] >* / # whitespace allowed after + - -=item * - -Character classes can be combined (additively or subtractively) within -a single set of angle brackets. Whitespace is ignored. For example: - - / <[a..z] - [aeiou] + xdigit> / # consonant or hex digit - -A named character class may be used by itself: - - - -However, in order to combine classes you must prefix a named -character class with C<+> or C<->. Whitespace is required before -any C<-> that would be misparsed as an identifier extender. - -=item * - -One can use character classes as assertions. The following two expressions -are equivalent and match a variable that does not start with a sigil assuming -that C<< >> can also match a sigil less variable. - - - > - -=item * - -Unicode properties are indicated by use of pair notation in place of a normal -rule name: - - <:Letter> # a letter - <:!Letter> # a non-letter - -Properties with arguments are passed as the argument to the pair: - - <:East_Asian_Width> - <:!Blk> - -The pair value is smartmatched against the value in the Unicode Character -Database. - - <:Nv(0 ^..^ 1)> # the char has a proper fractional value - -As a particular case of smartmatching, TR18 section 2.6 is satisfied -with a pattern as the argument: - - <:name(/^LATIN LETTER.*P$/)> - -=item * - -Multiple of these terms may be combined with pluses and minuses: - - <+ :HexDigit - :Upper > - -Terms may also be combined using C<&> for set intersection, C<|> -for set union, and C<^> for symmetric set difference. Parens may be -used for grouping. (Square brackets always quote literal characters -(including backslashed literal forms), and may not be nested, unlike -the suggested notation in TR18 section 1.3.) The precedence of -the operators is the same as the correspondingly named operators in -L, even though they have somewhat different -semantics. - -=item * - -Extra long characters may be entered by quoting them and including them -via intersection. Any quoted characters will be treated as "longest tokens" -when appropriate. Here 'll' would be recognized in preference to 'l': - - / <[ a..z ] | 'ñ' | 'ch' | 'll' | 'rr'> - -Note that a negated character class containing "long characters" -always advances by a single character. - -=item * - -When any character constructor such as C<\c>, C<\x>, or C<\o> contains -multiple values separated by commas, these are treated as "long characters". -So you could add a C<\c[13,10]> to the list above to match CRLF as a long -character. - -A consequence of this is that the negated form advances by a single -position (matching as C<.> does) when the long character doesn't -match as a whole. Hence, this matches: - - "\c[13,13,10,10]" ~~ /\C[13,10]* \c[13,10] \C[13,10]/; - -If you want it to mean \C13\C10 instead, then you can just write it that way. - -=item * - -A leading C indicates a negated meaning (always a zero-width assertion): - - / / # We aren't before an _ - -Note that C<< >> is different from C<< <-alpha> >>. -C<< /<-alpha>/ >> is a complemented character class equivalent to -C<<< /> ./ >>>, whereas C<< >> is a zero-width -assertion equivalent to a C<<< />/ >>> assertion. - -Note also that as a metacharacter C doesn't change the parsing -rules of whatever follows (unlike, say, C<+> or C<->). - -=item * - -A leading C indicates a positive zero-width assertion, and like C -merely reparses the rest of the assertion recursively as if the C -were not there. In addition to forcing zero-width, it also suppresses -any named capture: - - # match a letter and capture to $alpha (eventually $) - <.alpha> # match a letter, don't capture - # match null before a letter, don't capture - -The special named assertions include: - - / / # lookahead - / / # lookbehind - - / / # true between two identical characters - - / <.ws> / # match "whitespace": - # \s+ if it's between two \w characters, - # \s* otherwise - - / / # match only at a particular position - # short for - # (considered declarative until $pos changes) - -It is legal to use any of these assertions as named captures by omitting the -punctuation at the front. However, capture entails some overhead in both -memory and computation, so in general you want to suppress that for data -you aren't interested in preserving. - -The C assertion implements lookbehind by reversing the syntax -tree and looking for things in the opposite order going to the left. -It is illegal to do lookbehind on a pattern that cannot be reversed. - -Note: the effect of a forward-scanning lookbehind at the top level -can be achieved with: - - / .*? prestuff <( mainpat )> / - -=item * - -A leading C<*> indicates that the following pattern allows a -partial match. It always succeeds after matching as many characters -as possible. (It is not zero-width unless 0 characters match.) -For instance, to match a number of abbreviations, you might write -any of: - - s/ ^ G<*n|enesis> $ /gen/ or - s/ ^ Ex<*odus> $ /ex/ or - s/ ^ L<*v|eviticus> $ /lev/ or - s/ ^ N<*m|umbers> $ /num/ or - s/ ^ D<*t|euteronomy> $ /deut/ or - ... - - / (<* < foo bar baz > >) / - - / / and return %long{$} || $; - -The pattern is restricted to declarative forms that can be rewritten -as nested optional character matches. Sequence information -may not be discarded while making all following characters optional. -That is, it is not sufficient to rewrite: - - <*xyz> - -as: - - x? y? z? # bad, would allow xz - -Instead, it must be implemented as: - - [x [y z?]?]? # allow only x, xy, xyz (and '') - -Explicit quantifiers are allowed on single characters, so this: - - <* a b+ c | ax*> - -is rewritten as something like: - - [a [b+ c?]?]? | [a x*]? - -In the latter example we're assuming the DFA token matcher is going to -give us the longest match regardless. It's also possible that quantified -multi-character sequences can be recursively remapped: - - <* 'ab'+> # match a, ab, ababa, etc. (but not aab!) - ==> [ 'ab'* <*ab> ] - ==> [ 'ab'* [a b?]? ] - -[Conjecture: depending on how fancy we get, we might (or might not) -be able to autodetect ambiguities in C<< <*@abbrev> >> and refuse to -generate ambiguous abbreviations (although exact match of a shorter -abbrev should always be allowed even if it's the prefix of a longer -abbreviation). If it is not possible, then the user will have to -check for ambiguities after the match. Note also that the array -form is assuming the array doesn't change often. If it does, the -longest-token matcher has to be recalculated, which could get -expensive.] - -=item * - -A leading C<~~> indicates a recursive call back into some or all of -the current rule. An optional argument indicates which subpattern -to re-use, and if provided must resolve to a single subpattern. -If omitted, the entire pattern is called recursively: - - <~~> # call myself recursively - <~~0> # match according to $0's pattern - <~~foo> # match according to $'s pattern - -Note that this rematches the pattern associated with the name, not -the string matched. So - - $_ = "foodbard" - - / ( foo | bar ) d $0 / # fails; doesn't match "foo" literally - / ( foo | bar ) d <$0> / # fails; doesn't match /foo/ as subrule - / ( foo | bar ) d <~~0> / # matches using rule associated with $0 - -The last is equivalent to - - / ( foo | bar ) d ( foo | bar ) / - -Note that the "self" call of - - / <~~> / - -calls back into this anonymous rule as a subrule, and is implicitly -anchored to the end of the operator as any other subrule would be. -Despite the fact that the outer rule scans the string, the inner -call to it does not. - -Note that a consequence of the previous section is that you also get - - - -for free, which fails if the current rule would match again at this location. - -=item * - -A leading C<|> indicates some kind of a zero-width boundary. You can refer to -backslash sequences with this syntax; C<< <|h> >> will match between a C<\h> and -a C<\H>, for instance. Some examples: - - <|w> word boundary - <|g> grapheme boundary (always matches in grapheme mode) - <|c> codepoint boundary (always matches in grapheme/codepoint mode) - -=back - -The following tokens include angles but are not required to balance: - -=over - -=item * - -A C<< <( >> token indicates the start of the match's overall capture, while the -corresponding C<< )> >> token indicates its endpoint. When matched, -these behave as assertions that are always true, but have the side -effect of setting the C<.from> and C<.to> attributes of the match -object. That is: - - / foo <( \d+ )> bar / - -is equivalent to: - - / \d+ / - -except that the scan for "C" can be done in the forward direction, -while a lookbehind assertion would presumably scan for C<\d+> and then -match "C" backwards. The use of C<< <(...)> >> affects only the -positions of the beginning and ending of the match, and anything calculated -based on those positions. For instance, after the match above, C<$()> contains -only the digits matched, and C<$/.to> is pointing to after the digits. Other -captures (named or numbered) are unaffected and may be accessed through C<$/>. - -When used directly within quantifiers (that is, within quantified -square brackets), there is only one C object to set -C<.from>/C<.to> on, so the C<< <( >> token always sets C<.from> to -the leftmost matching position, while C<< )> >> always sets C<.to> -to the rightmost position. However, the situation is different for -capturing parentheses. When used within parentheses (whether or -not the parens are quantified), the C being generated by each -dynamic capture serves as the target, so each such capturing group -sets its own C<.from>/C<.to>. Hence, if the group is quantified, -each capture sets its own boundaries independently. - -These tokens are considered declarative. - -=item * - -A C<«> or C<<< << >>> token indicates a left word boundary. A C<»> or -C<<< >> >>> token indicates a right word boundary. (As separate tokens, -these need not be balanced.) Perl 5's C<\b> is replaced by a C<< <|w> >> -"word boundary" assertion, while C<\B> becomes C<< >>. (None of -these are dependent on the definition of C<< <.ws> >>, but only on the C<\w> -definition of "word" characters. Non-space mark characters are ignored in -calculating word properties of the preceding character. See TR18 1.4.) - -=back - -=head2 Predefined Subrules - -These are some of the predefined subrules for any grammar or regex: - -=over - -=item * ident -XX<< >> - -Match an identifier. - -=item * upper -XX<< >> - -Match a single uppercase character. - -=item * lower -XX<< >> - -Match a single lowercase character. - -=item * alpha -XX<< >> - -Match a single alphabetic character, or an underscore. - -To match Unicode alphabetic characters without the underscore, use -C<< <:alpha> >>. - -=item * digit -XX<< >> - -Match a single digit. - -=item * xdigit -XX<< >> - -Match a single hexadecimal digit. - -=item * print -XX<< >> - -Match a single printable character. - -=item * graph -XX<< >> - -Match a single "graphical" character. - -=item * cntrl -XX<< >> - -Match a single "control" character (equivalent to the <:Cc> property). A control character is usually one that -doesn't produce output as such but instead controls the terminal somehow: for -example newline and backspace are control characters. All characters with ord() -less than 32 are usually classified as control characters (assuming ASCII, the -ISO Latin character sets, and Unicode), as is the character with the ord() value -of 127 (DEL). The characters from 128 to 159 are also control characters. - -=item * punct -XX<< >> - -Match a single punctuation character (that is, any character from the -Unicode General Category "Punctuation"). - -=item * alnum -XX<< >> - -Match a single alphanumeric character. This is equivalent to <+alpha +digit> . - -=item * wb -XX<< >> - -Returns a zero-width match that is true at word boundaries. A word -boundary is a spot with a "\w" on one side and a "\W" on the other -side (in either order), counting the beginning and end of the string -as matching "\W". - -=item * ww -XX<< >> - -Matches between two word characters (zero-width match). - -=item * ws -XX<< >> - -Matches required whitespace between two word characters, optional -whitespace otherwise. This is roughly equivalent to C<< \s* >> -(C isn't required to use the C subrule). - -=item * space -XX<< >> - -Match a single whitespace character (same as C< \s > ). - -=item * blank -XX<< >> - -Match a single "blank" character -- in most locales, this corresponds -to space and tab. - -=item * before C -XX<< >> - -Perform lookahead -- i.e., check if we're at a position where -C matches. Returns a zero-width C object on -success. - -=item * after C -XX<< >> - -Perform lookbehind -- i.e., check if the string before the -current position matches (anchored at the end). -Returns a zero-width C object on success. - -=item * -XX<< >> - -Match a null string, viz., always returns true - -=item * -XX<< >> - -Inverse of , viz., always returns false. - -=back - -=head1 Backslash reform - -=over - -=item * - -Many C<\p> and C<\P> properties become intrinsic grammar rules such as (C<< - >> and C<< <-alpha> >>). They may be combined using the above-mentioned -character class notation: C<< <[-]+alpha+digit> >>. Regardless of the -higher-level character class names, all low-level Unicode properties are always -available with a prefix of colon, that is, in pair notation within the angle -brackets. Hence, C<< <+:Lu+:Lt> >> is equivalent to C<< <+upper+title> >>. - -=item * - -The C<\L...\E>, C<\U...\E>, and C<\Q...\E> sequences are gone. The -single-character case modifiers C<\l> and C<\u> are also gone. In the -rare cases that need them you can use C<< <{ lc $regex }> >>, -C<< <{tc $word}> >>, etc. - -=item * - -As mentioned above, the C<\b> and C<\B> word boundary assertions are gone, -and are replaced with C<< <|w> >> (or ) and C<< >> (or ) -zero-width assertions. - -=item * - -The C<\G> sequence is gone. Use C<:p> instead. (Note, however, -that it makes no sense to use C<:p> within a pattern, since every -internal pattern is implicitly anchored to the current position.) -See the C assertion below. - -=item * - -Backreferences (e.g. C<\1>, C<\2>, etc.) are gone; C<$0>, C<$1>, etc. can be -used instead, because variables are no longer interpolated. - -Numeric variables are assumed to change every time and therefore are -considered procedural, unlike normal variables. - -=item * - -New backslash sequences, C<\h> and C<\v>, match horizontal and vertical -whitespace respectively, including Unicode. Horizontal whitespace is defined -as anything matching C<\s> that doesn't also match C<\v>. Vertical whitespace is -defined as any of: - - U+000A LINE FEED (LF) - U+000B LINE TABULATION - U+000C FORM FEED (FF) - U+000D CARRIAGE RETURN (CR) - U+0085 NEXT LINE (NEL) - U+2028 LINE SEPARATOR - U+2029 PARAGRAPH SEPARATOR - -Note that C (CARRIAGE RETURN) is considered vertical whitespace despite -the fact that it only moves the "carriage" horizontally. - -=item * - -C<\s> now matches any Unicode whitespace character. - -=item * - -The new backslash sequence C<\N> matches anything except a logical -newline; it is the negation of C<\n>. - -=item * - -Other new capital backslash sequences are also the negations -of their lowercase counterparts: - -=over - -=item * - -C<\H> matches anything but horizontal whitespace. - -=item * - -C<\V> matches anything but vertical whitespace. - -=item * - -C<\T> matches anything but a tab. - -=item * - -C<\R> matches anything but a return. - -=item * - -C<\F> matches anything but a formfeed. - -=item * - -C<\E> matches anything but an escape. - -=item * - -C<\X...> matches anything but the specified character (specified in -hexadecimal). - -=item * - -Backslash escapes for literal characters in ordinary strings are allowed in -regexes (C<\a>, C<\x>, etc.). However, the exception to this rule is C<\b>, -which is disallowed in order to avoid conflict with its former use as a word -boundary assertion. To match a literal backspace, use C<\c8>, C<\x8>, or a -double-quoted C<\b>. - -=back - -=back - -=head2 Character class shortcuts - -For historical and convenience reasons, the following character classes are -available as backslash sequences: - - \d A digit - \D <-digit> A nondigit - \w A word character - \W <-alnum> A non-word character - \s A whitespace character - \S A non-whitespace character - \h A horizontal whitespace - \H A non-horizontal whitespace - \v A vertical whitespace - \V A non-vertical whitespace - -=head1 Regexes constitute a first-class language, rather than just being strings - -=over - -=item * - -The Perl 5 C regex constructor is gone. - -=item * - -The Perl 6 equivalents are: - - regex { pattern } # always takes {...} as delimiters - rx / pattern / # can take (almost) any chars as delimiters - -You may not use whitespace or alphanumerics for delimiters. Space is -optional unless needed to distinguish from modifier arguments or -function parens. So you may use parens as your C delimiters, -but only if you interpose whitespace: - - rx ( pattern ) # okay - rx( 1,2,3 ) # tries to call rx function - -(This is true for all quotelike constructs in Perl 6.) - -The C form may be used directly as a pattern anywhere a normal C match can. -The C form is really a method definition, and must be used in such a way that -the grammar class it is to be used in is apparent. - -=item * - -If either form needs modifiers, they go before the opening delimiter: - - $regex = regex :s:i { my name is (.*) }; - $regex = rx:s:i / my name is (.*) /; # same thing - -Space is necessary after the final modifier if you use any -bracketing character for the delimiter. (Otherwise it would be taken as -an argument to the modifier.) - -=item * - -You may not use colons for the delimiter. Space is allowed between -modifiers: - - $regex = rx :s :i / my name is (.*) /; - -=item * - -The name of the constructor was changed from C because it's no -longer an interpolating quote-like operator. C is short for I, -(not to be confused with regular expressions, except when they are). - -=item * - -As the syntax indicates, it is now more closely analogous to a C -constructor. In fact, that analogy runs I deep in Perl 6. - -=item * - -Just as a raw C<{...}> is now always a closure (which may still -execute immediately in certain contexts and be passed as an object -in others), so too a raw C is now always a C object (which -may still match immediately in certain contexts and be passed as an -object in others). - -=item * - -Specifically, a C matches immediately in a value context (sink, -Boolean, string, or numeric), or when it is an explicit argument of -a C<~~>. Otherwise it's a C constructor identical to the explicit -C form. So this: - - $var = /pattern/; - -no longer does the match and sets C<$var> to the result. -Instead it assigns a C object to C<$var>. - -=item * - -The two cases can always be distinguished using C or C: - - $match = m{pattern}; # Match regex immediately, assign result - $regex = rx{pattern}; # Assign regex expression itself - -=item * - -Note that this means that former magically lazy usages like: - - @list = split /pattern/, $str; - -are now just consequences of the normal semantics. - -=item * - -It's now also possible to set up a user-defined subroutine that acts -like C: - - sub my_grep($selector, *@list) { - given $selector { - when Regex { ... } - when Code { ... } - when Hash { ... } - # etc. - } - } - -When you call C, the first argument is bound in item context, -so passing C<{...}> or C produces a C or C object, -which the switch statement then selects upon. (Normal C just -lets a smartmatch operator do all the work.) - -=item * - -Just as C has variants, so does the C declarator. -In particular, there are two special variants for use in grammars: -C and C. - -A token declaration: - - token ident { [ | \- ] \w* } - -never backtracks by default. That is, it likes to commit to whatever -it has scanned so far. The above is equivalent to - - regex ident { [ : | \-: ]: \w*: } - -but rather easier to read. The bare C<*>, C<+>, and C quantifiers -never backtrack in a C. -In normal regexes, use -C<*:>, C<+:>, or C to prevent any backtracking into the quantifier. -If you want to explicitly backtrack, append either a C or a C -to the quantifier. The C forces frugal matching as usual, -while the C forces greedy matching. The C declarator is -really just short for - - regex :ratchet { ... } - -The other is the C declarator, for declaring non-terminal -productions in a grammar. Like a C, it also does not backtrack -by default. In addition, a C regex also assumes C<:sigspace>. -A C is really short for: - - regex :ratchet :sigspace { ... } - -=item * - -The Perl 5 C syntax (I) was rarely used and can be -now emulated more cleanly with a state variable: - - $result = do { state $x ||= m/ pattern /; } # only matches first time - -To reset the pattern, simply say C<$x = 0>. Though if you want C<$x> visible -you'd have to avoid using a block: - - $result = state $x ||= m/ pattern /; - ... - $x = 0; - -=back - -=head1 Backtracking control - -Within those portions of a pattern that are considered procedural rather -than declarative, you may control the backtracking behavior. - -=over - -=item * - -By default, backtracking is greedy in C, C, C, and the like. -It's also greedy in ordinary C declarations. In C -and C declarations, backtracking must be explicit. - -=item * - -To force the preceding atom to do frugal backtracking (also sometimes -known as "eager matching" or "minimal matching"), -append a C<:?> or C to the atom. If the preceding token is -a quantifier, the C<:> may be omitted, so C<*?> works just as -in Perl 5. - -=item * - -To force the preceding atom to do greedy backtracking in a -spot that would default otherwise, append a C<:!> to the atom. -If the preceding token is a quantifier, the C<:> may be omitted. -(Perl 5 has no corresponding construct because backtracking always -defaults to greedy in Perl 5.) - -=item * - -To force the preceding atom to do no backtracking, use a single C<:> -without a subsequent C or C. Backtracking over a single colon -causes the regex engine not to retry the preceding atom: - - ms/ \( [ , ]*: \) / - -(i.e. there's no point trying fewer C<< >> matches, if there's -no closing parenthesis on the horizon) - -When modifying a quantifier, a C<+> may be used instead of a C<:>, in -which case the quantifier is often known as a I quantifier. - - ms/ \( [ , ]*+ \) / # same thing - -To force all the atoms in an expression not to backtrack by default, -use C<:ratchet> or C or C. - -=item * - -Evaluating a double colon throws away all saved choice points in the current -L alternation. - - ms/ [ if :: - | for :: - | loop :: ? - ] - / - -(i.e. there's no point trying to match a different keyword if one was -already found but failed). - -The C<::> also has the effect of hiding any declarative match on the right -from "longest token" processing by C<|>. Only the left side is evaluated -for determinacy. - -C<::> does nothing if there is no current LTM alternation. "Current" -is defined dynamically, not lexically. A C<::> in a subrule will affect -the enclosing alternation. - -=item * - -Evaluating a C<< ::> >> throws away all saved choice points in the current -innermost temporal alternation. It thus acts as a "then". - - ms/ [ - || ::> - || ::> - || ::> - ] - / - -Note that you can still back into the "then" part of such -an alternation, so you may also need to put C<:> after it if you -also want to disable that. If an explicit or implicit C<:ratchet> -has disabled backtracking by supplying an implicit C<:>, you need to -put an explicit C after the alternation to enable backing into, -say, the C<< >> rule above. - -C<< ::> >> does nothing if there is no current temporal alternation. -"Current" is defined dynamically, not lexically. A C<< ::> >> in a -subrule will affect the enclosing alternation. - -=item * - -Evaluating a triple colon throws away all saved choice points since -the current regex was entered. Backtracking to (or past) this point -will fail the rule outright (no matter where in the regex it occurs): - - regex ident { - ( [|\-] \w* ) ::: { fail if %reserved{$0} } - || " [|\-] \w* " - } - - ms/ get ? / - -(i.e. using an unquoted reserved word as an identifier is not permitted) - -=item * - -Evaluating a C<< >> assertion throws away all saved choice -points since the start of the entire match. Backtracking to (or past) -this point will fail the entire match, no matter how many subrules -down it happens: - - regex subname { - ([|\-] \w*) { fail if %reserved{$0} } - } - ms/ sub ? / - -(i.e. using a reserved word as a subroutine name is instantly fatal -to the I match as well) - -If commit is given an argument, it's the name of a calling rule that -should be committed: - - - -=item * - -A C<< >> assertion always matches successfully, and has the -side effect of logically deleting the parts of the string already -matched. Whether this actually frees up the memory immediately may -depend on various interactions among your backreferences, the string -implementation, and the garbage collector. In any case, the string -will report that it has been chopped off on the front. It's illegal -to use C<< >> on a string that you do not have write access to. - -Attempting to backtrack past a C<< >> causes the complete -match to fail (like backtracking past a C<< >>). This is -because there's now no preceding text to backtrack into. This is -useful for throwing away successfully processed input when matching -from an input stream or an iterator of arbitrary length. - -=back - -=head1 Regex Routines, Named and Anonymous - -=over - -=item * - -The analogy between C and C extends much further. - -=item * - -Just as you can have anonymous subs and named subs... - -=item * - -...so too you can have anonymous regexes and I regexes (and tokens, -and rules): - - token ident { [|\-] \w* } - - # and later... - - @ids = grep //, @strings; - -=item * - -As the above example indicates, it's possible to refer to named regexes, -such as: - - regex serial_number { <[A..Z]> \d**8 } - token type { alpha | beta | production | deprecated | legacy } - -in other regexes as named assertions: - - rule identification { [soft|hard]ware } - -These keyword-declared regexes are officially of type C, -which is derived from C. - -In general, the anchoring of any subrule call is controlled by its calling context. -When a regex, token, or rule method is called as a subrule, the -front is anchored to the current position (as with C<:p>), while -the end is not anchored, since the calling context will likely wish -to continue parsing. However, when such a method is smartmatched -directly, it is automatically anchored on both ends to the beginning -and end of the string. Thus, you can do direct pattern matching -by using an anonymous regex routine as a standalone pattern: - - $string ~~ regex { \d+ } - $string ~~ token { \d+ } - $string ~~ rule { \d+ } - -and these are equivalent to - - $string ~~ m/^ \d+ $/; - $string ~~ m/^ \d+: $/; - $string ~~ m/^ <.ws> \d+: <.ws> $/; - -The basic rule of thumb is that the keyword-defined methods never -do implicit C<.*?>-like scanning, while the C and C -quotelike forms do such scanning in the absence of explicit anchoring. - -The C and C forms can go either way: they scan when used -directly within a smartmatch or boolean context, but when called -indirectly as a subrule they do not scan. That is, the object returned -by C behaves like C when used directly, but like C -C<{}> when used as a subrule: - - $pattern = rx/foo/; - $string ~~ $pattern; # equivalent to m/foo/; - $string ~~ /'[' <$pattern> ']'/ # equivalent to /'[foo]'/ - -=back - -=head1 Nothing is illegal - -=over - -=item * - -The empty pattern is now illegal. - -=item * - -To match the zero-width string, you must use some explicit -representation of the null match: - - / '' /; - / /; - -For example: - - split /''/, $string - -splits between characters. But then, so does this: - - split '', $string - -=item * - -Likewise, to match an empty alternative, use something like: - - /a|b|c|/ - /a|b|c|''/ - -This makes it easier to catch errors like this: - - /a|b|c|/ - -As a special case, however, the first null alternative in a match like - - ms/ [ - | if :: - | for :: - | loop :: ? - ] - / - -is simply ignored. Only the first alternative is special that way. -If you write: - - ms/ [ - if :: | - for :: | - loop :: ? | - ] - / - - -it's still an error. - -=item * - -However, it's okay for a non-null syntactic construct to have a degenerate -case matching the null string: - - $something = ""; - /a|b|c|$something/; - -In particular, C<< >> always matches the null string successfully, -and C<< >> always fails to match anything. - -=back - -=head1 Longest-token matching - -Since "longest-token matching" is a long phrase, we will usually refer -to this idea as B. The basic notion is that LTM is how people -tend to parse text in their heads, so the computer ought to try to do -the same. And parsing with LTM is all about how the computer decides -which alternative of a set of alternatives is going to match. - -Instead of representing temporal alternation as it does in Perl 5, in Perl 6 C<|> represents -logical alternation with declarative longest-token semantics. (You may -now use C<||> to indicate the old temporal alternation. That is, C<|> -and C<||> now work within regex syntax much the same as they do outside -of regex syntax, where they represent junctional and short-circuit OR. -This includes the fact that C<|> has tighter precedence than C<||>.) - -Historically regex processing has proceeded in Perl via a backtracking -NFA algorithm. This is quite powerful, but many parsers work more -efficiently by processing rules in parallel rather than one after -another, at least up to a point. If you look at something like a -yacc grammar, you find a lot of pattern/action declarations where the -patterns are considered in parallel, and eventually the grammar decides -which action to fire off. While the default Perl view of parsing is -essentially top-down (perhaps with a bottom-up "middle layer" to handle -operator precedence), it is extremely useful for user understanding -if at least the token processing proceeds deterministically. So for -regex matching purposes we define token patterns as those patterns -that can be matched without potential side effects or self-reference. -(Since whitespace often has side effects at line transitions, it -is usually excluded from such patterns, give or take a little -lookahead.) Basically, Perl automatically derives a lexer -from the grammar without you having to write one yourself. - -To that end, every regex in Perl 6 is required to be able to -distinguish its "pure" patterns from its actions, and return its -list of initial token patterns (transitively including the token -patterns of any subrule called by the "pure" part of that regex, but -not including any subrule more than once, since that would involve -self reference, which is not allowed in traditional regular -expressions). A logical alternation using C<|> then takes two or -more of these lists and dispatches to the alternative that matches -the longest token prefix. This may or may not be the alternative -that comes first lexically. - -However, if two alternatives match at the same length, the tie is -broken first by specificity. The alternative that starts with the -longest fixed string wins; that is, an exact match counts as closer -than a match made using character classes. If that doesn't work, the tie -is broken by one of two methods. If the alternatives are in different -grammars, standard MRO (method resolution order) determines which -one to try first. If the alternatives are in the same grammar file, the -textually earlier alternative takes precedence. (If a grammar's rules -are defined in more than one file, the order is undefined, and an explicit -assertion must be used to force failure if the wrong one is tried first.) - -This longest token prefix corresponds roughly to the notion of "token" -in other parsing systems that use a lexer, but in the case of Perl -this is largely an epiphenomenon derived automatically from the grammar -definition. However, despite being automatically calculated, the set of -tokens can be modified by the user; various -constructs within a regex declaratively tell the grammar engine that -it is finished with the pattern part and starting in on the side effects, -so by inserting such constructs the user controls what is considered -a token and what is not. The constructs deemed to terminate a token -declaration and start the "action" part of the pattern include: - -=over - -=item * - -Any :: or ::: backtracking control (but not the : possessive modifier). - -=item * - -Any atom that is quantified with a frugal match (using the C modifier). - -=item * - -Any C<{...}> action, but not an assertion containing a closure. -(The empty closure C<{}> is customarily used to explicitly terminate -the pure part of the pattern.) The closure form of the general -C<**{...}> quantifier also terminates the longest token, but the -closureless forms of quantifier do not. - -=item * - -Any sequential control flow operator such as C<||> or C<&&>. - -=item * - -As a consequence of the previous point, and because the standard -grammar's C<< >> rule defines whitespace using C<||>, the -longest token is also terminated by any part of the regex or rule -that I match whitespace using that rule, including whitespace -implicitly matched via C<:sigspace>. (However, token declarations are -specifically allowed to recognize whitespace within a token by using -such lower-level primitives as C<\h+> or other character classes.) - -=back - -Subpatterns (captures) specifically do not terminate the token pattern, -but may require a reparse of the token to find the location -of the subpatterns. Likewise assertions may need to be checked out -after the longest token is determined. (Alternately, if DFA semantics -are simulated in any of various ways, such as by Thompson NFA, it may -be possible to know when to fire off the assertions without backchecks.) - -Greedy quantifiers and character classes do not terminate a token pattern. -Zero-width assertions such as word boundaries are also okay. - -Because such assertions can be part of the token, the lexer engine must -be able to recover from the failure of such an assertion and backtrack -to the next best token candidate, which might be the same length or shorter, -but can never be longer than the current candidate. - -For a pattern that contains a positive lookahead assertion such as -C<< >> or C<< >>, the assertion is assumed to be -more specific than the subsequent pattern, so the lookahead's pattern -is counted as the final part of the longest token; the longest-token -matcher will be smart enough to treat the extra bit as 0-width, that -is, to rematch any text traversed by the lookahead when (and if) -it continues the match. (Indeed, if the entire lookahead is pure -enough to participate in LTM, the rematcher may simply optimize away -the rematching, since the lookahead already matched in the LTM engine.) - -However, for a pattern that contains a negative lookahead assertion -such as C<< >> or C<< >>, just the opposite is -true: the subsequent pattern is assumed to be more specific than -the assertion's. So LTM completely ignores negative lookaheads, and -continues to look for pure patterns in whatever follows the negative -lookahead. You might say that positive lookaheads are opaque to LTM, -but negative lookaheads are transparent to LTM. As a consequence, -if you wish to write a positive lookahead that is transparent to -LTM, you may indicate this with a double negation: C<< >>. -(The optimizer is free to remove the double negation, but not the -transparency.) - -Oddly enough, the C keyword specifically does not determine -the scope of a token, except insofar as a token pattern usually -doesn't do much matching of whitespace, and whitespace is the prototypical -way of terminating tokens. - -The initial token matcher must take into account case sensitivity -(or any other canonicalization primitives) and do the right thing even -when propagated up to rules that don't have the same canonicalization. -That is, they must continue to represent the set of matches that the -lower rule would match. - -The C<||> form has the old short-circuit semantics, and will not -attempt to match its right side unless all possibilities (including -all C<|> possibilities) are exhausted on its left. The first C<||> -in a regex makes the token patterns on its left available to the -outer longest-token matcher, but hides any subsequent tests from -longest-token matching. Every C<||> establishes a new longest-token -matcher. That is, if you use C<|> on the right side of C<||>, that -right side establishes a new top level scope for longest-token processing -for this subexpression and any called subrules. The right side's -longest-token automaton is invisible to the left of the C<||> or outside -the regex containing the C<||>. - -=head1 Return values from matches - -=head2 Match objects - -=over - -=item * - -A successful match always returns a C object, which is generally also -put into C<$/>, a dynamic lexical declared in the outer -routine that is calling the regex. (A named C, C, -or C is a routine, and hence declares its own -lexical C<$/> variable, which always refers to the most recent -submatch within the rule, if any.) The current match state is -kept in the regex's C<$¢> variable which will eventually get -bound to the user's C<$/> variable when the match completes. - -An unsuccessful match returns C (and sets C<$/> to C if -the match would have set it). - -=item * - -Notionally, a match object contains (among other things) a boolean -success value, an array of ordered submatch objects, and a hash of named -submatch objects. (It also optionally carries an I normally -used to build up an abstract syntax tree,) To provide convenient -access to these various values, the match object evaluates differently -in different contexts: - -=over - -=item * - -In boolean context it evaluates as true or false (i.e. did the match -succeed?): - - if /pattern/ {...} - # or: - /pattern/; if $/ {...} - -With C<:global> or C<:overlap> or C<:exhaustive> the boolean is -allowed to return true on the first match. The C object can -produce the rest of the results lazily if evaluated in list context. - -=item * - -In string context it evaluates to the stringified value of its match, -which is usually the entire matched string: - - print %hash{ "{$text ~~ /<.ident>/}" }; - # or equivalently: - $text ~~ /<.ident>/ && print %hash{~$/}; - -But generally you should say C<~$/> if you mean C<~$/>. - -=item * - -In numeric context it evaluates to the numeric value of its match, -which is usually the entire matched string: - - $sum += /\d+/; - # or equivalently: - /\d+/; $sum = $sum + $/; - -=item * - -When used as a scalar, a C object evaluates to itself. - -However, sometimes you would like an alternate scalar value to -ride along with the match. The C object itself describes -a concrete parse tree, so this extra value is called an I -object; it rides along as an attribute of the C object. -The C<.made> method by default returns an undefined value. -C<$()> is a shorthand for C<$($/.made // ~$/)>. - -Therefore C<$()> is usually just the entire match string, but -you can override that by calling C inside a regex: - - my $moose = $(m[ - - { make Moose.new( body => $.attach($) ) } - # match succeeds -- ignore the rest of the regex - ]); - -This puts the new abstract node into C<$/.made>. An AST node may be of any -type. Using the C/C<.made> mechanism, it is convenient to build up an -abstract syntax tree of arbitrary node types. - -However, the C function is not limited to be used for storing AST -nodes and building abstract syntax trees only. This is just a specific Perl 6 -internal use of this functionality. Nor does the C function impose any -item or list context onto its argument, so if you say something ambiguously -listy like - - make () - make @array - make foo() - -the value returned from C<.made> will interpolate into a list. To suppress -this, use one of these: - - make ().item - make [] - make $@array - make [@array] - make foo().item - make $(foo()) - -or use C<.made.item> or a C<$> variable on the receiving end. - -The C<.ast> method is a synonym C<.made> with no differing behavior. It exists -both for historical reasons and as a way to indicate to those reading your code -a more AST-like use of the C/C<.make> mechanism. - -=item * - -You may also capture a subset of the match using the C<< <(...)> >> construct: - - "foo123bar" ~~ / foo <( \d+ )> bar / - say $(); # says 123 - -In this case C<$()> is always a string when doing string -matching, and a list of one or more elements when doing list matching. -This construct does not set the C<.made> attribute. - -=item * - -When used as an array, a C object pretends to be an array of all -its positional captures. Hence - - ($key, $val) = ms/ (\S+) '=>' (\S+)/; - -can also be written: - - $result = ms/ (\S+) '=>' (\S+)/; - ($key, $val) = @$result; - -To get a single capture into a string, use a subscript: - - $mystring = "{ ms/ (\S+) '=>' (\S+)/[0] }"; - -To get all the captures into a string, use a I slice: - - $mystring = "{ ms/ (\S+) '=>' (\S+)/[] }"; - -Or cast it into an array: - - $mystring = "@( ms/ (\S+) '=>' (\S+)/ )"; - -Note that, as a scalar variable, C<$/> doesn't automatically flatten -in list context. Use C<@()> as a shorthand for C<@($/)> to flatten -the positional captures under list context. Note that a C object -is allowed to evaluate its match lazily in list context. Use C -to force an eager match. - -=item * - -When used as a hash, a C object pretends to be a hash of all its named -captures. The keys do not include any sigils, so if you capture to -variable C<< @ >> its real name is C<$/{'foo'}> or C<< $/ >>. -However, you may still refer to it as C<< @ >> anywhere C<$/> -is visible. (But it is erroneous to use the same name for two different -capture datatypes.) - -Note that, as a scalar variable, C<$/> doesn't automatically flatten -in list context. Use C<%()> as a shorthand for C<%($/)> to flatten as a -hash, or bind it to a variable of the appropriate type. As with C<@()>, -it's possible for C<%()> to produce its pairs lazily in list context. - -=item * - -The numbered captures may be treated as named, so C<< $<0 1 2> >> -is equivalent to C<$/[0,1,2]>. This allows you to write slices of -intermixed named and numbered captures. - -=item * - -The C<.keys>, C<.values> and C<.kv> methods act both on the list and hash -part, with the list part coming first. - - 'abcd' ~~ /(.)(.)**2 /; - say ~$/.keys; # 0 1 alpha - -=item * - -In ordinary code, variables C<$0>, C<$1>, etc. are just aliases into -C<$/[0]>, C<$/[1]>, etc. Hence they will all be undefined if the -last match failed (unless they were explicitly bound in a closure without -using the C keyword). - -=back - -=item * - -C objects have methods that provide additional information about -the match. For example: - - if m/ def / { - say "Found sub def from index $/.from.bytes ", - "to index $/.to.bytes"; - } - -The currently defined methods are - - $/.from # the initial match position - $/.to # the final match position - $/.chars # $/.to - $/.from - $/.orig # the original match string - $/.Str # substr($/.orig, $/.from, $/.chars) - $/.made # the abstract result associated with this node (from make) - $/.ast # same as $/.made - $/.caps # sequential captures - $/.chunks # sequential tokenization - $/.prematch # $/.orig.substr(0, $/.from) - $/.postmatch # $/.orig.substr($/.to) - -Within the regex the current match state C<$¢> also provides - - .pos # the current match position - -This last value may correspond to either C<$¢.from> or C<$¢.to> depending -on whether the match is proceeding in a forward or backward direction -(the latter case arising inside an C<< >> assertion). - -=item * - -As described above, a C in list context returns its positional -captures. However, sometimes you'd rather get a flat list of tokens -in the order they occur in the text. The C<.caps> method returns -a list of every capture in order, regardless of how it was otherwise -bound into named or numbered captures. (Other than order, there is -no new information here; all the elements of the list are the very -same C objects that bound elsewhere.) The bindings are actually -returned as key/value pairs where the key is the name or number under which -the match object was bound, and the value is the match object itself. - -In addition to returning those captured C objects, the -C<.chunks> method also returns all the interleaved "noise" between -the captures. As with C<.caps>, the list elements are in the order -they were originally in the text. The interleaved bits are also -returned as pairs, where the key is '~' and the value -is a simple C object containing only the string, even if unbound -subrules such as C<.ws> were called to traverse the text in the first -place. Calling C<.made> on such a C object always returns a C. - -A warning will be issued if either C<.caps> or C<.chunks> discovers -that it has overlapping bindings. In the absence of such overlap, -C<.chunks> guarantees to map every part of its matched string (between -C<.from> and C<.to>) to exactly one element of its returned matches, -so coverage is complete. - -[Conjecture: we could also have C<.deepcaps> and C<.deepchunks> that -recursively expand any capture containing submatches. Presumably the -keys of such returned chunks would indicate the "pedigree" of bindings -in the parse tree.] - -=item * - -All match attempts--successful or not--against any regex, subrule, -or subpattern (see below) return an object that can be evaluated -as a boolean. (This object will be either a C or a C.) -That is: - - $match_obj = $str ~~ /pattern/; - say "Matched" if $match_obj; - - -=item * - -This returned object is also automatically bound to the lexical -C<$/> variable of the current surroundings regardless of success. That is: - - $str ~~ /pattern/; - say "Matched" if $/; - -=item * - -Inside a regex, the C<$¢> variable holds the current regex's incomplete -C object, known as a match state (of type C). Generally this should not -be modified unless you know how to create and propagate match states. -All regexes actually return match states even when you think they're -returning something else, because the match states keep track of -the successes and failures of the pattern for you. - -Fortunately, when you just want to return a different abstract result along with -the default concrete C object, you may associate your return value with -the current match state using the C function, which works something -like a C, but doesn't clobber the match state: - - $str ~~ / foo # Match 'foo' - { make 'bar' } # But pretend we matched 'bar' - /; - say $(); # says 'bar' - -The value of any C object (such as an abstract object) is available via -the C<< .made >> method. Hence these abstract objects can be managed -independently of the returned cursor objects. - -The current cursor object must always be derived from C, or the -match will not work. However, within that constraint, the actual type -of the current cursor defines which language you are currently parsing. -When you enter the top of a grammar, this cursor generally starts out -as an object whose type is the name of the grammar you are in, but the -current language can be modified by various methods as they mutate the -current language by returning cursor objects blessed into a different -type, which may or may not be derived from the current grammar. - -=back - -=head2 Subpattern captures - -=over - -=item * - -Any part of a regex that is enclosed in capturing parentheses is called a -I. For example: - - # subpattern - # _________________/\___________________ - # | | - # | subpattern subpattern | - # | __/\__ __/\__ | - # | | | | | | - ms/ (I am the (walrus), ( khoo )**2 kachoo) /; - - -=item * - -Each subpattern in a regex produces a C object if it is -successfully matched. - -=item * - -Each subpattern is either explicitly assigned to a named destination or -implicitly added to an array of matches. - -For each subpattern that is not explicitly given a name, -the subpattern's C object is pushed onto the array inside -the outer C object belonging to the surrounding scope (known as -its I object>). The surrounding scope may be either the -innermost surrounding subpattern (if the subpattern is nested) or else -the entire regex itself. - -=item * - -Like all captures, these assignments to the array are hypothetical, and -are undone if the subpattern is backtracked. - -=item * - -For example, if the following pattern matched successfully: - - # subpat-A - # _________________/\__________________ - # | | - # | subpat-B subpat-C | - # | __/\__ __/\__ | - # | | | | | | - ms/ (I am the (walrus), ( khoo )**2 kachoo) /; - -then the C objects representing the matches made by I -and I would be successively pushed onto the array inside I's C object. Then I's C object would itself be -pushed onto the array inside the C object for the entire regex -(i.e. onto C<$/>'s array). - -=item * - -As a result of these semantics, capturing parentheses in Perl 6 are -hierarchical, not linear (see L). - -=back - -=head2 Accessing captured subpatterns - -=over - -=item * - -The array elements of a C object are referred to using either the -standard array access notation (e.g. C<$/[0]>, C<$/[1]>, C<$/[2]>, etc.) -or else via the corresponding lexically scoped numeric aliases (i.e. -C<$0>, C<$1>, C<$2>, etc.) So: - - say "$/[1] was found between $/[0] and $/[2]"; - -is the same as: - - say "$1 was found between $0 and $2"; - -=item * - -Note that, in Perl 6, the numeric capture variables start from $0, not -$1, with the numbers corresponding to the element's index inside C<$/>. - -=item * - -The array elements of the regex's C object (i.e. C<$/>) -store individual C objects representing the substrings that were -matched and captured by the first, second, third, etc. I -(i.e. unnested) subpatterns. So these elements can be treated like fully -fledged match results. For example: - - if m/ (\d\d\d\d)-(\d\d)-(\d\d) (BCE?|AD|CE)?/ { - ($yr, $mon, $day) = $/[0..2]; - $era = "$3" if $3; # stringify/boolify - @datepos = ( $0.from() .. $2.to() ); # Call Match methods - } - - -=back - -=head2 Nested subpattern captures - -=over - -=item * - -Substrings matched by I subpatterns (i.e. nested capturing -parens) are assigned to the array inside the nested subpattern's parent C -object, not to the array of C<$/>. - -=item * - -This behavior is quite different from Perl 5 semantics: - - # Perl 5... - # - # $1--------------------- $4--------- $5------------------ - # | $2--------------- | | | | $6---- $7------ | - # | | $3-- | | | | | | | | | | - # | | | | | | | | | | | | | | - m/ ( A (guy|gal|g(\S+) ) ) (sees|calls) ( (the|a) (gal|guy) ) /x; - -=item * - -In Perl 6, nested parens produce properly nested captures: - - # Perl 6... - # - # $0--------------------- $1--------- $2------------------ - # | $0[0]------------ | | | | $2[0]- $2[1]--- | - # | | $0[0][0] | | | | | | | | | | - # | | | | | | | | | | | | | | - m/ ( A (guy|gal|g(\S+) ) ) (sees|calls) ( (the|a) (gal|guy) ) /; - - -=back - -=head2 Quantified subpattern captures - -=over - -=item * - -If a subpattern is directly quantified with C, it either produces -a single C object, or C. If a subpattern is directly -quantified using any other quantifier, it never produces a single -C object. Instead, it produces a list of C objects -corresponding to the sequence of individual matches made by the -repeated subpattern. If we need to distinguish the two categories, -C is an I, while C<*>, C<+>, and C<**> are called -I. - -If 0 values match, the captured value depends on which quantifier -is used. If the quantifier is C, a C is captured if it -matched 0 times. If the quantifier is C<*>, the empty list, C<()>, -is captured instead. (Nothing is captured by the C<+> quantifier -if it matches 0 times, since it causes backtracking, but the capture -variable should return C if an attempt is made to use it after -an unsuccessful match.) A C<**> quantifier returns () as C<*> does -if it the minimum of its range is 0, and backtracks otherwise. - -Note that C<** 0..1> is always considered a list quantifier, unlike C. - -The rationale for treating C as an item quantifier is to make -it consistent with how C<$object.?meth> is defined, and to reduce -the need for gratuitous C<.[0]> subscripts, which is surprising to -most people. Now that C is considered undefined rather than a -synonym for C<()>, it's easy to use C<$0 // "default"> or some such -to dereference a capture safely. - -=item * - -Because a list-quantified subpattern returns a list of C objects, the -corresponding array element for the quantified capture will store a -(nested) array rather than a single C object. For example: - - if m/ (\w+) \: (\w+ \s+)* / { - say "Key: $0"; # Unquantified --> single Match - say "Values: @($1)"; # Quantified --> array of Match - } - - -=back - -=head2 Indirectly quantified subpattern captures - -=over - -=item * - -A subpattern may sometimes be nested inside a quantified non-capturing -structure: - - # non-capturing quantifier - # __________/\____________ __/\__ - # | || | - # | $0 $1 || | - # | _^_ ___^___ || | - # | | | | | || | - m/ [ (\w+) \: (\w+ \h*)* \n ] ** 2..* / - -Non-capturing brackets I create a separate nested lexical scope, -so the two subpatterns inside them are actually still in the regex's -top-level scope, hence their top-level designations: C<$0> and C<$1>. - -=item * - -However, because the two subpatterns are inside a quantified -structure, C<$0> and C<$1> will each contain an array. -The elements of that array will be the submatches returned by the -corresponding subpatterns on each iteration of the non-capturing -parentheses. For example: - - my $text = "foo:food fool\nbar:bard barb"; - - # $0-- $1------ - # | | | | - $text ~~ m/ [ (\w+) \: (\w+ \h*)* \n ] ** 2..* /; - - # Because they're in a quantified non-capturing block... - # $0 contains the equivalent of: - # - # [ Match.new(str=>'foo'), Match.new(str=>'bar') ] - # - # and $1 contains the equivalent of: - # - # [ Match.new(str=>'food '), - # Match.new(str=>'fool' ), - # Match.new(str=>'bard '), - # Match.new(str=>'barb' ), - # ] - - -=item * - -In contrast, if the outer quantified structure is a I -structure (i.e. a subpattern) then it I introduce a nested -lexical scope. That outer quantified structure will then -return an array of C objects representing the captures -of the inner parens for I iteration (as described above). That is: - - my $text = "foo:food fool\nbar:bard barb"; - - # $0----------------------- - # | | - # | $0[0] $0[1]--- | - # | | | | | | - $text ~~ m/ ( (\w+) \: (\w+ \h*)* \n ) ** 2..* /; - - # Because it's in a quantified capturing block, - # $0 contains the equivalent of: - # - # [ Match.new( str=>"foo:food fool\n", - # arr=>[ Match.new(str=>'foo'), - # [ - # Match.new(str=>'food '), - # Match.new(str=>'fool'), - # ] - # ], - # ), - # Match.new( str=>'bar:bard barb', - # arr=>[ Match.new(str=>'bar'), - # [ - # Match.new(str=>'bard '), - # Match.new(str=>'barb'), - # ] - # ], - # ), - # ] - # - # and there is no $1 - -=item * - -In other words, quantified non-capturing parens collect their components -into handy flattened lists, whereas quantified capturing parens collect -their components in a handy hierarchical structure. - -Additionally, the sublists are kept "in sync" with each other, as each empty -match, in the case of C<$0[1]> in our example if a C<:> is followed by a -newline character, will have a corresponding Nil in the given list. - -=back - -=head2 Subpattern numbering - -=over - -=item * - -The index of a given subpattern can always be statically determined, but -is not necessarily unique nor always monotonic. The numbering of subpatterns -restarts in each lexical scope (either a regex, a subpattern, or the -branch of an alternation). - -=item * - -In particular, the index of capturing parentheses restarts after each -C<|> or C<||> (but not after each C<&> or C<&&>). Hence: - - # $0 $1 $2 $3 $4 $5 - $tune_up = rx/ ("don't") (ray) (me) (for) (solar tea), ("d'oh!") - # $0 $1 $2 $3 $4 - | (every) (green) (BEM) (devours) (faces) - /; - -This means that if the second alternation matches, the list value of the match will -contain C<('every', 'green', 'BEM', 'devours', 'faces')> rather than -Perl 5's C<(undef, undef, undef, undef, undef, undef, 'every', 'green', 'BEM', -'devours', 'faces')>. - -=item * - -Note that it is still possible to mimic the monotonic Perl 5 capture -indexing semantics. See L below for details. - - -=back - -=head2 Subrule captures - -=over - -=item * - -Any call to a named C<< >> within a pattern is known as a -I, whether that regex is actually defined as a C or -C or C or even an ordinary C or C. - -=item * - -Any bracketed construct that is aliased (see L below) to a -named variable is also a subrule. - -=item * - -For example, this regex contains three subrules: - - # subrule subrule subrule - # __^__ _______^_____ __^__ - # | | | | | | - m/ $=(\s*) + / - -=item * - -Just like subpatterns, each successfully matched subrule within a regex -produces a C object. But, unlike subpatterns, that C -object is not assigned to the array inside its parent C object. -Instead, it is assigned to an entry of the hash inside its parent C -object. For example: - - # .... $/ ..................................... - # : : - # : .... $/[0] .................. : - # : : : : - # : $/ : $/[0] : : - # : __^__ : __^__ : : - # : | | : | | : : - ms/ \: ( known as previously ) / - - -=back - -=head2 Accessing captured subrules - -=over - -=item * - -The hash entries of a C object can be referred to using any of the -standard hash access notations (C<$/{'foo'}>, C<< $/ >>, C<$/«baz»>, -etc.), or else via corresponding lexically scoped aliases (C<< $ >>, -C<$«bar»>, C<< $ >>, etc.) So the previous example also implies: - - # $ $0 - # __^__ __^__ - # | | | | - ms/ \: ( known as previously ) / - -=item * - -Note that it makes no difference whether a subrule is angle-bracketed -(C<< >>) or aliased internally (C<< >>) or aliased -externally (C<< $=(<.alpha>\w*) >>). The name's the thing. - - -=back - -=head2 Repeated captures of the same subrule - -=over - -=item * - -If a subrule appears two (or more) times in any branch of a lexical -scope (i.e. twice within the same subpattern and alternation), or if -the subrule is list-quantified anywhere within a given scope (that is, -by any quantifier other than C), then its corresponding hash entry -is always assigned an array of C objects rather than a single -C object. - -=item * - -Successive matches of the same subrule (whether from separate calls, or -from a single quantified repetition) append their individual C -objects to this array. For example: - - if ms/ mv / { - $from = $[0]; - $to = $[1]; - } - -(Note, for clarity we are ignoring whitespace subtleties here--the -normal sigspace rules would require space only between alphanumeric -characters, which is wrong. Assume that our file subrule deals -with whitespace on its own.) - -Likewise, with a quantified subrule: - - if ms/ mv ** 2 / { - $from = $[0]; - $to = $[1]; - } - -And with a mixture of both: - - if ms/ mv + / { - $to = pop @($); - @from = @($); - } - -=item * - -To avoid name collisions, you may suppress the original name by use -of a leading dot, and then use an alias to give the capture a different name: - - if ms/ mv / { - $from = $; # Only one subrule named , so scalar - $to = $; # The Capture Formerly Known As - } - - -Likewise, neither of the following constructions causes C<< >> to -produce an array of C objects, since none of them has two or more -C<< >> subrules in the same lexical scope: - - if ms/ (keep) | (toss) / { - # Each is in a separate alternation, therefore - # is not repeated in any one scope, hence $ is - # not an Array object... - $action = $0; - $target = $; - } - - if ms/ \: (|none) / { - # Second nested in subpattern which confers a - # different scope... - $actual = $/; - $virtual = $/[0] if $/[0]; - } - -=item * - -On the other hand, unaliased square brackets don't confer a separate -scope (because they don't have an associated C object). So: - - if ms/ \: [|none] / { # Two s in same scope - $actual = $/[0]; - $virtual = $/[1] if $/[1]; - } - - -=back - -=head2 Aliasing - -Aliases can be named or numbered. They can be scalar-, array-, or hash-like. -And they can be applied to either capturing or non-capturing constructs. The -following sections highlight special features of the semantics of some -of those combinations. - - -=head3 Named scalar aliasing to subpatterns - -=over - -=item * - -If a named scalar alias is applied to a set of I parens: - - # _____/capturing parens\_____ - # | | - # | | - ms/ $=( (<[A..E]>) (\d**3..6) (X?) ) /; - -then the outer capturing parens no longer capture into the array of -C<$/> as unaliased parens would. Instead the aliased parens capture -into the hash of C<$/>; specifically into the hash element -whose key is the alias name. - -=item * - -So, in the above example, a successful match sets -C<< $ >> (i.e. C<< $/ >>), but I C<$0> (i.e. not C<< $/[0] >>). - -=item * - -More specifically: - -=over - -=item * - -C<< $/ >> will contain the C object that would previously have -been placed in C<< $/[0] >>. - -=item * - -C<< $/[0] >> will contain the A-E letter, - -=item * - -C<< $/[1] >> will contain the digits, - -=item * - -C<< $/[2] >> will contain the optional X. - -=back - -=item * - -Another way to think about this behavior is that aliased parens create -a kind of lexically scoped named subrule; that the contents of the -parentheses are treated as if they were part of a separate subrule whose -name is the alias. - - -=back - -=head3 Named scalar aliases applied to non-capturing brackets - -=over - -=item * - -If a named scalar alias is applied to a set of I brackets: - - # __/non-capturing brackets\__ - # | | - # | | - ms/ $=[ (<[A..E]>) (\d**3..6) (X?) ] /; - -then the corresponding C<< $/ >> C object contains only the string -matched by the non-capturing brackets. - -=item * - -In particular, the array of the C<< $/ >> entry is empty. That's -because square brackets do not create a nested lexical scope, so the -subpatterns are unnested and hence correspond to $0, $1, and $2, and -I to C<< $/[0] >>, C<< $/[1] >>, and C<< $/[2] >>. - -=item * - -In other words: - -=over - -=item * - -C<< $/ >> will contain the complete substring matched by the square -brackets (in a C object, as described above), - -=item * - -C<< $0 >> will contain the A-E letter, - -=item * - -C<< $1 >> will contain the digits, - -=item * - -C<< $2 >> will contain the optional X. - -=back - - -=back - -=head3 Named scalar aliasing to subrules - -=over - -=item * - -If a subrule is aliased, it assigns its C object to the hash -entry whose key is the name of the alias, as well as to the original name. - - if m/ ID\: / { - say "Identified as $/ and $/"; # both names defined - } - -To suppress the original name, use the dot form: - - if m/ ID\: / { - say "Identified as $/"; # $/ is undefined - } - -=item * - -Hence aliasing a dotted subrule I the destination of the subrule's C -object. This is particularly useful for differentiating two or more calls to -the same subrule in the same scope. For example: - - if ms/ mv + / { - @from = @($); - $to = $; - } - -=back - -=head3 Numbered scalar aliasing - -=over - -=item * - -If a numbered alias is used instead of a named alias: - - m/ $1=(<-[:]>*) \: $0= / # captures $ too - m/ $1=(<-[:]>*) \: $0=<.ident> / # doesn't capture $ - -the behavior is exactly the same as for a named alias (i.e. the various -cases described above), except that the resulting C object is -assigned to the corresponding element of the appropriate array rather -than to an element of the hash. - -=item * - -If any numbered alias is used, the numbering of subsequent unaliased -subpatterns in the same scope automatically increments from that -alias number (much like enum values increment from the last explicit -value). That is: - - # --$1--- -$2- --$6--- -$7- - # | | | | | | | | - m/ $1=(food) (bard) $6=(bazd) (quxd) /; - -=item * - -This I behavior is particularly useful for reinstituting -Perl 5 semantics for consecutive subpattern numbering in alternations: - - $tune_up = rx/ ("don't") (ray) (me) (for) (solar tea), ("d'oh!") - | $6 = (every) (green) (BEM) (devours) (faces) - # $7 $8 $9 $10 - /; - -=item * - -It also provides an easy way in Perl 6 to reinstitute the unnested -numbering semantics of nested Perl 5 subpatterns: - - # Perl 5... - # $1 - # _____________/\___________ - # | $2 $3 $4 | - # | __/\___ __/\___ /\ | - # | | | | | | | | - m/ ( ( [A-E] ) (\d{3,6}) (X?) ) /x; - - - # Perl 6... - # $0 - # ______________/\______________ - # | $0[0] $0[1] $0[2] | - # | ___/\___ ____/\____ /\ | - # | | | | | | | | - m/ ( (<[A..E]>) (\d ** 3..6) (X?) ) /; - - - # Perl 6 simulating Perl 5... - # $1 - # _______________/\________________ - # | $2 $3 $4 | - # | ___/\___ ____/\____ /\ | - # | | | | | | | | - m/ $1=[ (<[A..E]>) (\d ** 3..6) (X?) ] /; - -The non-capturing brackets don't introduce a scope, so the subpatterns within -them are at regex scope, and hence numbered at the top level. Aliasing the -square brackets to C<$1> means that the next subpattern at the same level -(i.e. the C<< (<[A..E]>) >>) is numbered sequentially (i.e. C<$2>), etc. - - -=back - -=head3 Scalar aliases applied to quantified constructs - -=over - -=item * - -All of the above semantics apply equally to aliases which are bound to -quantified structures. - -=item * - -The only difference is that, if the aliased construct is a subrule or -subpattern, that quantified subrule or subpattern will have returned a -list of C objects (as described in L and L). -So the corresponding array element or hash entry for the alias will -contain an array, instead of a single C object. - -=item * - -In other words, aliasing and quantification are completely orthogonal. -For example: - - if ms/ mv $0=<.file>+ / { - # + returns a list of Match objects, - # so $0 contains an array of Match objects, - # one for each successful call to - - # $/ does not exist (it's suppressed by the dot) - } - - - if m/ mv \s+ $=(\S+ \s+)* / { - # Quantified subpattern returns a list of Match objects, - # so $/ contains an array of Match - # objects, one for each successful match of the subpattern - - # $0 does not exist (it's pre-empted by the alias) - } - -=item * - -Note, however, that a set of quantified I brackets always -returns a single C object which contains only the complete -substring that was matched by the full set of repetitions of the -brackets (as described in L). For example: - - "coffee fifo fumble" ~~ m/ $=[f <-[f]> ** 1..2 \s*]+ /; - - say $; # prints "fee fifo fum" - - -=back - -=head3 Array aliasing - -=over - -=item * - -An alias can also be specified using an array as the alias instead of a scalar. -For example: - - m/ mv \s+ @=[(\S+) \s+]* /; - -=item * - -Using the C<< @alias= >> notation instead of a C<< $alias= >> -mandates that the corresponding hash entry or array element I -receives an array of C objects, even if the -construct being aliased would normally return a single C object. -This is useful for creating consistent capture semantics across -structurally different alternations (by enforcing array captures in all -branches): - - ms/ Mr?s? @= W\. @= - | Mr?s? @= - /; - - # Aliasing to @names means $/ is always - # an Array object, so... - - say @($/); - -=item * - -For convenience and consistency, C<< @ >> can also be used outside a -regex, as a shorthand for C<< @( $/ ) >>. That is: - - ms/ Mr?s? @= W\. @= - | Mr?s? @= - /; - - say @; - -=item * - -If an array alias is applied to a quantified pair of non-capturing -brackets, it captures the substrings matched by each repetition of the -brackets into separate elements of the corresponding array. That is: - - ms/ mv $=[ f.. \s* ]* /; # $/ assigned a single - # Match object containing the - # complete substring matched by - # the full set of repetitions - # of the non-capturing brackets - - ms/ mv @=[ f.. \s* ]* /; # $/ assigned an array, - # each element of which is a - # Match object containing - # the substring matched by Nth - # repetition of the non- - # capturing bracket match - -=item * - -If an array alias is applied to a quantified pair of capturing parens -(i.e. to a subpattern), then the corresponding hash or array element is -assigned a list constructed by concatenating the array values of each -C object returned by one repetition of the subpattern. That is, -an array alias on a subpattern flattens and collects all nested -subpattern captures within the aliased subpattern. For example: - - if ms/ $=( (\w+) \: (\N+) )+ / { - # Scalar alias, so $/ is assigned an array - # of Match objects, each of which has its own array - # of two subcaptures... - - for @($) -> $pair { - say "Key: $pair[0]"; - say "Val: $pair[1]"; - } - } - - - if ms/ @=( (\w+) \: (\N+) )+ / { - # Array alias, so $/ is assigned an array - # of Match objects, each of which is flattened out of - # the two subcaptures within the subpattern - - for @($) -> $key, $val { - say "Key: $key"; - say "Val: $val"; - } - } - -=item * - -Likewise, if an array alias is applied to a quantified subrule, then the -hash or array element corresponding to the alias is assigned a list -containing the array values of each C object returned by each -repetition of the subrule, all flattened into a single array: - - rule pair { (\w+) \: (\N+) \n } - - if ms/ $=+ / { - # Scalar alias, so $/ contains an array of - # Match objects, each of which is the result of the - # subrule call... - - for @($) -> $pair { - say "Key: $pair[0]"; - say "Val: $pair[1]"; - } - } - - - if ms/ mv @=+ / { - # Array alias, so $/ contains an array of - # Match objects, all flattened down from the - # nested arrays inside the Match objects returned - # by each match of the subrule... - - for @($) -> $key, $val { - say "Key: $key"; - say "Val: $val"; - } - } - -=item * - -In other words, an array alias is useful to flatten into a single array -any nested captures that might occur within a quantified subpattern or subrule. -Whereas a scalar alias is useful to preserve within a top-level array -the internal structure of each repetition. - -=item * - -It is also possible to use a numbered variable as an array alias. -The semantics are exactly as described above, with the sole difference -being that the resulting array of C objects is assigned into the -appropriate element of the regex's match array rather than to a key of -its match hash. For example: - - if m/ mv \s+ @0=((\w+) \s+)+ $1=((\W+) (\s*))* / { - # | | - # | | - # | \_ Scalar alias, so $1 gets an - # | array, with each element - # | a Match object containing - # | the two nested captures - # | - # \___ Array alias, so $0 gets a flattened array of - # just the (\w+) captures from each repetition - - @from = @($0); # Flattened list - - $to_str = $1[0][0]; # Nested elems of - $to_gap = $1[0][1]; # unflattened list - } - -=item * - -Note again that, outside a regex, C<@0> is simply a shorthand for -C<@($0)>, so the first assignment above could also have been written: - - @from = @0; - - -=back - -=head3 Hash aliasing - -=over - -=item * - -An alias can also be specified using a hash as the alias variable, -instead of a scalar or an array. For example: - - m/ mv %=( () \: (\N+) )+ /; - -=item * - -A hash alias causes the corresponding hash or array element in the -current scope's C object to be assigned a (nested) Hash object -(rather than an C object or a single C object). - -=item * - -If a hash alias is applied to a subrule or subpattern then the first nested -numeric capture becomes the key of each hash entry and any remaining numeric -captures become the values (in an array if there is more than one). - -=item * - -As with array aliases it is also possible to use a numbered variable as -a hash alias. Once again, the only difference is where the resulting -C object is stored: - - rule one_to_many { (\w+) \: (\S+) (\S+) (\S+) } - - if ms/ %0=+ / { - # $/[0] contains a hash, in which each key is provided by - # the first subcapture within C, and each - # value is an array containing the - # subrule's second, third, fourth, etc. subcaptures... - - for %($/[0]) -> $pair { - say "One: $pair.key()"; - say "Many: { @($pair.value) }"; - } - } - -=item * - -Outside the regex, C<%0> is a shortcut for C<%($0)>: - - for %0 -> $pair { - say "One: $pair.key()"; - say "Many: @($pair.value)"; - } - - -=back - -=head3 External aliasing - -=over - -=item * - -Instead of using internal aliases like: - - m/ mv @=+ $= / - -the name of an ordinary variable can be used as an I alias, like so: - - m/ mv @OUTER::files=+ $OUTER::dir= / - -=item * - -In this case, the behavior of each alias is exactly as described in the -previous sections, except that any resulting capture is bound -directly (but still hypothetically) to the variable of the specified -name that must already exist in the scope in which the regex is declared. - - -=back - -=head2 Capturing from repeated matches - -=over - -=item * - -When an entire regex is successfully matched with repetitions -(specified via the C<:x> or C<:g> flag) or overlaps (specified via the -C<:ov> or C<:ex> flag), it will usually produce a sequence -of distinct matches. - -=item * - -A successful match under any of these flags still returns a single -C object in C<$/>. However, this object may represent a partial -evaluation of the regex. Moreover, the values of this match object -are slightly different from those provided by a non-repeated match: - -=over - -=item * - -The boolean value of C<$/> after such matches is true or false, depending on -whether the pattern matched. - -=item * - -The string value is the substring from the start of the first match to -the end of the last match (I any intervening parts of the -string that the regex skipped over in order to find later matches). - -=item * - -Subcaptures are returned as a multidimensional list, which the user can -choose to process in either of two ways. If you refer to -C<@().flat> (or just use C<@()> in a flat list context), the multidimensionality -is ignored and all the matches are returned flattened (but still lazily). If -you refer to C, you can get each individual sublist as a C -object. As with any multidimensional list, each sublist can be lazy separately. - -=back - -For example: - - if $text ~~ ms:g/ (\S+:) / { - say "Full match context is: [$/]"; - } - -But the list of individual match objects corresponding to each separate -match is also available: - - if $text ~~ ms:g/ (\S+:) / { - say "Matched { +lol() } times"; # Note: forced eager here by + - - for lol() -> $m { - say "Match between $m.from() and $m.to()"; - say 'Right on, dude!' if $m[0] eq 'Perl'; - say "Rocks like $m"; - } - } - -=back - -=head1 Grammars - -=over - -=item * - -Your private C rule shouldn't clobber someone else's -C rule. So some mechanism is needed to confine rules to a namespace. - -=item * - -If subs are the model for rules, then modules/classes are the obvious -model for aggregating them. Such collections of rules are generally -known as I. - -=item * - -Just as a class can collect named actions together: - - class Identity { - method name { "Name = $!name" } - method age { "Age = $!age" } - method addr { "Addr = $!addr" } - - method desc { - print &.name(), "\n", - &.age(), "\n", - &.addr(), "\n"; - } - - # etc. - } - -so too a grammar can collect a set of named rules together: - - grammar Identity { - rule name { Name '=' (\N+) } - rule age { Age '=' (\d+) } - rule addr { Addr '=' (\N+) } - rule desc { - \n - \n - \n - } - - # etc. - } - -=item * - -Like classes, grammars can inherit: - - - grammar Letter { - rule text { $=+? } - - rule greet { [Hi|Hey|Yo] $=\S+? ',' } - - rule close { Later dude ',' $=.+ } - - token line { \N* \n} - } - - grammar FormalLetter is Letter { - - rule greet { Dear $=\S+? ',' } - - rule close { Yours sincerely ',' $=.+ } - - } - -=item * - -Just like the methods of a class, the rule definitions of a grammar are -inherited (and polymorphic!). So there's no need to respecify C, -C, etc. - -=item * - -Perl 6 will come with at least one grammar predefined: - - grammar STD { # Perl's own standard grammar - - rule prog { * } - - rule statement { - | - | - |
- - - -         - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Syn pod)(Justification)(Explanation)
1OverviewS01-overview.podApocalypse
2Bits and PiecesS02-bits.podApocalypseExegesis
3Summary of Perl 6 OperatorsS03-operator.podApocalypseExegesis
4Blocks and StatementsS04-control.podApocalypseExegesis
5Regexes and RulesS05-regex.podApocalypseExegesis
6SubroutinesS06-subroutines.podApocalypseExegesis
7Lists and Iteration [DRAFT]S07-lists.pod
8Capture and Argument ListsS08-capture.pod
9Data StructuresS09-data.pod
10PackagesS10-packages.pod
11Compilation UnitsS11-modules.pod
12ObjectsS12-objects.podApocalypse
13OverloadingS13-overloading.pod
14Roles and Parametric Types [DRAFT]S14-roles-and-parametric-types.pod
15Unicode [DRAFT]S15-unicode.pod
16IO / User / Group [DRAFT]S16-io.pod
17ConcurrencyS17-concurrency.pod
18Compiling(TBD)
19Command line interface [DRAFT]S19-commandline.pod
20Introspection(Draft)
21Calling foreign code [DRAFT]S21-calling-foreign-code.pod
22Distributions, Recommendations, Delivery and InstallationS22-package-format.pod
23Security(TBD)
24TestingS24-testing.pod
25Portable perl(TBD)
26DocumentationS26-documentation.pod(HTML rendering of S26 is known to be incomplete)
27Perl culture(Draft)
28Special namesS28-special-names.pod
29Builtin Functions [DRAFT]S29-functions.pod
30Standard perl library(TBD)
31Pragmatic modules [DRAFT]S31-pragmatic-modules.pod
32Setting library [DRAFT] 
Basics+ [DRAFT]Basics.pod
Callable* [DRAFT]Callable.pod
Containers* [DRAFT]Containers.pod
Exception* [DRAFT]Exception.pod
IO* [DRAFT]IO.pod
Numeric* [DRAFT]Numeric.pod
Rules* [DRAFT]Rules.pod
Str [DRAFT]Str.pod
Temporal+Temporal.pod
33Diagnostic messages(TBD)
99GlossaryS99-glossary.pod
- -
-

Indexes

- - -
- -
-

S32 Key

- -
-
* = Documents related types as well
-
+ = Not a type name, but documents a group of types
-
-
- - -
-

Differences from Perl 5

- - - -

-The Differences document is stored in docs/Perl6/Perl5/Differences.pod -in the mu repository, -if you'd like to make updates to it. Your changes will automatically appear on the web server in less than one hour. -

-
- -
-

Further reading

- -

For further information on Perl 6, links to examples, tutorials etc. please -visit perl6.org, the official Perl 6 -homepage.

-
- - -
-

About this page

- -

The HTML version of Synopses contains code snippets from the official - test suite. In other words, the .t files from the test suite are -divided into pieces and inserted after corresponding paragraph of -the Synopses. The job is done by the Perl 5 script util/smartlinks.pl -living in the mu repository. It runs once every hour and is -triggered by the file util/update-design.perl6.org.sh in the mu -repository. It runs as user design.perl6.org on hack.p6c.org -and is copied to the web server via rsync.

-
- - - - diff --git a/html/perl-with-historical-message.css b/html/perl-with-historical-message.css deleted file mode 100644 index e9fbcf24..00000000 --- a/html/perl-with-historical-message.css +++ /dev/null @@ -1,53 +0,0 @@ -@import 'perl.css'; -/* We can't include the rules below inside perl.css, because it's used by other sites, - and we can't specify more than one stylesheet to the podhtml.pl program. So... import -*/ - -body { - padding-top: 100px; - margin: 5px auto; -} - -body:before { - content: "Note: these documents may be out of date. For Perl 6 documentation see docs.perl6.org; for specs, see the official test suite."; - text-align: center; - background: #600; - color: white; - width: 100%; - display: block; - padding: 10px 20px; - font-size: 110%; - position: fixed; - z-index: 10; - top: 0; - left: 0; -} - -:target { - display: block; - padding-top: 90px; -} - -[id^="line_"] { - position: relative; -} - -[id^="line_"]::before { - color: transparent; - content: attr(id); - left: -9em; - position: absolute; -} - -[id^="line_"] + [id^="line_"]::before { - content: none; -} - - -[id^="line_"] { - position: relative; -} - -.pod:hover [id^="line_"]::before { - color: #ddd; -} diff --git a/html/perl.css b/html/perl.css deleted file mode 100644 index ae37ab64..00000000 --- a/html/perl.css +++ /dev/null @@ -1,291 +0,0 @@ -/* - - - WARNING: this file is used by multiple .perl6.org websites (like docs.perl6.org) - - -*/ - -/* CSS File for Modern Browsers */ -/* also, perl-ns4.css stops ns4 from crashing. */ -/* Originates from svn:pugs/docs/feather/perl.css */ - -BODY { - font-family:helvetica,sans-serif; - font-size:14px; - font-weight:normal; - width: 730px; - margin: 5px; -} - -UL{ - list-style-type: square; -} - -A { - text-decoration: none; -} - -th { - text-align: left; -} - -tr th { - font-weight: bold; -} - -.RIGHT { - text-align: right; -} - -.HOME { - text-align: right; - text-decoration: underline; -} - -.error { - color: #DD0000; -} - -/* specify link and visited so the 'hover' style doesn't apply to - other links, like those which are just NAME anchors. */ -A:link:hover { - text-decoration: underline; - color: #8B0000; /* dark red */ -} -A:visited:hover { - text-decoration: underline; - color: #8B0000; /* dark red */ -} - -TD { - font-size:14px; -} - -.SHADED { - background-color: #d2b48c; - font-size:14px; - font-weight: bold; - font-family:helvetica,sans-serif; -} - -/* Header */ -.BANNER { - font-weight: bold; - font-size:18px; - color: #fff; - font-family:helvetica,sans-serif; - background-color:#191970; - padding-top: .5em; - padding-left:.5em; - padding-bottom:.5em; - border-bottom: 4px solid #39f; - border-top: 4px solid #39f; - letter-spacing: 2px; - /* not valid CSS - line-spacing: 2px; */ -} - -/* Navigation */ -#NAV { - width: 180px; - font-size:12px; - margin:0em; - margin-top: -1px; - padding:7px; - background-color:#eee; - border-right:1px solid #191970; - border-left:1px solid #191970; -} - -.topNAV { -} - -.sideNAV { - background-image: url("/simages/onion/onion-160x160a.gif"); - background-position: bottom; - background-repeat: no-repeat; -} - -#MAIN { - font-size:12px; - margin-top:1em; - margin-left:1em; -} - -#MAIN TD { - font-size:12px; -} - -.INDENT { - font-size:12px; - margin-left:1em; -} - -.BEGINNER { - font-size:12px; - border:1px solid orange; - background-color: #fffacd; /* lemonchiffon */ - padding:10px; - width: 400px; - margin-top: 1.5em; -} - -.NAVITEM { - padding-bottom:.5em; - padding-top:1em; - width: 180px; -} - -.MENU { - padding-bottom:1em; - width: 180px; - border-bottom:1px solid #191970; -} - -.TOPIC { - font-weight: bolder; - font-size: 16px; - color: #191970; - font-family:helvetica,sans-serif; - text-decoration: underline; - padding-bottom: 4px; -} - -.NAVLINE { - font-size:12px; -} -.SMALL { - font-size: xx-small; -} -/* -.TITLE { - color: #ccff66; -} -*/ -.ITEMS { - font-size:14px; -} - -.CR { - border-left: 1px solid #191970; - border-right: 1px solid #191970; - border-bottom: 1px solid #191970; - width: 180px; - background-color:#eee; - color: #333; - padding:7px; - font-size: x-small; -} - -.DESCRIPTION { - padding-bottom:1em; - padding-right:1em; -} - -.TAGLINE { - letter-spacing: 2.5px; - color: #666; - font-size: 14px; - font-family: Verdana, Sans-Serif; - font-weight: 800; - font-style: italic; - padding-top: 3px; - border-top:2px solid #191970; - margin-top: -10px -} - -/* for perl-directory style */ -.PDFOOTER { - font-size: 12px; - padding-top: 0px; - padding-bottom: 2px; - margin-bottom: 12px; -} - -/* for default style */ -.FOOTER { - font-size: 12px; - padding-top: 3px; - border-top:2px solid #191970; - margin-top: -10px -} - -HR { - color: #191970; - text-align: center; /* what does this do on a HR? */ - padding-top: .5em; - padding-bottom:.5em; -} - -.CAMEL { - float: right; - /* margin-top: -5em; */ -} - -H3 { - font-size: 14px; - font-family:verdana,helvetica,sans-serif; - font-weight: bolder; -} - -TR { - vertical-align: top; -} - -TD.NOVERTPAD { - padding-top: 0; - padding-bottom: 0; -} - -IMG.border { - border-width: 1px; - border-color: #191970; - border-style: solid; - padding: 4px; - margin: 2px; - background: white; -} - -.newsitem { - width: 80%; - text-align: justify; -} - -P.fancyp:first-letter { - font-size: 215%; float: left; font-family: serif; padding: 1px; -} - -.orangebox { - padding: 4px; - border: 1px solid orange; - font-size: 120%; - font-weight: 800; - text-align: center; - padding: 10px 0 10px 0; - margin-top: 10px; -} - -.smartlink { - margin: 0 0 0 0; - padding: 0 0 0 0; - background-color: #def; - color: #000; -} - -.smartlink a { - color: #039; -} - -.snip { - font-family: "Courier New", Courier, Monospace; - font-size: 12px; - line-height: 0.8em; -} - -.smartlink-file { - text-align: right; - margin: 0 0 0 0; - padding: 0 0 0 0; -} - diff --git a/html/style.css b/html/style.css deleted file mode 100644 index c2cd1b7e..00000000 --- a/html/style.css +++ /dev/null @@ -1,86 +0,0 @@ -body { - font-family: sans-serif; - line-height: 1.2; - margin: 0; - padding: 1.5em 0; -} - -header, main, footer { - box-sizing: border-box; - margin: auto; - max-width: 100vw; - width: 800px; -} - -header, aside { - background: #eee; - border-radius: 1em; - border: 0.2em solid #ddd; - color: #000; - margin-bottom: 1em; - padding: 0em 1em; -} - -header { - box-shadow: 0.3em 0.3em 0.6em #888; - font-weight: bold; - min-height: 200px; -} - -body > header img { - float: right; - position: relative; - right: -2em; - top: -1.5em; -} - -.specs { - background: #e47286; - border-color: #e43b59; -} - -header + * { - clear: both; -} - -table { - overflow-x: auto; -} - -tbody th { - text-align: left; -} - -a:link { - border-bottom: 1px dotted currentColor; - text-decoration: none; -} - -a:link:hover { - border-bottom: none; - text-decoration: underline; -} - -html { - padding-top: 100px; -} - -html:before { - content: "Note: these documents may be out of date. For Perl 6 documentation see docs.perl6.org; for specs, see the official test suite."; - text-align: center; - background: #600; - color: white; - width: 100%; - display: block; - padding: 10px 20px; - font-size: 110%; - position: fixed; - z-index: 10; - top: 0; - left: 0; -} - -:target { - display: block; - padding-top: 90px; -} diff --git a/pod6-files b/pod6-files deleted file mode 100644 index 638116fa..00000000 --- a/pod6-files +++ /dev/null @@ -1,7 +0,0 @@ -# this file contains a list of all the synpses that are written in -# Perl 6 pod, and what files they should generate. They are handled -# by a separate tool. -# input and output file name must be separated by a hard tab character. -S15-unicode.pod S15.html -S26-documentation.pod S26.html -# vim: noexpandtab ts=30 diff --git a/v6d.pod b/v6d.pod deleted file mode 100644 index abe1f0bb..00000000 --- a/v6d.pod +++ /dev/null @@ -1,5 +0,0 @@ -=encoding utf8 - -This document moved to L - -=cut From 87b211429767b2b99f7003bc234188ae1907b8ae Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Wed, 18 Oct 2023 08:07:24 +0200 Subject: [PATCH 26/47] grammar --- S26-documentation.pod | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 2a1a8cd0..1b703a30 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2239,7 +2239,7 @@ a commonly used format for writing mathematical equations. =end code -I possible to define the formule caption using the C<:caption> attribute. +It possible to define the formule caption using the C<:caption> attribute. =begin code :allow =formula B< :caption > From c1d5701e6211250ebd8be66fdc6e495d01d4962e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 5 Nov 2023 18:45:09 +0100 Subject: [PATCH 27/47] section --- S26-documentation.pod | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 1b703a30..e3ce7809 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -6,9 +6,9 @@ This file is deliberately specified in Raku Pod format =TITLE Raku Documentation -=for AUTHOR -Damian Conway |mailto:damian@conway.org>> -Aliaksandr Zahatski |mailto:zag@cpan.org>> +=for AUTHORS +=item Damian Conway |mailto:damian@conway.org>> +=item Aliaksandr Zahatski |mailto:zag@cpan.org>> =VERSION pre-1.0.0 From 86cd4c4974ea2da07267b8b883f42fedc42bf606 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 3 Dec 2023 15:10:07 +0100 Subject: [PATCH 28/47] fix block --- S26-documentation.pod | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index e3ce7809..f9110475 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -6,9 +6,10 @@ This file is deliberately specified in Raku Pod format =TITLE Raku Documentation -=for AUTHORS +=begin AUTHORS =item Damian Conway |mailto:damian@conway.org>> =item Aliaksandr Zahatski |mailto:zag@cpan.org>> +=end AUTHORS =VERSION pre-1.0.0 From 4645fa014fea1ca3f4cd5e7a5753ef2a9a2efa62 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 3 Dec 2023 15:11:46 +0100 Subject: [PATCH 29/47] fix typo --- S26-documentation.pod | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index f9110475..4006ed4c 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -710,7 +710,7 @@ The general syntax is: =begin code :allow< R > R or -[ R | ] [R] +[ R | ] R =end code ...where @@ -726,7 +726,7 @@ For example: _______________________________________ ___________________________________________________ head1, head2, item1 all head1, head2 and item1 blocks from document - file:atricle.pod6 | head1, head2 all head1 and head2 blocks from atricle.pod6 file + file:article.pod6 | head1, head2 all head1 and head2 blocks from article.pod6 file file:./includes/*.pod6 | head1, head2 all head1 and head2 blocks from pod6 files placed in includes directory From 831c11b8bcbe0b6eb0b663a65a23ca0271ac65c9 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 3 Dec 2023 15:26:06 +0100 Subject: [PATCH 30/47] remove language-specific bindings and specific requirements, old references --- S26-documentation.pod | 217 ++++-------------------------------------- 1 file changed, 16 insertions(+), 201 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 4006ed4c..12e22090 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -63,14 +63,18 @@ textual content. All Pod directives are considered to be special types of comments in Raku. Every directive starts either with an equals sign (C<=>) followed -immediately by an identifier N, or with -a C<#=> or C<#|> followed immediately by whitespace or an opening bracket. +immediately by an identifier. + +An identifier composed of an alphabetical character followed by +any combination of alphanumeric characters. Alphabetic and numeric +definitions encompass relevant Unicode characters. The underscore +is consistently treated as alphabetic. Additionally, an identifier +can include isolated apostrophes or hyphens, given that the subsequent +character is alphabetic. Directives that start with C<=> can be indented like the code they interleave, but their initial C<=> must still be the first non-whitespace -character on their line. Directives that start with C<#=> or C<#|> can be placed -anywhere that a Raku comment can appear, though they are meaningful -only in a subset of those places; see L<#Declarator blocks>. +character on their line. An indented Pod block is considered to have a I, determined by the indentation of its opening delimiter. @@ -86,12 +90,11 @@ aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. Pod blocks The content of a document is specified within one or more D. -Every Pod block may be declared in any of four forms: +Every Pod block may be declared in any of three forms: L|#Delimited blocks>, L|#Paragraph -blocks>, L|#Abbreviated blocks>, or L|#Declarator blocks>. The first three forms are all equivalent; the -fourth is distinct. +blocks>, or L|#Abbreviated blocks>. +All of these forms are equivalent. Anything in a document that is neither a Pod directive nor contained within a Pod block is treated as "ambient" material. Typically this @@ -269,192 +272,11 @@ For example: Note that abbreviated blocks cannot specify configuration information. If configuration is required, use a C<=for> or C<=begin>/C<=end> instead. - -=head3 Declarator blocks - -The fourth form of Pod block differs from the first three in that it -does not specify an explicit typename. Instead, it obtains its identity -and purpose from the Raku source code to which it is attached; -specifically, from some nearby declarator. - -Declarator blocks are introduced by a special Raku comment: either C<#=> -or C<#|>, which must be immediately followed by either by a space or an -opening bracket. If followed by a space, the block is terminated by the -end of line; if followed by one or more opening brackets, the block is -terminated by the matching sequence of closing brackets. - -That is, declarator Pod blocks are syntactically like ordinary Raku -single-line comments and embedded comments. The general syntax is: - -=begin code :allow< R > - - #| R - - #|{ R - R - } - - #= R - - #={ R - R - } - -=end code - -except that the bracketed forms may use I valid Raku bracket delimiter -(including repeated opening brackets), as described in Synopsis 2. - -Declarator Pod blocks must either precede or immediately follow a valid -Raku declarator, and are then said to be "attached" to it. They are -primarily intended to simplify the documentation of code interfaces. - -Declarator blocks that start with C<#|> attach to the declarator immediately -after them (separated only by whitespace). Declarator blocks that start with -C<#=> attach to the declarator declared at the start of the line immediately -before them. In all other respects they act just like comments (i.e. they are -themselves whitespace as far as ambient source code is concerned). This means -multiple declarator blocks can be specified in a row and will all attach to the -same declarator. - -For example: - -=begin code - - #| Base class for comms necromancy hierarchy - class Magic::Necrotelecomnicon { - has $.elemental; #= Source of all power - has $!true_name; # Source of all self-protection (not documented) - - method cast(#|{ A spell } Spell $s) - #= Initiate a specified spell normally - #= (do not use for class 7 spells) - { - do_raw_magic($s); - } - - - method kast( #= Initiate a specified spell abnormally - Spell $s #= The spell to be abnormally initiated - ) { - do_raw_magic($s, :alternative); - } - - #| This subroutine does the real work - sub do_raw_magic ( - Spell $s, #= Which spell to invoke - *%options #= How to invoke it - ) {...} - } - - sub fu (Any $bar) - #=[ This text stored in C<&fu.WHY>, not in C<$bar.WHY>, - (because C is the declarator - at the I of the preceding line) - ] - - multi sub baz(Int $count, Str $name) - #=[ This text stored in C<&baz:(Int,Str).WHY> - (i.e. the C<.WHY> of the variant, not of the entire multisub) - ] - - #| Attaches to the specific parameterized role, rather than the role group itself - role R[::T] {} - role R {} -=end code - -A declarator can have multiple leading and/or trailing Pod comments, in -which case they are concatenated with an intermediate newline when -their object's C<.WHY> return value is stringified: - - #| This is a special chainsaw - #| (Why, you ask?) - my SwissArmy $chainsaw #= (It has a rocket launcher!) - - say $chainsaw.WHY; # prints: This is a special chainsaw - # (Why, you ask?) - # (It has a rocket launcher!) - -The individual leading and trailing Pod comments can be retrieved -via the returned Pod object's C<.leading> and C<.trailing> methods: - - say $chainsaw.WHY.leading; # prints: This is a special chainsaw - (Why, you ask?) - - say $chainsaw.WHY.trailing; # prints: (It has a rocket launcher!) - -The Pod object representing each Declarator block is still appended to -the current surrounding Pod object (e.g. to C<$=pod> at the top level). -Each such block representation is an object of class -C, and has a C<.WHEREFORE> method that returns -the code object or metaobject created by the declarator to which the -documentation is attached. - -In other words, C<.WHY> and C<.WHEREFORE> are inverse operations: - -=code - .WHY - ---------------------------- - | | - | v - ----------------- ----------------- - | Declared code | | Documentation | - | object | | object | - ----------------- ----------------- - ^ | - | | - ---------------------------- - .WHEREFORE - - - -When the L block|#How Pod is parsed and processed> -renders these Pod objects, it automatically includes information about -the declarator as well. For instance, the earlier Necrotelecomnicon -example might produce something like: - -=begin output - Name: Magic::Necrotelecomnicon: - Desc: Base class for comms necromancy hierarchy - - Attrs: - .elemental : Source of all power - - Methods: - .cast(Spell $s) : Initiate a specified spell normally - .kast(Spell $s) : Initiate a specified spell abnormally - - Subroutines: - do_raw_magic( : This subroutine does the real work - Spell $s, : Which spell to invoke - *%options : How to invoke it - ) - -=end output - -Note, however, that the exact rendering used for declarator blocks is -implementation dependent, and may also be pre-empted explicitly by some -L configuration statement|#How Pod is parsed and processed> -within the document, such as: - - DOC use Pod::Markovian; - -or: - - DOC INIT { - use Pod::Eiffelish::Long; - - say eiffelish_long($=pod); - - exit; - } - - =head3 Block equivalence -The first three block specifications (delimited, paragraph, and -abbreviated) are treated identically by the underlying documentation -model, so you can use whichever form is most convenient for a particular +The underlying documentation model treats all block +specifications (delimited, paragraph, and abbreviated) the same way. +It is possible to choose the form is most convenient for a particular documentation task. In the descriptions that follow, the abbreviated form will generally be used, but should be read as standing for all three forms equally. @@ -480,12 +302,6 @@ or: =end head1 =end code -Declarator blocks are distinct from these three forms. They do not have -typenames of their own, but rather take their meaning and identity from -the declared object or type to which they are attached. In general, they -are used specifically to describe that declarand. - - =head3 Standard configuration options Pod predefines a small number of standard configuration options that can be @@ -2292,8 +2108,7 @@ the flexibility of Markdown. =head2 Formatting codes Formatting codes provide a way to add inline mark-up to a piece of text -within the contents of (most types of) Pod block (including all -L). Formatting codes are +within the contents of (most types of) Pod block. Formatting codes are themselves a type of block, and may nest other formatting codes. other type of block (most often, other formatting codes). In particular, you can nest comment blocks in the middle of a formatting code: From 304daad5ed30173c55a2def9e1ea89ca86f0ec6a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 3 Dec 2023 17:53:30 +0100 Subject: [PATCH 31/47] remove language-specific bindings and requirements --- S26-documentation.pod | 174 ++---------------------------------------- 1 file changed, 5 insertions(+), 169 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 12e22090..cb8e6227 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1644,25 +1644,6 @@ or: =Image http://www.perlfoundation.org/images/perl_logo_32x104.png =end code -Named blocks are converted by the Pod parser to block objects; -specifically, to objects of a subclass of the standard -C class. - -For example, the blocks of the previous example would be converted to -objects of the classes C and -C respectively. Both of those classes -would be automatically created as subclasses of the -C class (unless they were already defined in a module -loaded via some prior L|#How Pod is parsed and processed>. - -The resulting object's C<.typename> method retrieves the short name of -the block type: C<'Xhtml'>, C<'Image'>, etc. The object's C<.config> -method retrieves the list of configuration options (if any). The -object's C<.contents> method retrieves a list of the block's -verbatim contents. - -Named blocks for which no explicit class has been defined or loaded are -usually not rendered by the standard renderers. Note that all block names consisting entirely of lowercase or entirely of uppercase letters are reserved. See L<#Semantic blocks>. @@ -1670,12 +1651,10 @@ uppercase letters are reserved. See L<#Semantic blocks>. =head3 Pod comments -All Pod blocks are intrinsically Raku comments, but -D are comments that Pod renderers ignore too. -That is, they are Pod blocks that are never to be rendered by any -renderer. They are, of course, still included in any internal Pod -representation, and are accessible via the Pod API...and via the -C<$=pod> variable within a Raku program. +D refers to Pod blocks that should not +be displayed by any renderer. However, they are still may be part of the +internal Pod representation. However, they can still be part of internal +Pod representation. Comments are useful for meta-documentation (documenting the documentation): @@ -1697,18 +1676,6 @@ and for temporarily removing parts of a document: B<=end comment> =end code -Note that, since the Raku interpreter never executes embedded Pod -blocks, C blocks can also be used as an alternative form of -nestable block comments in Raku: - -=begin code - =begin comment - for @files -> $file { - shell("rm -rf $file"); - } - =end comment -=end code - =head3 The C<=finish> block The C<=finish> block is special in that all three of its forms @@ -2494,7 +2461,7 @@ A link to the system manpages. For example: C A link to some other documentation, typically a module or part of the -core documentation; things that would normally be read with C. +core documentation. For example: =begin code :allow @@ -2706,31 +2673,6 @@ For example: laid out by A, as specified at A. =end code -Any compile-time Raku object that starts with a sigil is automatically -available within an alias placement as well. Unless the object is already -a string type, it is converted to a string during document-generation by -implicitly calling C<.perl> on it. - -So, for example, a document can refer to its own filename (as -C>), or to the subroutine inside which the specific Pod is nested -(as C>), or to the current class (as C>). -Similarly, the value of any program constants defined with sigils can be -easily reproduced in documentation: - -=begin code - # Actual code... - constant Num $GROWTH_RATE = 1.6; - - =pod - =head4 Standard Growth Rate - - The standard growth rate is assumed to be A<$GROWTH_RATE>. -=end code - -Non-mutating method calls on these objects are also allowed, so a -document can reproduce the surrounding subroutine's signature -(C>) or the type of a constant -(C>). See L<#Aliases> for further details of the aliasing macro mechanism. @@ -3216,112 +3158,6 @@ resulting low-level database handle in its private C<$!handle> attribute. By default, handles are opened to the file "C". -=head1 How Pod is parsed and processed - -Pod is just a collection of specialized forms of Raku comment. Every -Raku implementation must provide a special command-line flag that -locates, parses, and processes Pod to produce documentation. That flag -is K<--doc>. - -Hence, to read Pod documentation you would type things like: - - raku --doc perlrun - - raku --doc DBI::DBD::Metadata - - raku --doc ./lib/My/Module.pm - -When the Raku interpreter is run in this mode, it sets the compiler -hint C<$?DOC> to true. If the K<--doc> flag is given a value, that value -(with a C added) is placed in C<$?DOC>. This can be used to -specify, for example, the output format desired: - - raku --doc=HTML perldelta > perldelta.html - -Under K<--doc>, the interpreter runs in a special mode, parsing the -source code (including the Pod, as it always does) during compilation -and building the program's syntax tree. However, during parsing and -initialization under K<--doc>, the interpreter executes any -C, C, and C blocks (and equivalents, such as C -statements and subroutine declarations) that are preceded by the special -prefix: C - -When the K<--doc> is I specified on the commandline, blocks and -statements that are preceded by the C prefix are not executed at all. - -By default, once the C phase is complete, the interpreter then -calls a special default C block that walks the AST and -generates the documentation, guided by the content of the C<$?DOC> hint, -the C<$=pod> tree, and any C blocks that have loaded Pod-related -handler code. - -Because the conversion of documentation is just a variation on the -standard Raku compilation process, the processing of any given file of -Pod can be modified from within that file itself by the appropriate -insertion of C blocks. For example: - - DOC use Pod::Markovian; - -or: - - DOC BEGIN { - use Pod::Literate; - - if ($?DOC ~~ /short/) { - literate_sequence(< - NAME - AUTHOR - SYNOPSIS - COPYRIGHT - WARRANTY - DESCRIPTION - INTERFACE - DIAGNOSTICS - >); - } - else { - literate_sequence(:default); - } - -You can even I the standard Pod processor with your own, so -long as you remember to exit before the default C can run: - - DOC INIT { - use My::Pod::To::Text; - - pod_to_text( $=pod ); - - exit(0); - } - -The idea is that developers will be able to add their own documentation -mechanisms simply by loading a module (via a C) to augment or -override the default documentation behaviour. Such mechanisms can then -be built using code written in standard Raku that accesses C<$=pod>, -as well as using the C<.WHY> and C<.WHEREFORE> introspection methods of -any constructs that have attached Pod blocks. - -Note also that this mechanism means that, on many systems, you can -create a self-converting documentation file like so: - -=begin code - #! /usr/bin/raku --doc - - =begin pod - - =head1 A document that can write itself - - Executing this document from the commandline will automatically - convert it to a readable text representation. - - =head2 Et cetera - ... - - =end pod - -=end code - - =begin SUMMARY =head2 Directives From eb9a0df6f844ecaeefaa7ecf7ec07532c2121379 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 10 Dec 2023 18:59:28 +0100 Subject: [PATCH 32/47] remove draft version --- S26-documentation.pod | 46 ------------------------------------------- 1 file changed, 46 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index cb8e6227..631d2ccd 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -2698,52 +2698,6 @@ rather than: =nested The emergency signal is: dot dot dot dash dash dash dot dot dot. -=head3 Backward links - -Bidirectional or backward linking refers to the ability to navigate -from a destination page back to the source page through -a hyperlink or other means. - -Usual link are works by the following way: - -=begin code :allow - C> -> Perl data page - source destanation -=end code - -Backward is working in anothe manner: - -=begin code :allow - C> <- Perl data page - destanation source -=end code - -Here are examples of bidirectional or backward linking: - -=begin code :allow - This text can reveal the meaning of B> -=end code - -or: - -=begin code :allow - We discuss here about B>. -=end code - -A contextual backlink displays not only a reference -from another location, but the specific context around that -reference—for instance, the page of a book or the referencing -paragraph. - -Backward links operate similarly to standard links -but might be distinguished by color. - -Backward links may be highlighted by color, and it is essential -to see the context surrounding the backlink to understand -the implied meaning. Backlinks on the source page can be displayed -with surrounding text chunks or placed at the end of the text, -in the margin of the page, or highlighted in some other way. - =head3 Entities From 34b4f079c818563cd07c7534482cfb8e1fc5a0ad Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 24 Dec 2023 09:56:59 +0100 Subject: [PATCH 33/47] remove :formatted --- S26-documentation.pod | 58 +++++++------------------------------------ 1 file changed, 9 insertions(+), 49 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 631d2ccd..adf2f73b 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -37,6 +37,7 @@ Raku Documentation =item C<=encoding> directive, =item C> due to C<=toc> block, =item C>, C> due to C<=include> block, + =C<:formatted> attribute, =end CHANGES @@ -421,47 +422,6 @@ in the final rendered document. =end defn -=begin defn -C<:formatted> - -This option specifies that the contents of the block should be treated as if -they had one or more L placed around them. - -For example, instead of: - -=begin code - =for comment - The next para is both important and fundamental, - so doubly emphasize it... - - =begin para - B> - =end para -=end code - -you can just write: - -=begin code :allow - =begin para B<:formatted> - Warning: Do not immerse in water. Do not expose to bright light. - Do not feed after midnight. - =end para -=end code - -The internal representations of these two versions are exactly the same, -except that the second one retains the C<:formatted> option information -as part of the resulting block object. - -Like all formatting codes, codes applied via a C<:formatted> are -inherently cumulative. For example, if the block itself is already -inside a formatting code, that formatting code will still apply, in -addition to the extra "basis" and "important" formatting specified by -C<:formatted>. -=end defn - =begin defn C<:lang> @@ -2867,17 +2827,17 @@ ordinary text. The C<=config> directive allows you to prespecify standard configuration information that is applied to every block of a particular type. -For example, to specify particular formatting for different levels of -heading, you could preconfigure all the heading blocks with -appropriate formatting schemes: - =begin code - =config head1 :formatted :numbered - =config head2 :like :formatted - =config head3 :formatted - =config head4 :like :formatted + + =config code :lang :allow + =config head1 :numbered + =end code +Here, two configurations are outlined. The first one sets +the language for code blocks to C and allows bold formatting +The second establishes that all level 1 headings will be numbered. + The general syntax for configuration directives is: =begin code :allow< R > From 146dadee750e2541e0ab2f445b999950a26a1e1e Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 24 Dec 2023 09:59:41 +0100 Subject: [PATCH 34/47] remove placement links --- S26-documentation.pod | 72 ++++--------------------------------------- 1 file changed, 6 insertions(+), 66 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index adf2f73b..355fdaad 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -37,6 +37,8 @@ Raku Documentation =item C<=encoding> directive, =item C> due to C<=toc> block, =item C>, C> due to C<=include> block, + =item C> - placement links, + =item Declarator block, =C<:formatted> attribute, =end CHANGES @@ -602,7 +604,7 @@ example: which would produce: -=begin nested :formatted +=begin nested 1. The Problem 2. The Solution @@ -2523,68 +2525,6 @@ For example: His Ldefn:lexiphania>> tendencies were, alas, incurable. =end code -=head3 Placement links - -A second kind of linkEthe C> or BEworks -in the opposite direction. Instead of directing focus out to another -document, it allows you to assimilate the contents of another document -into your own. - -In other words, the C> formatting code takes a URI and (where possible) -inserts the contents of the corresponding document inline in place of the -code itself. - -C> codes are handy for breaking out standard elements of -your documentation set into reusable components that can then be -incorporated directly into multiple documents. For example: - - =COPYRIGHT - P - - =DISCLAIMER - P - -might produce: - -=begin nested -B - -This document is copyright (c) MegaGigaTeraPetaCorp, 2006. All rights reserved. - -B - -ABSOLUTELY NO WARRANTY IS IMPLIED. NOT EVEN OF ANY KIND. WE HAVE SOLD -YOU THIS SOFTWARE WITH NO HINT OF A SUGGESTION THAT IT IS EITHER USEFUL -OR USABLE. AS FOR GUARANTEES OF CORRECTNESS...DON'T MAKE US LAUGH! AT -SOME TIME IN THE FUTURE WE MIGHT DEIGN TO SELL YOU UPGRADES THAT PURPORT -TO ADDRESS SOME OF THE APPLICATION'S MANY DEFICIENCIES, BUT NO PROMISES -THERE EITHER. WE HAVE MORE LAWYERS ON STAFF THAN YOU HAVE TOTAL -EMPLOYEES, SO DON'T EVEN *THINK* ABOUT SUING US. HAVE A NICE DAY. -=end nested - -If a renderer cannot find or access the external data source for a -placement link, it must issue a warning and render the URI directly in -some form, possibly as an outwards link. For example: - -=begin nested -B - -See: L - -B - -See: L -=end nested - -You can use the following URI forms in a -placement link: - -=item C and C -=item C - -For L C> works as inline equivalent of a C<=picture> block -in the following form: C>. - =head3 Contextual backlinks Pod introduces the concept of contextual backward links C> (or contextual backlinks), @@ -2620,8 +2560,8 @@ standard links through color coding. =head3 Alias placements -A variation on placement codes is the C> code, which is replaced -by the contents of the named alias or object specified within its delimiters. +The C> code is replaced by the contents of the named alias or object +specified within its delimiters. For example: =begin code @@ -3138,7 +3078,7 @@ attribute. By default, handles are opened to the file "C". C> Module-defined code (C:R>>) C> Note (not rendered inline) C> Strikethrough - C> Placement link, inline eqivalent for C<=picture> block + C> Inline eqivalent for C<=picture> block C> reserved C<...>> Replaceable component or metasyntax C> Space characters to be preserved From ea921d21b9de68595b80ad68f73895d59aaa9766 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 24 Dec 2023 10:01:18 +0100 Subject: [PATCH 35/47] remove :like --- S26-documentation.pod | 58 ++++++------------------------------------- 1 file changed, 8 insertions(+), 50 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 355fdaad..807f21b1 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -40,6 +40,7 @@ Raku Documentation =item C> - placement links, =item Declarator block, =C<:formatted> attribute, + =C<:like> attribute =end CHANGES @@ -450,22 +451,6 @@ values for the C<:lang> attribute: =end defn -=begin defn -C<:like> - -This option specifies that a block or config has the same formatting -properties as the type named by its value. This is useful for creating -related L or for making -user-defined synonyms for existing types. For example: - -=begin code - =config head2 :like :formatted - - =config Subhead :like -=end code - -=end defn - =begin defn C<:allow> @@ -2788,41 +2773,18 @@ The general syntax for configuration directives is: A C<=config> is a directive, not a block. Hence, there is no paragraph or delimited form of the C<=config> directive. Each C<=config> specification is lexically scoped to the surrounding -block in which it is specified. +block or file in which it is specified. Note that, if a particular block later explicitly specifies a configuration option with the same key, that option overrides the -pre-configured option. For example, given the heading configurations in the -previous example, to specify a I-basic second-level heading: +pre-configured option. For example, given the code blocks configurations in the +previous example, to specify another langiage for code block: =begin code - =for head2 :formatted - Details -=end code - -The C<:like> option causes the current formatting options for the -named block type to be (lexically) I by the complete -formatting information of the block type specified as the C<:like>'s -value. That other block type must already have been preconfigured. Any -additional formatting specifications are subsequently added to that -config. For example: - -=begin code :allow - =comment In the current scope make =head2 an "important" variant of =head1 - =config head2 B<:like> :formatted -=end code - -Incidentally, this also means you can arrange for an explicit C<:formatted> -option to I an existing C<=config>, rather than replacing -it. Like so: - -=begin code :allow - =comment Mark this =head3 (but only this one) as being important - (in addition to the normal formatting)... - =head3 B<:like> :formatted + =for code :lang + print(JSON.stringify([1,2]])); =end code - =head3 Pre-configuring formatting codes You can also lexically preconfigure a L, @@ -2831,18 +2793,14 @@ by naming it with a pair of angles as a suffix. For example: =begin code :allow =comment Always allow E<> codes in any (implicit or explicit) V<> code... B<=config V<> :allow> -=end code - -=begin code :allow - =comment All inline code to be marked as important... - B<=config C<> :formatted> + =comment All inline code allows I<> + B<=config C<> :allow> =end code Note that, even though the formatting code is named using single-angles, the preconfiguration applies regardless of the actual delimiters used on subsequent instances of the code. - =head2 Aliases The C<=alias> directive provides a way to define lexically scoped From 4b95b96c302cc1065c7c9fe4914b84432392f8c4 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 25 Dec 2023 16:33:22 +0100 Subject: [PATCH 36/47] update changes --- S26-documentation.pod | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/S26-documentation.pod b/S26-documentation.pod index 807f21b1..2e2773b7 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod @@ -1,10 +1,10 @@ =begin pod =comment -This file is deliberately specified in Raku Pod format +This file is deliberately specified in Podlite format =TITLE -Raku Documentation +Podlite - a lightweight markup language =begin AUTHORS =item Damian Conway |mailto:damian@conway.org>> @@ -39,8 +39,8 @@ Raku Documentation =item C>, C> due to C<=include> block, =item C> - placement links, =item Declarator block, - =C<:formatted> attribute, - =C<:like> attribute + =item C<:formatted> attribute, + =item C<:like> attribute =end CHANGES @@ -90,8 +90,7 @@ thereafter considered the first column of the entire block's contents. As with Raku heredocs, the virtual margin treats leading tabs as aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. -=head2 -Pod blocks +=head2 Pod blocks The content of a document is specified within one or more D. Every Pod block may be declared in any of three forms: From be06ea40d48f9d341aca69afcc7874023b326154 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 1 Jan 2024 15:04:21 +0100 Subject: [PATCH 37/47] fix ext, add assets --- ...documentation.pod => S26-documentation.pod6 | 5 ++--- assets/LICENSE | 10 ++++++++++ assets/podlite_logo.pdf | Bin 0 -> 304347 bytes assets/podlite_logo.png | Bin 0 -> 42753 bytes 4 files changed, 12 insertions(+), 3 deletions(-) rename S26-documentation.pod => S26-documentation.pod6 (99%) create mode 100644 assets/LICENSE create mode 100644 assets/podlite_logo.pdf create mode 100644 assets/podlite_logo.png diff --git a/S26-documentation.pod b/S26-documentation.pod6 similarity index 99% rename from S26-documentation.pod rename to S26-documentation.pod6 index 2e2773b7..640b2972 100644 --- a/S26-documentation.pod +++ b/S26-documentation.pod6 @@ -3,8 +3,7 @@ =comment This file is deliberately specified in Podlite format -=TITLE -Podlite - a lightweight markup language +=TITLE Podlite - a lightweight markup language =begin AUTHORS =item Damian Conway |mailto:damian@conway.org>> @@ -3051,6 +3050,6 @@ attribute. By default, handles are opened to the file "C". =end SUMMARY -=LICENCE Artistic license 2.0 +=LICENSE Artistic license 2.0 =end pod diff --git a/assets/LICENSE b/assets/LICENSE new file mode 100644 index 00000000..b48a8cd8 --- /dev/null +++ b/assets/LICENSE @@ -0,0 +1,10 @@ + +All assets in this directory including, but not limited to, logos, icons +and images are copyright © 2019-2024 by Aliaksandr Zahatski, all rights reserved. + +Content in this directory is licensed under a Creative Commons Attribution 4.0 International license. + +Under the terms of this license, you must include an attribution to the Podlite project, with a link (https://podlite.org/), if you display these logos or derivates thereof. + +https://creativecommons.org/licenses/by/4.0/ + diff --git a/assets/podlite_logo.pdf b/assets/podlite_logo.pdf new file mode 100644 index 0000000000000000000000000000000000000000..121a6250a727cd63756dda78b1d76d4580d8b952 GIT binary patch literal 304347 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 A78zd+0jSwc&b^aMnLE$ya9*a=5q>D) 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

J0;}0e`??#>`^E)C-2xrM~9XN580{=c9OQ# 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 z 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

B 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⁡)-Fhg-#@-@*ySbm;F3e*KuRnVeN1=jOg#QV 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

)P(mly`xG`?JQdbAmZ+u|Arol4xSD~& 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 XW(hFwA4LQER98{sgFy5x4EX*J6y~n1 literal 0 HcmV?d00001 diff --git a/assets/podlite_logo.png b/assets/podlite_logo.png new file mode 100644 index 0000000000000000000000000000000000000000..dd3bb0dbc28f6bed990e9b139561445ce3a1a565 GIT binary patch literal 42753 zcmb??by$>7)b=jDQo2e=s<29TEMT!J$kMP&BaMO*(hUNN2!bL@NG?csEZq{41`Pr$ zsdPx!H~4$M@BjC@J{VEpnR#Z;+~+>`IWvZ8s43E(V>t(bKxma7-q(UasG`sQP?3V4 zboZIGg1?~7T8b!0VISKc2!s@(p@Mm!=%{jfdg|}*kHuo|+`02m>LK_lD=I51CwKGa zZAnQek`$Aa5S93^NeW9!iky8b zE-Ee|{O{|(C(nL(_74e^k)w)htX|TWM|pFm`Fo}Xd!~h;?V1+tnilVxmVmZnTDoHf zTG@_S`HmT3+pJ>Sta95Nv?|d4npgidulZ|U3)+@>-IjU%mIY`HTNaI=ZCW&KS~PE3 zw1Bo@@p;1%wAKyFHqh2B+t)2S)-AuRTY=UI+L~3@npO9jRS#&ZR=ulMeXG`>eOvjfM>~oN%_{J(skpaWrG5ue(r=` z)=!({jB+qmo7xaZrj=UcxY z(EQ8)%eH^VPUyhj(C^!?`?grwTbN!@SL zhDEccWsA@27Om?RE$ik@Yv#>su2uVEldi?XjM2T?$-}x|2eq^N?)~eQoeMe!#sEJSjjL8I>sAfxrlr5ltJf_m7Bs{s zbbwz#T(s1*Ay5)hG7745H0Liev2t?r3QNe|RZ!N{H8QiZv3u^~=IQO@9}u0yew-Gugr)6%TZ^?yUU1+P8e37w>VGEXaKq(; zibeQR`}W^Lts0eibH0T;a&mWAkx89OVjZ3328w^!GMz*|9AEWr97!5dyS9CxcI*90 zjx55Mi!LM7T0*A+sig?T=58E?MxVx|E-5ni!s@dr^YOyO6tXEBM#aO2I z3az*DDkDoqk^#k5;45WqI&<&xCn?X=E)UEY*i^B&xlE7a!lba0PqOdc~T`^#t)*~5nk zORPnd$N1F%Zut|3D6|qL<8;*FtEs0)ER&3c%&zK5et7T= z;mhe56)oP->aFaOsZRC4*L&`7wQ#y<^on{(b;(%cs*;vPu6fiV7NyjK^C=^Y>yPl2 z@^R*H50(riRos_Fie4-zx>ft?(c0}eNYoYOs2$aw(E5T`y~|{3g!+dhOq=%IafnPh zpQ5$JIeUYq0#RQ9o^|g}*w4mcs5@+jRc4?bqE}uaZns z4!-Jbg;I*n^W4~`wthjCXs&WU&CPSnsN#NXt&zDInVNtSPpBAeo#9=Dhvd~KpW(#C z4(_H))8T4;Lzw4~EE0MN#7o|>gS-^}tfBit&>*-nu=mX!wd+@}S<9rE?~6(x2+wnv z5)CG1hA;x6pF}_QOKZMrHoft+mQRb0ID5giGF`)b)ZyD5AGEIFdbV=hv#BfL7&pDDS zNI1$2j|&a{HnXo&Y4T_hQxl1xf{|5Mf=NC6>`tjxaIKpA+R44AoOfV3auJAIO4r(= zf};ZNEKiI_Cc3hBYixR&*J3G1 zU~jxEXt?7XsTdCoyX{3TWIJ8`3(-6m_qx5YnHAyU{(x>Gsi^1X=qlXW&D}ahrqRSM zQ@U*YvENpL=k2e%?jC4Kx4+%7omQ`2?4)$)A1Vh&1vE&d^im8>8z(ng_r5N`ss!5vAC%Q72|t9wbWzWRW7hV>P-UDPxJ!% zd+{T_yFCaw{o6-7=CF&(R0y8tHq!8`q!@H|^t0iHHkqttePNGzt&;mH0#~C`Y4RxJ z*4lZ={&L6;?yS_lyOrSdal0ksf4Y8NlqdA;1PC;RzJ6c#vtq?gsOhS*1jB{nDoEDC z)!bb!Wc{hcN+a>+0$$MG0y(hzo%U&g|A;vVnzFfnd zM;Bj=@MM8PamncAW}y%RAgo@O=Q)9D~1Yr3A2@zrnrqbR#~J9A}rV|C4Y znz1HC@uEJf$61L2BwHnbf#eT$8qlok zv~%(o{Tpq!4VyQ2ow)&}R=Jv2T&PtTZge%XxHG{Rz z_vR6_D=x>HdgK{Z*d(o7rII>Xci(6KE1crk#j4e5aLo)7q7lf536vtTCa$SOcb3|X zvLFruc-Zr`HEOrcHzsK zO$_TS6gQ~oL zfJ3WKM>IfOEdzkTF6U@h`k9vG>k#Zo7}Wzu>bl9_pM8ycbBR)se>S3>)s#HHcaF*o z>Jp1t&x6Tp&9S4Jjk;g_N=Pb;L_C&LozIWf+G#QC^@xvT!jlOx_=%r&ViFp;VD^;% z(nZLs>FZ78LP@z)fW@3qkLz}6wV(;-$b*Z23CJf(SM|@~TF%jmD~pB;ryc3q;s!A> zmt1nK?~G0fGQ^mFy8Q)b!IZaO%R3o$Pwj%H0QG$Ey$mu#{R|kS7?O2=-nYvc%gmA zweh*5y91}uLB9Jn%~I5kQWqCDN!Sc?YND_yOSuHCQ0utgXrAWzqXSMGG7Vm+ag9o{ zYv1jd#I09ap$qi_;@@!^f%DU)-V&&1;(_;sp#5ms6-~K6d#j()Flhv>&Z^b}RuoLC zq@|9Y0wTrlKA!oV(wDnv7p2uIQWqoDvxZlg~V9 zauvKAnWm*B^jK-T9dqqR}Xm|KNL&JWQ_ zN+ExEfG4!GAKMdF7?ZyrY;_4VQ5t4T^0 z*%=)jW^7!qBJ%5%&y(vqgHQ`;-&M|y=So6lmaKKgshp`jet)B$9a84;86&%YXe#f^ zUBt8D*>W$(GKjIqYXrKp92TNo^X_Qg+I{If`1q4}xljOf{X@>Eh2(asT7CeM(G(Vwt5}jy0-F zOGk(H1DXo)yLfz|@Q!b?HAG}&x~DOvR(He5eI z6+ePE1Ez}ZYRfF_so;)IweZ_xo=Jzi>ZTS>u5=SpiqVNi*m>Axdk zM`b#axWDf!H;(Fc)4IC!;}d-76C7Q9d8x{6dV^ZUfm|ebdTxPmPiB~NQ@OC%o7V}-&^UaFCSSU z_m-B`IW-KQ^w z!P1tU+4{BdPcQnWb-CRXW81Lp*O)3br5~?u89#2fiXp#<)<_G9QztPcYb~=?)|0Hz z!t%vTJ-Z7ccPcdRR%F>KMbks%Vcl3PO2^7~|1I1w>jL_l)VS@e+s+NB$ThX8tf5h@ zk|Tw-P1b@USf&yT@nl+(@R<`o2MK>e|2D_6KId1pth?}ai!w$D)IYz6ZP(I(utN23I{Wf*^mBGqEzeBb_&*#uk)5$J4T1R8zZ4q26@y`~~^n5Rz#+GcFyJ!PWO0Ec{pB#mPK;m9$}B zxw5n8b~v=MMs1xjxH?kUPQ>KsusO zqeW!x(Gc`hZ{IfWMbJU7jNh(Uzk}atJ)MW4x|3iO72@WVNVX==jkKNmlfm`SK<=`? zh?-&MrptGX-?!%f@U8LgB9-{{KDTf+UN&lfbZKn2{swu}Qi6XSZ;>Vwnt7pnY_~v* z7mAB|$%hy$vYo1BnWw+)iVxQIjd5USjKp1uy{VL&*@f6o+d0mos49H=0FDpVG|cvW zbT}!ylCtjI^{t_mC^%qFO*nMjy+5TL6^1px%hGz~F))d3)6(=sU{Z0wL+*p#Hr_loQZQQAM(GyY+N0SNlLTq494AZkO*O@9jMCtYtD`9oBMj z#GvobQyc&A{9Vd$ixnRnU+3sGSKn$WLYl!Be|@##(C|3Y?$=9r=3tJmN#e4QSg7ED z^(6E15Qps>7&Q%%X78G|t7E%K#iUmQmgm=gl_pRh?xs`-2y>H6*{5mML=fv-QLL}4t4m1bE>WOcDlGIq>VI&T$L#uX$_AcWG=S@}if8Y{ikq@@jk)H8HgAsb z(;rwl1LKIvrdtGm5N}ZyOtbwnn%(_PJ+Ag`Zqw zokH39D>b?ZUPO;rW^fnIF(uS!<-88IMc)Q$1A`8D0QPF+6oMyXfb^y^yg_iKxNdh- zqF^J#gCjJt)!7I0^or;3WC4#ECoTrVk#3byRreZ{;Zt44(-jkCg;a&<5=*P|g#!(-BX2r7hQm_cm^T7(%SXZE#k#n+-O7X=5R1cqWqR-7bFsBd)Ik|Gb; z*={fe!@>TYts_nazN_qUpCK5YXqIw{nVfJxdTN+G!KHM4FaLujAl{nVOiOA>^^Y(_ zs#YL^oC-l4n=XMref+2-`#d^sw{u6-Fk4XbrFs-ErK66NJtV94F%j;G$u6 zj>DB`M|q|%+zg6c4@`gKH-;XbNAF$1W{8}7GIb@oi9Kph%@}3vJ2WWF84<0~!u$8| z4#kFEr!^w6m)N!PJ0*20{~m z6Mv@-elZK>-f<ME78Sm(8R8{gazK(!*7jc zA^pv|ed6o~@d&4hqa7+GrOfEN;BIp7d zFq^}Xlv;8^k}2dd)SDEU=jwQURme>jCpd5(4XMOs)(F@r8}Kx*u`)8$`M=0Uywzy= z?)2IC`i#knSiF%j?=stsQ1C+%;D0%ofm3Nm!}#As5jUldtQ*m(VzA%D0FAVfhR#|Q zQe+2unsJKJ_M*??Jxa#`>0r1=4fmwEQ#AMO&UEgLN4K9}#FMSC2Hbea7fMHmg8iK4 z*tCeUk22`~W}pObi&CAe^TeiV1m+NZIru%>JJ3c~bba$JhkT6%`GTXU-@Um8F@;d# z$)rrC*7KJ-Q?OzlFTl*4l(d`eOmxFPayAw%;S$IXYpz8*mgeZNv;EW&EBmBX@(Exw zR-;`1lS5Q1Bx0`T;E@bj!cflQSXz3+hKzp=2K&_qc|)d<7rQkRIndImYW&AG>>MtN z`h2Y;WK5b0k(x7G0v|RMunC4!D2E&04&sg%PIujIsWo1S%FDRt4wspPL}&!k(b@C= z5+Ox`4ke_f2e0hth~dWxG3-s3{j;r;l^kLlD1Tp2+? zF!3Sm`J1B@ct)?69hyQE1t2R4FI^}YY#GLxfDSrM$?|I2EuT$eIr@wpKl4$*aA%$n z3~xe^o!Ow_s`O85`~639O0RrY3JZ65Q}m7{hw#EAq7+u|^)GN^t53zF~Y|wM$^5MAub)l*L!+M7% zs&(bJ-i^ymO7P=KI~w8{M`2xAo8)9IT3B*7E^jJoTsOHyGDQWC}|wc&K4qpf)y7T+3V-tn1Vb+O!|K2Wh&5}@zEHb z#E4V2$k2DSDcW18gh=oq*7lwQD`;Ud9+A?^QQS> z;kb`4WtLdWb6k-LqMa*xeeUOQnpR7@(?=8!bT`l^gYE8>==JpK`DvrK2tMWPTbb}; z4((B`wOpy&+4G!tmTv{aS6Cq{Kq!o;&b4=2APfS&YB+(g8<{7tY7HX{k|NUuybt0Q zyQVT_I+$ZL?w!R$4M5Gmc!aLLS%IKn-ftcG`iC@pl9aV z;i-sxNs3%mU=Q5kpa3zhX_Th+YYd9#R}V{i50O{`XTyMsEWY$+I0DiIzvfs;vFa9lYzp zZ@t3+nWeXKuvDXS09VIs+h-W-Div1jo*^eFqtMalYIJ~kZRFg+uLkyD_zm%t4mzK9 z#e?i1i#7JVu9`wM9TaT%H?gYZK}PUf$<0C`JXvut3qY^tgD?9#GyS=XU#5z*3XOAZ zD|6=1k{m z9DQPnqPSmcY`*D&(D5MxK>X1vtS}|F1^T8W_@i!6k}+Y=KU*NvJL3c+$)W413w#uE z1_qD(*&i&x>pb&YEdVTv_aSPo8PLRz8_M&EU)h^%1j_uxv6mA(za~0&J6d8usp!8z zkAvUkfey#uN|o5;IQZpxo{M?cL=;r$CSZOQeUHu75yVSn6-_m>C)$3t&W5rD!_S|` zqS@sBdnMUjA<*N)_7Rj#IJ6{qjGl&Qv`RpqIfQ)1eG?K4`WXmZ)ntCLvE)z`j8y<1 z!&J1S94^zrHm;<;ehb$Ja)?A#eUxfOD|NO!IL)DWS_{NVFg)MM5xJ1!Oi%1_@YkUw z?j5k#1se>0^#26xf`U=K=0j9m0@;{`T6n+?;EV(Te1)}93nZeUmFXd(%Le2kd!b#5 z2e)vM(@07{!vkL&uW`hfI?$#EqF}=2c9e>Cr#R=e(U-)NKxo&wJ=tOO9}XHKl~bXPAl{ap2Zp5~n8 zL@=#4i60eD2mEkb%0HJF%zrt!QM}c_W~KG=Dr4qUs>(huWaSO zsOr*Fem(|sj7w%Xlj(B%%JDfj1*=G|=ztGXS(r!P{r_gxOsz%S1j)>~w|HMt;LkU- zj?Yi^U=q&l3|UEc?QZH9ZE07t3KB zsfA{ZtE!#{EEM=}R0cMY91Xw_zqkgwC=#)J328|;RT89#9_8KJnV-(gs^22AlD;Z% zjycCWNXytkt-gMLANYFg6AW$0Ra0$AJ_a^?@PuGKQAK_3`|`Dq90RYsv$1?1 zEB?->O;rx9%N#%=7~R{a_y)E#(6%!RQ>ft1tosy32WIKP#~E=@!KZH;LXp^YUy66;=V{{x$RHaK64lQ?O6_(FqZw^vlhmArP4n9X-sbGu-C#oA=JtTr&K z&=k~^Sse{wT_CeS(o~awb3+(<8G04v75oLe)Hjr~Y!{F5*KHQn0`e%3G#ds)C@u_> zb^b1oru)ABpgt{f=fF~)w2$IWylW-yS+>F7%Di3{$5#|!eY)S7=dL34c+E`Sc7gL2 z$Sge153pdkVRn*RaiIj!XSa$(ad2&TJg+3Ai_un5QIQ<*2rcLV6-VA2H@`ZPcW5fH-5uT&(YbNZ4 zYoBP_fRv@=(bL2VJN}&T0byNq?$h3!%1Y@*U{8$(d3s6VY|*ZvLKLjfI=qQwxPTAa z=w%(cy(5nG?t6HKSZ&YiZyu+3DsvV^Gv`d@y!>ow2uKj)2$28|M0IgxDBuHu>;oF# z&1gGh6bxtE-oUY3z032fdXT5q7<#B>!H9OW`u*w`{Yb&A_HK>NDzWa43Y|GXy}vV- z^zmG=jmfY-0P1?x?}ow!dK{xOJ~;M$L1D2!%Nasru|p4x-?H%CbG_Se8w~%bXuX1O zVYy>%$yT_?81sq+PZqWU0R%z8ro?m}UG=Vw7MZ+&&;8r~DR)`YJ8*HyBGHA z13RHR&~>iEjTV`g2iwu`PCM7s^7@2c*>Qi2J(ukY=V}#76`kEEzZA7szBE5Ur-ucR|tKaVBVI<;@F@- zSa>)QGf0-@0d5xP@ycHUC6!(YmWc4G0y5+x0K92hzyqu-w_kaglthFfc*dsl|( zI7WM(M+cKj5Ra0&(6F=Zf6@d6A&MPaxZvYG>|Q%TLxO@K<#UO9e4JAZN4gtQkma7T9EGO@b+JvH$&nAR`B2uw?>K&4tYW| z$NCQ{$Z>N|Qh?B}&+zl(-dT%3-d@FZx~shP=Ho(~U7tr78C4gwT5XwMX6Of;*Ab^4 z=Nv97ZB$SM=*Q349821l_;k_)0ZkkVn0ftL14O=m<9&$@!hR{>uy2Ey1QV&OH$8yDucy7up$ zr5)Vhx=1j*j)ZuD1gKI9!|VcmG7T*HQV1sEk0sV%@tsP_wdkguXZTm4pztl?8L#iM@V$&j*mWgQjX7SzP#+D&YiU|$DpdV>+jDeE<*|^ibe{VJR z+{t{&RJAwhtCr>@c{RF8k&oK3sVzjK#n5JU$u#aFu-zkDimY6f?z*purrXKRftBN` zky>sS(C@fLTqtfNEh^%o7UvqaJsPJbE&?@M!VbZ=LPjkP1G=(|!`~D79~kC30mf`) zEgx7D3*vHx1yUj6ngN2LZk~pvzl?Psz*GVD4%_9{mJF)fZu?@3VRRBW4HEhhRBtaS z812i8NX+eh+sdd6K6a4P(tqLaA@*SN0w;P`mJaBqyz2BB1YBT9^X}uqSNm3iG z#{R|vi$ov3`q*lQt38>^Pif9+_ggLUYpePQs+%7_AwX>mPZsS8jsR}LPNh2ZsvsSV zwjrRNlfZb?v^g_goS`uBQ-jP6Po^>jJPCq>;)l_fz!E)5yJ&w8=ZeSnVq^!~6E+18 z35>+Vx|ar$ewH;0Fa*eD0rH2@BFi6?Z(Eacf!BQ_VN-Q&O4Qam&~?ob9FQ^&5YJMj zynw!&(OPeiaX$lCxe``=-v|oQY0Exkfu}tkP6xPs5#gnQf$e)VVkR`#uL7dTzGyV)m;h=-?!Fkb3tupN-2mnU^v}8vt5DOZ z3z>es3*p!%#N`P^R=Y#aGf}sPIC3DPlDB`0vB;lIL*z{1n+qIe_#5n>I|0W%m-LqL zbIS#%34DUU7rpbI)r7c!2p^f;ym1clh#!h4OSbnr{OXWLqxg2q4xgFM6;ER@_)wOJA~}LdmA# zKCin<{CLr?Wp5;AA0Dr=Jm7hu$V2T2c8TUyV{6l1Lf5Eao|FE%q}%2N^oZu%ZF^EW zL9FcY1>6;&+^qjSXpBs?U4u6@^4;2zlX3$y-1xIKUtW}FVQ`|@Ba>O?UWm2?H>s{f5ENgp;Sk-qOF4;PJQ8L+%^YQO z9)zxBi?;tv^?ue*A9HeHNpA2&)s-{MID=oJ{qH+)>rP`NRcH5G4g^0-bDJ+hCCr;yu`VEc zt$NdLHrUqCQnF5s;zd_9}G0m%oK2OO9HD_vK4pkfU5ZyhT&{yDrg0aEbmXtUjrR&3V zv$38Ppj7Fu~%y5FD^gi9vte3ZecFHzdGi0fh-V zvtg3-QI8rSiY3QMS%F?n>KK+|vTDn-GRK*^z*V>MLqafICZZb#q3(*n*G9G2?JBl&|TT*07P5NJ$+R)X=Mu+O+V`i>#5O*k*r zqwLgyZ&~%)B#dW*Yn>nWSvJ$@;hOVKu69IjNjx}mcmx#5QpaKrtsFKZr7;%JnuR?VULB+g=uLli*H)lM!KQniG1hv&{(fe2R*7BI!)3hz0o2*$y151v)j7vRM^~DM zsKQh&T|vPz-+s^;yMw8f#Ef9QY;}u^R#x`GO&&*%x9Adf5XRL^RL(E5fk+U{g$2=b zXRJ8~^Zl0KdV6Z_O&yy<_adkK`#jJv0~)@&JkK51#OJkd>ox>xuHWPN#l2XplwGq* zW9a%v-@m`np`U_n*a)OuP{8*?**9@5FbEBw90*WGXu>{CnLlaY!IWJ!|RwY$jJf3ds?x-V4%(ncQ!H*fwW15J~u6)X{!Z&vZ)E7MZGQ=!J zCP1NYg%ubz7%t#jVb`<~bF_TVJomO;Q}rh6`l@q;MoUocdm|_xqE;&tSXT}S$=c~g zthe2g?twcCh_G4|R^1IT$!w2P7+BPulT7kdsr~{o-Lzl*{)<Pi>;^b)@J3mjlv1)R$yC#$EgXL4w1E`2&` zb)eE$le|1p_V5CFoqYd8k&WNcf;V62(gj>sJ(uxQ866;N_azmqo|A#xWvUDBwElja zOVlzczduIssVkcb$9@VZyJ(P0H+IjNdMd#%ZqonH%t)c7-AwX z5av#z-Pah^DFI7YYH0I5&j{xL=~05h81lU`s67O>?JPz^p+#0IV&*=A zRn^{kfe!TnoZWx|Ibm_@*r_CYqoB6uZgNFXdJNd-5M4U9=SaPTOd&ZxFB9Oxa!6*) zE75o7WEOYpKXzS}ABXS0f(yCkGfUSEEGTuPo|#XxZHws8X6oA(I82%9ccios~THGJT@+>esW6AtW2lv$L<3`aQOC=w4b-jlA!*v$Nd_2S7D=vRU{$WyY;eKzIS{ ziA?n`Kl&cd?Km|3K{()d?2EvW@;^!fH+Z_HS!j_U45(_Gl8oVWMz(LPUByNumYyvXKw!=iHUzRhF2sP$X;o1AsMXtJ&b;y}XjUl}O`Gu!eS?XfYTM+ zM>r_l8ArO1KZWg(SN}+KR?+QB1=-fPv`^A!IFS5vO?PnYY%@PE(ws-1NAw(+r16jV z8XNNhn9-d{I;-=hCeuq|zkp$!<1@!fp^qCybkB61$q<`!52CTO>qnc@Vw7JsSz>de z5y@VKe=Qj}0((gcIQOw^a+a0?`3F$Whk&6BwMZUIIB1{67{LLRyN>x&r{X8}Cnp7G zR2RUxet3Fvz{Et3C!?k$g8yXLZ8v_G`Q>+S?Lc%_lxnsV7GFw+O=Z4Ddo7GP)U+YZ zIdCMv{d!Y#mOpa-)x405VeWavGxM@rvqK3dX7`RK1`wTdPMw~y%D9>fh`4BoL;0md zLF{X|)ZkFJ9C5qp8Vie9iNX!Sl|-3-pbN&e0&gH z{Hmt3Q(U{MN zr9qrRw5h;3pI;rHQnWuvboOe!?-ZfmJfTWQ@&Lc+d9#BgPz6hEc8>Zhe1|tUm zRRorrZL=uv0l5!TBPUfO_pW99_i)@GL=V_OAhQ5L^|LLdBhVPE0&)e7Ov@~=p#VtM zYzZ4XpbfY+_3^VvRpRR?ljR9z`*D#=cQq$hJY)6A-3QIGo|%#LUU|?^D#*LgW5`XX zVsz`H1Q(QJw24<*Dfk{ID%@ic!TgMhAJryKktCvtpBX{$audtEq>@G-FJ z2hX03>hUSuun7vx@;~eSX*5S#X6n3c`|rJhq)6}#m``BX67)Rc3q54F1{m_JYoW%y z=;Dknj`PHVP++P1FppM}W#Sd|2rh~fI3+0(^t&6~bR1t1Fb-UES!KTAzoA<23#@}8 z4A6wUD`?0_W8yglP;yKQ=KN$v2~O4_n$x*y6S+=0lmg1SYUEsJFAKDxg}ja;&D#tk zP4)mg1D@u(^L3V&O2l10+H?X!S5iIJ#%}xXg{DFzrfu@k9$6Ek22bm>^vwhEWGaoH z*QKSA-6uc$jpGd*mIT;ohLdf`U_Pg5C#+k566_^#F)$y<{ZM+xi6l~_slL|-{(yV12O2 zX9@Xd6gr|uDzwAlZnPr>PV!P6;nw=uOEd!kgH8nm@rW`{7^OS4ULHyGHoou=a+7B&aOu)WO`eH(R!7y1)5_u@Z5-DIgo(T5@aGL$BfacdsJ?lz*@a>&6yUg&BJt;l*99%Q#C``ngo6^oUQ&0H2`*^ zmfPLX7_$4Yn|Vf0$$qo`^CXXV+MG?DTQqTqE9fR$if5_$+W)Pk30hn)#3UTZBahy5 z4PdV;SorJo<_w}OS#wvZkxSl1VS;R$BxsV6AejQ~{|s1G*wj%?bwM+b10n$XZ-pEs z0dgPd_}{?4NjC{aYd8OU(DC8mmnXny%!BUHL$ZvFe8?mIkpP%v^SePPTXB_M=D$U} zpp{?)hXT>2!8CgC|11wyd=rDK<{`Rp{u`^<`hx{Cp|1_V_&XiBEJU7xT9}VpD zALB5WkOc6^^Fz;w=02>QmGd!?gbsKR5h`GG_QXlC`)-x$eNE<9Uqg5VURcfsx|HXe zzvD4udKSV^4F4hjOR^X;0zv0qQnJ64r4)Us#AT+sBIO45<0Xs#!_;?xQ{DdmA3GG1 zNQ9KVlI&4NK2j(pt$=lh@236lHP%U~ zS>T)MsRxL!aRjS}#olyz{_DvbIP4i#eCy>$)bJd1TvryOUJSB;?QLkqDn}sfps;`6J-XoWQxhG6)VCuSnSPK3N`$>Q?lsbTEC0Uwsl}@MJ$@ngWDZ1!-`-pLsAFr1YZs=_4J>8H z&azlVn4>5pthTRg0Qs`?pgN#J5bW zs;n6N&%9Txm{s=^Vk546OKPkVc~z@QSxz}`T8R;#loyj;>uQW6Pt;hR$pOJ znd1j0Wxi%}8~fXQqFZMj&7ROOlis>BHZ!w(z0*T|bLI{Wmrs0K_NMEOKlSyXfCo)W zbfN24>}a^`n~D?_u(q`|iK&<>$q0J0l*EwM{9aaXCB*@=p3(gMzPE+TvWetr+~c2eX&1{ zcVMPa_@yBRzlqFOoO00nF z8K{J-aj4BpEk-ys91s3NqAo)8(uw;Wv(GMeyv6zFzAIyVV2qVHiB4lsN}MPzi%m8{ zmPv5hs48FCUX7B*y>zL(J^AGf$EOo|lxW*RmASpb;xx1UkDsU*?2;3Be7c-Ro+ag2 zub$~x(6w2t>f-;&xi+(8#Yb15+EP@clKZ4J9EtKy7sw?a@O9pmagTYuiR^B?C8qJ| z8lC3F1)e6!*3n^BWUs^}QtIJ?Fn;f%GSwo~D+)ByJBOmN&0u-j2!k{D>SbbPz`z-L zZ_sb66Ta?$f>Rhi#}${RuX^EyMzT9#ZKj{9cP2al&_@A+~vI1P)@?*bJp74dy6 zp1h)N{4UvKKk-&38sD>dLq9#c3@ z`HFPAoV8}a4!DnDtIwSiy@giwW7d?jRjs5ex=Q3@UC<-=(dw)y^D`_ZBW>?%c5sZV_kvx#r&~n8rQW`#}u& zWX#OAsa)!l!VapVgeqV{YNPO0f1la;lRNI)hOyUH&a6PSs;Qy5ccgFe_qX7KW~RYs z{;@Aw4!xG^?sckYq_+A?_q|+jygn}D$pxui{fK|~#C*in_w035+|%iNqL*IYiJml% zHP|`W+w$MAr<_FgD_q;+nI0i$Z5@+L#tt|3w!Dam`jsP%WlFNoxg_>1DMT}PVDXvU z*oSMj-vzE!H}?waRApOFLGGF77(2B6&_6j-?INxsj@x$P%)P>41%pni>sE18et&G?P~6CCZlL$u2$mm(k0mH-opwP7!sTc2uH#EcxRu^d0it+N+@HfAD@#fBEmu#00k5)P={jz0w5`n@k^C zn7ChS?K)C3-MV0rds)84a8g)c<1957)<#wa;D=*a&o5$9wp&swmxhYegceWKY)i(U zf{qc@WbtRm!j_ut+w6Iz%&cz#Je2x4uha%Abr_V(p~$!O_ddSYDvO;aT%+*CXA zqtwvi^-W3^0`~egB~*Ys6?rzwCS>TAikE(j%#}El7TZMXhVoXX)Y_i`+O>-}Kgq3H z>iEC_z_Kv2{stq|9 zVzIz%%8}A;zY+(>SkZ4uhM!PPLF?KsTg<9zojH=%YC7^;Y~tL%w6(ksdK@E*j(av6 z($3BNC@7QE_;p^ks#BgXe-PE6`ppX^&Go(?XBR#&vmHI@wxXYJjI}-r-L|F5jT93T@r8=)W=*qq8O+;O{LUlt=5chht#@F5( zl)EuF^n-9e!BMltMfJhF-CTMxDAg7;A}GEDjK7P`>r101eDHz3z2mp?sI<hU~Tz;C}G+fBE|iR$zk87Pa3W zJ`4pgg#ni9+@-hh%EaxThdX{liH8-tPX@j8yDlj@?rkUkoX@|fmLL%}TYnZ9D1_=X zK>ET%#+yh`JT|=8tOoqjl+W(G!Rg8;Swdnny=&6cbUz*5tbDvY|Fnl?7caf5@-KHK zhMv75Zav(jtKg)|w@uf&Y{LW-&kr`b^S9L?RON;^mXHs!4-g&c%^yGgFDLRVCDnWL zjh_O8U2~0LYcD+diHO#M5ca>Xdqu_&>Ag{vmFlcn&$91Jo=)I%f*-c$5Mp1*mZ*0z z(sh%m>lKD0jQ>87N;@=dcY-_ZTq)Bfp^>bnX;$hhqt1GlLkd5FsJ{_z_o(QZQ^#3H zC?kBO8MD&YFO|QOM9=l|DdZ@kOyV;LZTTr9=C_@~ z&}A8_xRQ7(B-UMXH+2dKzF6H2d!{{-v_7H2yts#lLIAKu6|ZfG1nXqQPTH zr2Ml^b8&Miki#d9r0rK9@>Gzb->t&s>qSqGnF{;Nf2CmWXp)Gi=}X6Piqi3p#rcaZQxIp1~fxLDj#gQj9lQa0%sZ~?7OaE7)gJ-Z69eCYDrjaqU;=tvRZ zz}Q&}1?CqQVLVT8jWn7rQ#o7a;ec%uRO6E1UM65A^I3P)vd0DuKqp?*Za1Ae zXL@eq1Q+W^9y0Lar=$>F34AU#&_?c^TVmL?C{(uUak$D{uEuMv>@v87L!57fKCyg_ zHraCxxI(4+)wth^hA(^XNV*86M39(oy1z{mj_V%7g1=AUzUPfZq(LA?aPT~T+dEX+ zJu;XQ!nZ>{8RkM4208(3+kcIV#KCPChU&hd?%S>$>b+B?WX6KQ&Z}{0b7!9exf>kf z2M&5|%@P~_#1LxLCta@YBWE@G+MeQh9I!1{QVK9U8JIJi)f>he@k+ez;S&#hHC_*U zksTcux7d+H?~8`hKT|}Y_<+P;7kq@0LmM{odFyZGh+%prGB=P^on9wjRAtl_z|IkNPNk{^Zh?(%2KJ6&{fgX8< zoJbcCPZdNI_@c&Kp3M#cKY4B~?$O1_$2J)I!ER2iPU>O42WIv6siTK$W#GjyaoiTN z&bN}ac_#OhMdEySlahMFdgl_^G=f*hq8;;0@cS%owTJclnMo&PxXMR0?SGzjjO&(4 zI^mRITvmD>#w;?Swr!VvPC_hhWomvEz?!coRZl-8`g6>q%~0mNc|s-h=@XV!{s%)l z{zaR@?Vjt1Rz(i9l2X=u?E^KA4R70h2g7Pd{n2+#%LcyA$1}_WQie{Y52LTmQ4m{h>P zXk)T8-?)?Go32yXZ0W}5`Iw!(GOGc6;4@}c@lw^xEppj$^pgUlVsu@L3}h(@Q665| zSETMxRhci0cu{TeKFi`5x`|sgyRPU%qEnp|N55sqKPl+f_a(lodrBbQn6|8uq49c8 z1fQqAjhXZpZ;L@8Q_icQJnaQ4uC!6s3@7B*6&J1PZhhL(N1n_%r*(n1zfJE`WH@E` zvb@MlKy-86CO@9(GM6-J{{2eJ#! zXmWo@R;*?=H84WLTaH(_am_7B58rb=ICdxPR17laqPy5nY@J;$t6%W)wZoTF9N*4M z5_ckm%jG^hYa@F#3QmRaByb=YIWj3!Lmw}_4CQ24Qoho|uJ`)0<%L3R3%9`r;q6$P z(|?UvH|^6qr1fwAu(mwS@Nib;0bL6Dx3rw?OCM=TA3t~9U+1%AZ_8FyxxBIyRYo-Z zEHi2DZF+;gP1#c#&qOAiDre;>`sFTq`~wYZ?dhG<8Z)j`f%Fqe-F||vr6Ui# zCl_+w$%Tm_CNrZ{Brc3eB=8j5PPR)~At@v8v}Jy#5xUG)Yw7tk^2T2m1HtQ*D>NMU z5=i(T(pxRP#Yyv3a!@pfpYPsXbTbY`M25dBJIxa>tkyxmcsX8{S?{wYqrx=%ADdcU)pylLMhf3v3`#n+FmJy?hHHU z#m1Qn1-`rr7LV1U>k4xzBqi0D8HgD5I~mONfW)?M`u*AaXXm$zN6SS>IGYLvwSw$Z z=0YxsC#RA!i*6GQH)}__s4C6RIyZcWtL`nW7K-Xb zD55wu{i5U6&MzUy-{dKQ4=v6Z9z@01KL~C2a@eXMI_?ld!j#Vx7|<38B~0m`3$+$~ zRzDrj@h$jtdfb!Lo>=h@Z1`7__LN>6+CGP(U}_?oBh zTDRkjm;YTEI?y(1W zM3=ap;mmWJ2j81b3B2boyc_@MHBt}tX!>=K`AyoVJ|AyZdQ=(UPVmGm@=2Q(=Zfn& z`hW9zrW24+xAi01hB)2w3KwxGy{5Qu(h+fLYV~bq^6mu2s^tBfw}0hTz5cL$ZbFNC zod2e^8NZ!eOdp?mO1Avhcz%YJa~VfR&D%-)ds3D(0ZUvm`r${D9t{Uy4SsJFUh>{L zpl#+8dD+_G?|_-|)~NmInwe1JBrCR-W5VLUT$_G2cT)L_#0+PbhF%4#9Ip&M%O za6;6-><8zXwNAw-+sYH+kGPrYUKg=;y@p2J+^W7+E>bQl@(7z(LT^-FJ|Typx!_4@ zwJihJ)zo}8sxqEFC0W;3|8Y10=c4*H+J@ZthA#0Znbh4b_xC0A+pHYC9hVy{G;P9| zSrMdM^@^E~U&%gk^q|HR=o$4(+@ubrzoPHKSbLAif3JT);^zA`QbkJPXz{=GrxJi` zg;1pYF`6FlvKM7}tL_DIn`iQ50`?W@r~s;x|0VgR_>OmOw3bw~gSXfT>bY z1z7;g+i`geBo+xu9#D~Zb=ArYfG2FjBzFVm{<<{0`=0SSuC@EBi%X`@qKKwyQhj1?1iDRsDE1SC&w3+ycY+N{X6wGcrN2V*+#;qp*|!10X$Ndc(+Rezvx zoR7UUktY+Z_EMgbtN!NgrgQHY9oHtlx)Swk#+uY1y7Y5NCS2=d%Uqa(V!G?+{=s$s zyAl0aq152!;xp<5G>UIrx3kHm5G41@q=S^!cb{qcvq|ReTz#`f6qmFijLal85T6pn z{4FFr;+y)kT8~J;2N^@qxgj((v071aXXK!`Hs-66ORVP3m)g29B^UeVSO1vwC?w$z zo)$Y(_;ax35Oad9w7dDZVW!J8v(oZQhwbM(n;*iyHYZ&cEs73oPzxzh?|cuO0c_kg z7jKXg1C1&-t^7Q;5@C;XC@ix3YA0;D^+AtLBD68xv)1P^4F?*8>lgYDS%!= zAzO9gHUvr3zv}_}>{iy*{?+7bkrhvWo|%v=w{ot=1h~{W-Kgo~tgaRMQG>j%7}s6j z0~J1@q30_rzaQ(q5g8iq|LUlF5u^f)LEVEmwO0D3nb<&LO7?CP|4on@=AJFI$_$@3 z-J;cd^TH!1xawgt5-gw(O+iryluT=ixbbG;qA-w>>3Fp{NdOqN=j?3mn3?UK_iDT& z0=R3(mJBKaH;!(rO=og3utc|^40LQdI zeJ&p|g8c~T5pm5arY0SV{C;^R^33p5!-7KF61X(ovvx%_l+3>bZAQ!FE;pTC1E1O{$GGJwkoYXj)) zYHi|ewwbkz&PfWCT;@3|jWpVSRVnv|ea$?3Pw4=E4b~AcEG6C0>gn$nzU?tjoEMSn zqm94|C*P@x|9Phh8E3K^H^SPmis@Z!cbJ%cS$^eduzuW~jrA$#98HC5Ofg}a3C71< z=Y#%<>5UBmzzQHN2?j=h)e*qN1Ra1olWgdKd;3*g%`0_>6}6HID3|>|LPO@DzKC~o zF<_>q1{(%DjOA9ZHcVUnr#PY+rEo9y&Nd6i{_1|)UT$gYI}85ZxI6aUMh4>b-uqsM zRuY`y^tIXg-~BngFwjD<(VE~MuDH2R4q}2hOl8vch1BjlJAx;E;4k0X@6nJFY}dP_ zdA0IkvTmsKiD(9?U6=vm6e-Ei9g3hr@!;LyM$rl*-Y@;HAS|hHdUHwEqPQAMSqAc9 zDi@)4=~vUQ0jMX4t4Nbz#A6~J+N^>cmK9O|`f<`401@U%7Zd+$kEO)HA}u(=@`j66O))5vUD(#D{bGn7 z*V?BuTbba6!uti*E80-k^emateLK=2Z8`ZhOXTy2wGyv&fLLV9sZy%1hqir}E6a-& z?IyT!uLNm2`M^{@`wZ%BU6*>`1lR1ZogS?LS38f(ofsibopfya&hEzts@sxyEDflG z0D^Yytqw@U5oS)yWV8JqslD@7^;jR8ps{(+Q;Fj9B94zfnSj1aSaG1OV#k3mI2=c4yU z-wjc1A)qCN%lnD36S!LyBf#QFZ$sp-IJFYxuRJYVT4J%FCM-BB{g27i_RA+`B|zVg z6dd7Ca6z;pwQH72U)#b4?bcii9|Wr;(&(U>!s)M+dk-&admX@DP?hKIpz?(b(s^U7 z7z@+dBtMFmOvoG?cWh&DO&K~*=4sK6$ucPN;V#n%%FOT-#|a7O*fhl$q^bJlu+tD7 zU(w=L|8nQ(??9p^PaKcaRfR#|`=YdBdtKXNxouNHs)|ixs<2`ulA>Sck~eg6>K}0T zd^hF=$h1}M4n^`vbs70EkAnW8_G!?SKp$pIEZMLQj;P7xj1>6QaS*gZtWx1+(!IrB zh=pA%z*z$WW$JR0$$j+{%>}l^v07K~R!v^1!6s(iz|{2_&T%n~r8zU zJaC9|(b;DYxIcSl;%^QtM{SCH7bvZi$updc8K_#RCVB?_l68@;Ub4xOCGoeo}AmstI( z`c)Q@_DYr^QI`va$`g(lR+}*U|Jh@E@!q;IXsv;Q$g7oPr_noC$II8iR#M%L$brh| zf4|z=K6q$sh} zkf860^jR~fr=$`17}wwJD>^V*l1*Zs8;p*!vQFW%M6yi*T9K`dKQ5rUXr3ItUP`hR z104>6ycqR`OqJ%( z9edh#h%S?vOb?)TNEvG7PJ><(u%LX6`l`_lWi7=$YEN|Ee4H3Jad2B(u>ED|C?tcD zTV;yCQi!`OOJQDj%8*bm?v|d(aIQo$oL=v{Cn`S3BF#o;YIM8k zCVEf0w*NFz%6Rb3@wJmr0Qv3_&4!&u4$%h&0w_3SC80+%hW$g_Xd&nkY5br^*4O2I z=}_D|1q~l?U`mv`yh?`opbdCkzYaPv3wp!V(R+~;g)%N9Wj%Y^6hK&vcP}vjApIIe zyavduep3yKY-pb+k&=;OmBDV!<(f!q>~;QQF5CpFY;!`M`^7D!QMQlNyc;S3%)Z=$ zdB*MIq9x;}<)X&CpGGh+omM+kDg--&ilpR7FHROQW&2HtL@APUj_EivEonL_sRz+d zQWTe`R~AANUs%RobQPQZ6G8#-ci{10Rb@OsQ>L2Iv!ZkGutzfX(!qDS=3M)oiniA) zB{~bI_hVw#N!Vxj`b|)Mzxvt&tC?7v<3>@lb6Et6n7Nni-U^^>cX`hTAIULC z+m>tBNOirl-9wkMKA$!#u*koft^YqNnx9B(FEj(WlE+RAV1KfBii!2<9Ot^&XIv3* z$BVkzpCU?a?Ju{?=_|2*o=K9dA1((4f;_`_Wr8F?yohxn-Ga~ zOHPuvr>?OdIkS8H&t}VI6w>dIW^eA6Jcl^fjQl_OIf}k#8LB5iY=Cks`B-4pTinmO zjvm0Uxb>8!PeB%1WGPgwl|876I36WR2Z0N$pvsdOo?+;JdtKJ`1bS-#Ev#lyb3O6~ z9}e%eL)7HCk~1B=za}Fi#rXH>>ayv$6C+UFUIz`n^qx2ELrpw`DKy{o-)y&v=V*f1 zrrm)C|La$YtRlmt$O_*4lYL1bKf7MTb$HVYtQ7-LrbjeaIezKrAldu#*nS7s_Ij|l zbw1P4K4U$$Usk{G*O{;Q!mfg(?GtitH1YJmGRQ~xU~51us*n>Nlx2GSb{a_brC&AN za2}4|KS;~HinWaeQSx|#{%R)aVnBlmMMRjm*3KU=ag`XO&X^TEs4R#?H#7yt$H8G{^QF-)e{IHChqNOiU#7m$Co*k1 zZEa;W(Aa+D9}AMeXAGyum_-t?5`_5<7{`@Xv_kIt?k0yA!+%n@2G$Z(^Zuhf0&V{> zp=qUiD1)wl7Y<@Cf#gF7THqkT|IoR~A;8)TZ0*4gO=tg-f=r@GB1z^}R2krDUnQyzmPO1g9dzCnR~>z`xZB z7-?4AfjMh6YRJCP+%RQg&=G&rF6|NyQ(-RW*~lGM3PEGz^aTV@@cnVK{=_xgaz1te za70!P_P)UmmPTiaKz;VZI|ISz&LDJ`fbzESF+w`g0e{(x#2hwHLbLDEMht#h&JN1NP*|9cfYLhDjsMwA7+fmX0J9Z-=mjDO3n22V3O zHdXh}&?XG+CYuI&_py{mU-(uJ%Ce)A7KFnJ{@ZFf?p?yQ-;_(Ht&2y5tT093N0P@I zDqS3CVF8ustex(2cf+KZRrBC$!dz$1N)sE8f~$yskPf;0i!p!>tE+X2<*uS?=O;_I~R}HZYoUoH+Rm=;|3yDC$fJOCo}|_gSx~sL%o+1tq6In`KQ#MsWkm4 zg_b(YAF^WA(Lg~v=wI=nbvkeIeQ(N8NxaXJ&k|(9qK)`xVZ1_Zq(v<(H_;tNHSE=(>>-lSJo>Mzt7oEw^UT zCqOMdV^>Nh0Hm((Z#qsp_G;!bit0e*KJlmj>nSPwF^A~^(+dqmUH|mm&dYEaw?e{& z_-zAG`gwG~h-r~V6lz;ZEO1_Si5x8+fIB6%1XOD$A@FLA^yG>|<0V5`lSrQ;9PHd8 z>o>}K$XS#2wk7c>MyWsu^*`|urGf9kUq2IWzUgI@Jv?_{ZPj%BWCxjeb@U(gVizZ& z{g9<2(HSv}i@BC@#<7FbTjNxVw6&4f_AB=lcZZ_fP+}hgBeW^MywHw>KiJF1u(ND* z&2G+y-Id0z4WZ&q7ivQXAB5P8E!!DlcFJGedlB+3o&S1J?`Y@QHv0rnLL#Nk-W_^< z)zWXq@27teGkBHIa!p-5d^-J9<|bdXuII~NUSCh!I*nwi71S*HqLZK$vrgpAl9#2g zhXjeW{!iEPMCX9-<}SarzqBhmyG);GJe*he>i%kI(Zad9(L&YGJ=h$ibQb)*lA)Ox zXiN1jkslVryoREia0SsKml39xF_dR(CTHSzlQV%cMKR>Pl8vUK-vU5d^Sw?gnpk0w zNlW){78i5sn~_$EvM4HcYcFJw0XltIjq9-(x|PFatg0Yf_lI@RflViVu} z^v}S}!Uog4A1&1nBHs+%{&VWi1N)P0KWUZQo9stgGwu|)9;s8%d`;Fd>Df9M9qg5vix;BE$TT4S zfqP{DrbJsiiPX&>HPG@9RO;sHA2oIA6PCcUW>yg``Y-){4S2-CPXAKzWrs_DtdFV_>%?h+heF-#%=# zD>b2D&ooT)4>ujKXhSE;EA?eTR5nJ6Ef;S!HsHGkMuFC{Bcot}5>f}*CecWVh_sTH zh~jAOX2LlbIL!b#sB?u;^2l|fp86xLs5?dRVL{T z;(3j6aLHgb6@jq5qq?Q*3Ove-6?zQgnLuR6)1u9Tz<)hl)o14Sj@Bhka9hvehP&QO zcp+nHm(vWyM9iPCX@0Toa#XAD>fhv%vba!zMTjf0XIcNePDZA|&gRkY-xY5ZXZyuF z-!()}DNWbrgyt2UZ)Oh76ML8H3QF+nhNymTuo9zDl-5t&t3z@n%0E;@za7BOHZ4(x z7}aEpwJvCRPf}4Cs{NTS{MOQ%(R&81dJ$HS_cm_(95={S!5J zLM;mfcjT-{qU}J65@G%m_MP2N&nA)Agmm=@@Y5|nC;O3PUkSYVQ6*9W|7%}8eiMlC zX+XMevB2PVEC7-k(tqu?lglhYt9ZW>sx+Y+tb9^M8$=vJe%4Xw^yMD!U3NFRiw@ z_EC=1C4O=K5qtf!lsMb>B@U{!>W5Bo69@ivZC|c@o+UF10gw_E$E5QRJgw_0C=IP&s&|1ZN>I|l+CxAoU z8Rb%9pmUcY3FPb;4|MHk&1&JvX&q$_k+XDfx6(OghJN|tieiv%PFa~!uuW(dh>$N3xGsNiL!|P z16NFO@6DKa=UgH+-fsp~?@T|A_RUz4Exuxmt{JJdERhHbUHU+tS{kuB_p>2HzqIDE zWhUuQRYEQEzl7&Ghl)kRyPT_^L0X}BI9wdm3CpWTu6|%K#L&pE4_}OP6q>0K1VxsA zXCx3xxExCmjnuOQ4bb`>Lzn6I#Bgf<#P90(ws^=UhRKVz-olvKbd>2OJ)OeSeac7+QvzK4ibo4-#3w&tgKn|*=*%!Mra zf)D7ud5}aWeT!Sumk**AR|CY6oC3A$I}jcVeXemO8%%IPWk%1W<1^NCC}84xHov?- zQkW3>?VCodQG0(s;gH7yF4Zq8&)sqUuGaZXNC;&dTrz8Mp{TyE)?^M(kwWj~n2>n- z9@Y&1zE#<_l;RgAFunRLsf4=iJd9Oj>&s#&xX5fo5{4y#UN`rDGNngUk=2<{a zB#b|iPFyVJebzg|kz?`DD5*j|`4~0;e#(f))tq=B(d#v_Egz7tsZU&j+yQAHUsm@+rlm`WVr5 z!cwS|;MX!0+b*SxQJ-5Mpbh{W@9~;ou^EM21aP%Ee_H7Yu17aW`t6F8EerLRCU%v$ z(baD!UQ-yOO+dr4!|qh@XB;_eY7;DN+katsIFA#X!FHstu+s`O%Rq|;MZp%<<5C?1 zaysTpxpQe{&nNVtfBI3o<3fASc>!@7N6lOr6-;3Oyb) z`%GF_vxE3Ur>Ht~6E3KbL^r%)If;&c3;C7sb5+O5lp;-jR{c!U)x5kfLSbiFA?Fa= zxWBAc*Be}`D;6RtBDVU9!1k|v&*=E_gDO-j{`jiXrIzJYg~IlD-Jmu^ckoV*-13w0 z7|2rJWwhlxj<%N3RI7XATg%XF0?=|Y5Z8i#6D%7`+!d!mw?j9XyJ>hDSy8^M>NHZm z-?&8OgKiVrhX|m(1M~(75235IkwXRErd1`#pssgY#Kb~Ee>jTRvF4{ku^0=cAM}f1 zJ(AG07E*@OGjN|ImPK=O_Cti(+(?u^o;|Ur6t8^nbE*Dps)bW1+O7xCm-v)q7&#D@ zFy&GRJ-U}kdUJX73wDe5l+?)C+A=(;aS<^G$^!b-x9tcs@89fpWxj zaXv*0L^9G&NnO9KpV#ccS>{%TPnDD19Vpn!Hy>{Oxv`CNr}|GlPcir1Gkro^u-~ZR z)}>KUbo;J!%iGlQp7&a|e%c7OdgSly{K*hQifj1a?K-U1QG^8M#(#$+`5B9`33S|q z!;$2&{@y199PCA)C|za-Y0I=xpEgfFZvgaVIHsYR$UH9xZi9os!(e$P@`sUT_qoUc z7M&lp2f^DuIuAlXpR(`$(tJi&j_R(0Ff7#jZDhgC@P2!{oP`cJk15h|YVXeZt7J!A z6M;&w149fdUB3R(3Di=w#O71>q|68Fi#Tz3h41HwlgtWSoD(r&i?{vOo|zJyOa1Y2 z^$U-YHf`^3YsKnvCB2?-76hNsMeR|PA*Q|s90J8%d-=bfj~wk23azW0EBtc|#g^ma zrZg3K_nh}^eI_Qa>-+j^^a)mzN0{?Im{cc!cbRMex6T^B``egA8y(bt3(XyG@FtgE zjW+XL%Xp$mT(n)gB7jFQ${vGec2MU=jv$A;}r^4mVJ6~N&| z_R?eGdy`8?Osi9EO1V)i89@_Ls{d^A()MgdX%Az)^AKpdLF*{_RQcI6&c=?JA7|1f zpXz>Z?zoPMFSOQodF@TsmCOOdaXX5jyb2@T_|%(HQ$;v~WmOK^3DPTu=P^g`O~tBr zT1&-QAXFDBat(4R-#NG&KiH!T%D|xB8nmaH8(uwc4=Zu%6DBwB>gmro5nTHKzgr-G z*B_UNLYdVwsQi^Jqj5s4gCHa}*e)c)&t51SNM#Z6JQZG>z>2}4JSCJz@;Yt#6G0xQ zWeL)bq+38INj>k`ny3+|%up+$!uw4Jo$|fY6n4}B%MN$0<6+Z82|OHi+Hm~ys7>Ah z_(2=0x$mZv362VKp~<2-+kcJZ+9LlV{ubo$l%e-+l73UCw{9ywjwI2mpz8bYe3ySN z3Krz9Y2x~)67tjlG>k@|?X!vd9+d;oGpGtjQm*TCOG4|0jgZ24Kkwl%rk|<|^$aF~ zh86t09}T)lr$D@3P7(aUx4YutrQmEVGnZok$HvX~=!IKLeGQ|ixL{1Q&tAoLD>}y8 zS#vUIpT{hXUw!}|{Yofazo?v(zv^}YTg}fefm457O!JCB-``lqVrH=8a}U%rL6DN5 z=d)_SJlfHL0FTq$&**r)wrSdiT73E7@4yIrAEF#1ONzx1|IP2dg;k#pwc#`iQX=-} z-cNKxsh{QR_fRr^%v5t+S)w%T@q#ND&7-9iO@AnOn(>>0&BKvKJEvfic0XctydZ@& z=u;ram~+UY6rkkP#=_fb9&{5u82FNi)d`ZN=podT*;|cp%bp*D{Q1u%3#Wwq4UmZ7 zeAvnt#wL-!mK_zGW5kS5^KsxQ!^G3EVG@@h(rFy)cyZq3^olND z-Am+8gbaSYb^H#??5tp`$p(3HxhA9vnD0I$*R4Opc*$)6q zpyJAqH8g(%IBYiiXUQ=;F&cA}Qnbaf;e=rXkw`Fz{@O`b0r#BO!OjX$AL=S#s}iZa zhgftNj&sQzc^iD+sdT^#)A+HPt+;w;uQ*(j(0qhriRcXo{*jhV^qe!b_*1ZAZDxTa zi;B0CP9aB z8q*i`WdFQHOvNO6J9Xw|PjzVj{jiYTIFbK7BWq5QXy?;OLjRIu*g!!iWcsL(pH}%x z;@JHhnY)NC9N-v&OTX!$;t2J8%%Gc(gA3PD**zR?bW1nl`U+X*#B+4B)*P>Z* z-ZSxR351|<=-N{_t1KnH{+d$6TN&sFs2OZGgYrYT=T1k2qmV%d7{y6P{`c;J`mjP< z$`llK8~Mw@-}@@##_G$LkGeLeQANuX%_(OX3lCF3V$vCeAjt_ug!zIlGAQAi|M0pU z$?8^99p?FR;H(`3ptILZ)(5M`$7>`EChtuKktIA7WKRwKX_N$1Qj0;e;Rp3=vx+}APC~NugSx* zH2sj~I0vv?jirfCz6Hw zRDT~7>7N4dR?ESg@3WI;(pNH}bjVs(n5^%tMnMrCtFckN@tA290*Z-Nt`x2Mu_^m& zad6E2T8i>=)=n`h;aLoHzyF}c$T3o82FwgFUWopfbKfwz%PR+wj=QhM7EuZil}P+r zZj8&14y?=*y}lh^UZm5K))R@EgV5?Zq=36h)O@6

#%A{^>{=uP%_w0Wr_{UyX2x&I}?y?#1ZqkQb&X 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 KsFkT&1^*9Tsmj6t literal 0 HcmV?d00001 From 05055dbf27e7ab9d5dcd622b32432293434f5a42 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Mon, 1 Jan 2024 15:41:45 +0100 Subject: [PATCH 38/47] add attrs for publish --- S26-documentation.pod6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index 640b2972..61c255c2 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -1,4 +1,4 @@ -=begin pod +=begin pod :puburl('/spec') :puburl('/spec') :pubdate('2023-11-15 18:14:00') =comment This file is deliberately specified in Podlite format From 40c942e858c545a82588f4f114239b087d04ae8c Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 7 Jan 2024 18:16:23 +0100 Subject: [PATCH 39/47] add 256x256 logo --- assets/podlite_logo_256x256.png | Bin 0 -> 16840 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 assets/podlite_logo_256x256.png diff --git a/assets/podlite_logo_256x256.png b/assets/podlite_logo_256x256.png new file mode 100644 index 0000000000000000000000000000000000000000..4bad5c95e14757efdde346e8cc17c2e3dd17c782 GIT binary patch literal 16840 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 hjg)0 Date: Sun, 7 Jan 2024 18:36:39 +0100 Subject: [PATCH 40/47] fix tables, formatting, toc --- S26-documentation.pod6 | 142 ++++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 65 deletions(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index 61c255c2..4521374d 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -1,10 +1,23 @@ -=begin pod :puburl('/spec') :puburl('/spec') :pubdate('2023-11-15 18:14:00') +=begin pod :puburl('/specification') :pubdate('2023-11-15 18:14:00') =comment This file is deliberately specified in Podlite format =TITLE Podlite - a lightweight markup language +=begin nested +B + +It's not finished yet, but it's available for everyone to see +and comment on. This way, it can get better with everyone's input. + +If you have any ideas to make it better, or if you have any questions, +you're welcome to suggest changes or start a conversation on +our L. +=end nested + +=Toc head1, head2,head3 + =begin AUTHORS =item Damian Conway |mailto:damian@conway.org>> =item Aliaksandr Zahatski |mailto:zag@cpan.org>> @@ -528,7 +541,7 @@ between Pod block names and their corresponding Markdown elements. =end table The most common use of Selectors is to create L and -in L. +in L. =head2 Block types @@ -2198,12 +2211,12 @@ To include other formatting codes in a C> code, you can lexically L it: =begin code :allow - =begin para - B<=config C<> :allow> - Raku makes extensive use of the C>> and C>> - characters, for example, in a hash look-up: - C<%hashB>>keyB>>> - =end para + =begin para + B<=config C<> :allow> + Raku makes extensive use of the C>> and C>> + characters, for example, in a hash look-up: + C<%hashB>>keyB>>> + =end para =end code To enable entities in I C> put a C<=config C<> :allow> @@ -2223,12 +2236,11 @@ eventually be replaced by an actual value. For example: or: =begin code :allow - Then enter your details at the prompt: - - =for input - Name: B> - ID: B> - Pass: B> + Then enter your details at the prompt: + =for input + Name: B> + ID: B> + Pass: B> =end code Typically replaceables would be rendered in R or with @@ -2270,8 +2282,8 @@ B, which should not be rendered by any renderer. For example: =begin code :allow - The "exeunt" command B> is used - to quit all applications. + The "exeunt" command B> is used + to quit all applications. =end code In Perl 5 POD, the C> code was widely used to break up text that would @@ -2345,7 +2357,7 @@ A standard web URL. For example: =begin code :allow This module needs the LAME library - (available from L>) + (available from LZ<>>) =end code If the link does not start with C it is treated as being relative to @@ -2940,24 +2952,24 @@ C, C, etc.) The declared object then becomes the (read-only) return value of the alias. For example: =begin code :allow - B<=alias CLASSNAME> - class Database::Handle { - B<=alias ATTR> - has IO $!handle; - - B<=alias OPEN> - my Bool method open ($filename?) {...} - - B<=alias DEFNAME> - constant Str DEFAULT_FILENAME = 'db.log'; - - =for para - Note that the B> method of class B> - stores the resulting low-level database handle - in its private B> attribute. By default, - handles are opened to the file "B>". - - } + B<=alias CLASSNAME> + class Database::Handle { + B<=alias ATTR> + has IO $!handle; + + B<=alias OPEN> + my Bool method open ($filename?) {...} + + B<=alias DEFNAME> + constant Str DEFAULT_FILENAME = 'db.log'; + + =for para + Note that the B> method of class B> + stores the resulting low-level database handle + in its private B> attribute. By default, + handles are opened to the file "B>". + + } =end code This would produce: @@ -2988,7 +3000,7 @@ attribute. By default, handles are opened to the file "C". =begin table :nested Block typename Specifies - ______________ ___________________________________________________ + _______________ ____________________________________________________ C<=code> Verbatim pre-formatted sample source code C<=comment> Content to be ignored by all renderers C<=defn> Definition of a term @@ -3001,7 +3013,7 @@ attribute. By default, handles are opened to the file "C". C<=para> Ordinary paragraph C<=pod> No "ambient" blocks inside C<=table> Simple rectangular table - C<=data> Raku data section + C<=data> Data section C<=finish> No ambient blocks after this point C<=toc> Autogenerated table of contents C<=include> Include other blocks, documents @@ -3017,34 +3029,34 @@ attribute. By default, handles are opened to the file "C". =config C<> :allow =begin table :nested - Formatting code Specifies - _______________ ___________________________________________________ - C> Replaced by contents of specified macro/object - C> Basis/focus of sentence (typically rendered bold) - C> Code (typically rendered fixed-width) - C> Definition (C|R;R;...>>) - C> Entity names or numeric codepoints (C;R;...>>), emoji - C> Mathematical formula - C> reserved - C> Superscript - C> Important (typically rendered in italics) - C> Subscript - C> Keyboard input (typically rendered fixed-width) - C> Link (C|R>>) - C> Module-defined code (C:R>>) - C> Note (not rendered inline) - C> Strikethrough - C> Inline eqivalent for C<=picture> block - C> reserved - C<...>> Replaceable component or metasyntax - C> Space characters to be preserved - C> Terminal output (typically rendered fixed-width) - C> Unusual (typically rendered with underlining) - C<...>> Verbatim (internal formatting codes ignored) - C> Contextual backlinks - C> reserved - C> Index entry (C|R,R;...>>) - C> Zero-width comment (contents never rendered) + Formatting code Specifies + ___________________ ___________________________________________________ + C> Replaced by contents of specified macro/object + C> Basis/focus of sentence (typically rendered bold) + C> Code (typically rendered fixed-width) + C> Definition (C|R;R;...>>) + C> Entity names or numeric codepoints (C;R;...>>), emoji + C> Mathematical formula + C> reserved + C> Superscript + C> Important (typically rendered in italics) + C> Subscript + C> Keyboard input (typically rendered fixed-width) + C> Link (C|R>>) + C> Module-defined code (C:R>>) + C> Note (not rendered inline) + C> Strikethrough + C> Inline eqivalent for C<=picture> block + C> reserved + C<...>> Replaceable component or metasyntax + C> Space characters to be preserved + C> Terminal output (typically rendered fixed-width) + C> Unusual (typically rendered with underlining) + C<...>> Verbatim (internal formatting codes ignored) + C> Contextual backlinks + C> reserved + C> Index entry (C|R,R;...>>) + C> Zero-width comment (contents never rendered) =end table From 271e8f1a0eb5430a23bc0cae168e5209d6926351 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 7 Jan 2024 18:37:53 +0100 Subject: [PATCH 41/47] update README --- README.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 92071a12..fe9f3ac9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,17 @@ -Design Documents -======================= + +[![Podlite](https://github.com/zag/specs/raw/podlite-specification/assets/podlite_logo_256x256.png)](https://podlite.org) + + +**Podlite is a block-based markup language designed for flexibility and ease of use.** + +Unbound by any specific domain, programming language, or concept, Podlite stands out as a universal markup language. It's versatile enough to be successfully implemented across various development fields, from web development to scientific research. + +Podlite is not limited to any specific application domain, programming language, or concept. + +In addition, the support for Markdown markup as a standard block adds convenience and allows for the use of familiar syntax for text formatting. + +One of the key features of Podlite is its extensibility. This allows for defining unique and domain-specific blocks and expanding the language's functionality according to the requirements of your project. + +Its flexibility makes it an ideal tool for creating documentation, blogs, educational materials, and much more. + +Podlite aims to provide users with a means for creativity and expressing ideas in a structured form, while ensuring ease of use and high flexibility in content creation. From d41181bc6659968643bfb923534604a26eee115a Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 7 Jan 2024 20:05:11 +0100 Subject: [PATCH 42/47] fix markup --- S26-documentation.pod6 | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index 4521374d..2463592a 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -106,9 +106,8 @@ aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. The content of a document is specified within one or more D. Every Pod block may be declared in any of three forms: - -L|#Delimited blocks>, L|#Paragraph -blocks>, or L|#Abbreviated blocks>. +I>, I>, or I>. All of these forms are equivalent. Anything in a document that is neither a Pod directive nor contained From dd42303081fc8ffdebb333144823a75f0222396c Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 7 Jan 2024 20:07:11 +0100 Subject: [PATCH 43/47] update links --- S26-documentation.pod6 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index 2463592a..a41ef911 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -13,7 +13,7 @@ and comment on. This way, it can get better with everyone's input. If you have any ideas to make it better, or if you have any questions, you're welcome to suggest changes or start a conversation on -our L. +our L. =end nested =Toc head1, head2,head3 From 6393067b50f98e5df7e6d2a33ede3cde72a7ade4 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 21 Jan 2024 17:41:41 +0100 Subject: [PATCH 44/47] fix naming --- S26-documentation.pod6 | 154 ++++++++++++++++++++--------------------- 1 file changed, 74 insertions(+), 80 deletions(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index a41ef911..0f07e960 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -56,32 +56,27 @@ our L. =end CHANGES -=head1 -Pod +=head1 Podlite -D is an easy-to-use markup language with a simple, consistent -underlying document object model. Pod can be used for writing language +D is an easy-to-use markup language with a simple, consistent +underlying document object model. Podlite can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition. -Pod is an evolution of Perl 5's L|doc:perlpod> -(POD) markup. Compared to POD, Raku Pod is much more -uniform, somewhat more compact, and considerably more expressive. The -Pod dialect also differs in that it is a purely descriptive mark-up -notation, with no presentational components. +The Podlite is a purely descriptive mark-up notation, with no presentational +components. =head2 General syntactic structure -Pod documents are specified using D, which are +Podlite documents are specified using D, which are used to declare configuration information and to delimit blocks of -textual content. All Pod directives are considered to be special types -of comments in Raku. +textual content. Every directive starts either with an equals sign (C<=>) followed immediately by an identifier. -An identifier composed of an alphabetical character followed by +An D composed of an alphabetical character followed by any combination of alphanumeric characters. Alphabetic and numeric definitions encompass relevant Unicode characters. The underscore is consistently treated as alphabetic. Additionally, an identifier @@ -92,38 +87,34 @@ Directives that start with C<=> can be indented like the code they interleave, but their initial C<=> must still be the first non-whitespace character on their line. -An indented Pod block is considered to have a I, +An indented Podlite block is considered to have a I, determined by the indentation of its opening delimiter. In other words, if a directive is indented from the left margin, the column at which the first character of its opening delimiter appears is thereafter considered the first column of the entire block's contents. -As with Raku heredocs, the virtual margin treats leading tabs as -aligning to tabstops spaced every C<($?TABSTOP // 8)> characters. +The virtual margin treats leading tabs as aligning to tabstops spaced +every C<($?TABSTOP // 8)> characters. -=head2 Pod blocks +=head2 Podlite blocks The content of a document is specified within one or more D. -Every Pod block may be declared in any of three forms: +Every Podlite block may be declared in any of three forms: I>, I>, or I>. All of these forms are equivalent. -Anything in a document that is neither a Pod directive nor contained -within a Pod block is treated as "ambient" material. Typically this -would be the source code of the program that the Pod is documenting. Pod -parsers still parse this text into the internal representation of the -file, representing it as a C block. Renderers +Anything in a document that is neither a Podlite directive nor contained +within a Podlite block is treated as "ambient" material. Typically this +would be the source code of the program that the Podlite is documenting. +Podlite parsers still parse this text into the internal representation of the +file, representing it as a "ambient" block. Renderers will I ignore such blocks, but see L<#Aliases>. -In Perl 5's POD format, once a POD directive is encountered, the parser -considers everything that follows to be POD, until an explicit C<=cut> -directive is encountered, at which point the parser flips back to -parsing ambient source code. The Raku Pod format is different. All Pod -directives have a defined terminator and the Pod parser always reverts to -"ambient" at the end of each Pod directive or block. To cause the parser -to remain in Pod mode, you must enclose the desired Pod region in a +All directives have a defined terminator and the Podlite parser always reverts to +"ambient" at the end of each Podlite directive or block. To cause the parser +to remain in "Pod" mode, you must enclose the desired Podlite region in a C block: =begin code :allow @@ -131,17 +122,21 @@ C block: =head1 A heading - This is Pod too. Specifically, this is a simple C block + This is Podlite too. Specifically, this is a simple C block $this = pod('also'); # Specifically, a code block B<=end pod> =end code +For files with the extensions '.pod6' and '.podlite', their contents +are implicitly wrapped in a C directive. Thus, the parser operates +in "Pod" mode until the end of the file. + =head3 Delimited blocks Delimited blocks are bounded by C<=begin> and C<=end> markers, both of -which are followed by a valid Raku identifier, which is the +which are followed by a valid Podlite identifier, which is the D of the block. Typenames that are entirely lowercase (for example: C<=begin head1>) or entirely uppercase (for example: C<=begin SYNOPSIS>) are reserved. @@ -149,7 +144,7 @@ SYNOPSIS>) are reserved. After the typename, the rest of the C<=begin> marker line is treated as configuration information for the block. This information is used in different ways by different types of blocks, but is always specified using -Raku-ish option pairs. That is, any of: +any of: =for table :nested Value is... Specify with... Or with... Or with... @@ -160,10 +155,9 @@ Raku-ish option pairs. That is, any of: List C«:key<1 2 3>» C«:key[1,2,3]» C«key => [1,2,3]» Hash C«:key{a=>1, b=>2}» C«key => {a=>1, b=>2}» -All option keys and values must, of course, be constants since Pod is a +All option keys and values must, of course, be constants since Podlite is a specification language, not a programming language. Specifically, option -values cannot be closures. See Synopsis 2 for details of the various -Raku pair notations. +values cannot be closures. The configuration section may be extended over subsequent lines by starting those lines with an C<=> in the first (virtual) column followed @@ -173,7 +167,7 @@ The lines following the opening delimiter and configuration are the data or contents of the block, which continue until the block's matching C<=end> marker line. For most block types, these contents may be indented if you wish, without them being treated as L. Unlike Perl 5, indented text is only treated as code within +blocks>. Indented text is only treated as code within C<=pod>, L|#Nesting blocks>, L|#Lists>, C<=code>, and L blocks. @@ -211,11 +205,11 @@ For example: Note that no blank lines are required around the directives; blank lines within the contents are always treated as part of the contents. -This is a universal feature of Pod. +This is a universal feature of Podlite. Note also that in the following specifications, a "blank line" is a line that is either empty or that contains only whitespace characters. That -is, a blank line matches the Raku pattern: C. Pod uses +is, a blank line matches the Raku pattern: C. Podlite uses blank lines as delimiters, rather than empty lines, to minimize unpleasant surprises when stray spaces or tabs mysteriously turn up in hitherto empty lines. @@ -224,7 +218,7 @@ empty lines. =head3 Paragraph blocks Paragraph blocks are introduced by a C<=for> marker and terminated by -the next Pod directive or the first blank line (which is I +the next Podlite directive or the first blank line (which is I considered to be part of the block's contents). The C<=for> marker is followed by the name of the block and optional configuration information. The general syntax is: @@ -259,7 +253,7 @@ For example: Abbreviated blocks are introduced by an C<'='> sign in the first column, which is followed immediately by the typename of the block. The rest of the line is treated as block data, rather than as -configuration. The content terminates at the next Pod directive or the +configuration. The content terminates at the next Podlite directive or the first blank line (which is not part of the block data). The general syntax is: @@ -318,7 +312,7 @@ or: =head3 Standard configuration options -Pod predefines a small number of standard configuration options that can be +Podlite predefines a small number of standard configuration options that can be applied uniformly to any built-in block type. These include: =begin defn @@ -511,13 +505,13 @@ For example: =end table Please note that while the Selector blocks provide a way to query and filter specific elements -within Markdown files, Markdown itself doesn't have formal named blocks like the Pod syntax. +within Markdown files, Markdown itself doesn't have formal named blocks like the Podlite syntax. Instead, Markdown uses a lightweight markup to structure content. The above table provides a mapping -between Pod block names and their corresponding Markdown elements. +between Podlite block names and their corresponding Markdown elements. -=begin table :nested :caption("A table of correspondences for some Pod blocks and markdown blocks") +=begin table :nested :caption("A table of correspondences for some Podlite blocks and markdown blocks") - Pod Markdown Describtion + Podlite Markdown Describtion _______________________________________ ______________ _____________________________________ head1, head2, ... #, ##, ... Heading level 1,2... @@ -544,11 +538,11 @@ in L. =head2 Block types -Pod offers notations for specifying a wide range of standard block types... +Podlite offers notations for specifying a wide range of standard block types... =head3 Headings -Pod provides an unlimited number of levels of heading, specified by the +Podlite provides an unlimited number of levels of heading, specified by the C<=head>R block marker. For example: =begin code @@ -561,8 +555,8 @@ C<=head>R block marker. For example: =head86 A "Missed it by I much!" heading =end code -While Pod parsers are required to recognize and distinguish all levels -of heading, Pod renderers are only required to provide distinct +While Podlite parsers are required to recognize and distinguish all levels +of heading, Podlite renderers are only required to provide distinct I of the first four levels of heading (though they may, of course, provide more than that). Headings at levels without distinct renderings would typically be rendered like the lowest distinctly @@ -830,7 +824,7 @@ For example: =head3 I/O blocks -Pod also provides blocks for specifying the input and output of programs. +Podlite also provides blocks for specifying the input and output of programs. The C<=input> block is used to specify pre-formatted keyboard input, which should be rendered without rejustification or squeezing of whitespace. @@ -850,7 +844,7 @@ Unlike C<=code> blocks, both C<=input> and C<=output> blocks honour any nested formatting codes. This is particularly useful since a sample of input will often include prompts (which are, of course, output). Likewise a sample of output may contain the occasional interactive -component. Pod provides L +component. Podlite provides L (C> and C>) to indicate embedded input or output, so you can use the block type that indicates the overall purpose of the sample (i.e. is it demonstrating an input operation or an output sequence?) and then use @@ -878,7 +872,7 @@ you could use the C> formatting code: =head3 Lists -Lists in Pod are specified as a series of contiguous C<=item> blocks. No +Lists in Podlite are specified as a series of contiguous C<=item> blocks. No special "container" directives or other delimiters are required to enclose the entire list. For example: @@ -944,7 +938,7 @@ E Gas =for para :nested(2) E Chocolate -Pod parsers must issue a warning if a "level-R" C<=item> block +Podlite parsers must issue a warning if a "level-R" C<=item> block (e.g. an C<=item2>, C<=item3>, etc.) appears anywhere except where there is a preceding "level-R" C<=item> in the same surrounding block. That is, an C<=item3> should only be specified if an C<=item2> appears @@ -1064,7 +1058,7 @@ or explicitly mark the item itself as being unnumbered: The numbering of successive C<=item1> list items increments automatically, but is reset to 1 whenever any other kind of non-ambient -Pod block appears between two C<=item1> blocks. For example: +Podlite block appears between two C<=item1> blocks. For example: =begin code The options are: @@ -1130,7 +1124,7 @@ which produces: =head4 Task lists -In addition to the ordered list Pod also supports +In addition to the ordered list Podlite also supports task lists, which are commonly known as checklists or to-do lists. To create a task list item just apply a C<:checked> @@ -1309,7 +1303,7 @@ nesting are required: =end para =end code -So Pod provides a C<=nested> block that marks all its contents as being +So Podlite provides a C<=nested> block that marks all its contents as being nested: =begin code :allow @@ -1340,7 +1334,7 @@ The preceding example could equally have been specified: =head3 Tables -Simple tables can be specified in Pod using a C<=table> block. +Simple tables can be specified in Podlite using a C<=table> block. The table may be given an associated description or title using the C<:caption> option. @@ -1606,12 +1600,12 @@ Note that all block names consisting entirely of lowercase or entirely of uppercase letters are reserved. See L<#Semantic blocks>. -=head3 Pod comments +=head3 Podlite comments -D refers to Pod blocks that should not +D refers to Podlite blocks that should not be displayed by any renderer. However, they are still may be part of the -internal Pod representation. However, they can still be part of internal -Pod representation. +internal Podlite representation. However, they can still be part of internal +Podlite representation. Comments are useful for meta-documentation (documenting the documentation): @@ -1905,7 +1899,7 @@ should be able to provide a warning in such situations. =head3 Inserting pictures -Pod allows to include images using a C<=picture> block with an inline version +Podlite allows to include images using a C<=picture> block with an inline version represented as C>: =begin code :allow @@ -1989,8 +1983,8 @@ It possible to define the formule caption using the C<:caption> attribute. =head3 Markdown support -Pod includes built-in support for Markdown, making it easy to include Markdown -content within Pod documents. This is achieved using the C<=markdown> block. +Podlite includes built-in support for Markdown, making it easy to include Markdown +content within Podlite documents. This is achieved using the C<=markdown> block. =begin code :allow =begin markdown @@ -2032,7 +2026,7 @@ the flexibility of Markdown. =head2 Formatting codes Formatting codes provide a way to add inline mark-up to a piece of text -within the contents of (most types of) Pod block. Formatting codes are +within the contents of (most types of) Podlite block. Formatting codes are themselves a type of block, and may nest other formatting codes. other type of block (most often, other formatting codes). In particular, you can nest comment blocks in the middle of a formatting code: @@ -2043,7 +2037,7 @@ you can nest comment blocks in the middle of a formatting code: and with emphasis.> =end code -All Pod formatting codes consist of a single capital letter followed +All Podlite formatting codes consist of a single capital letter followed immediately by a set of angle brackets. The brackets contain the text or data to which the formatting code applies. You can use a set of single angles (C«<...>»), a set of double angles (C<«...»>), or multiple @@ -2083,7 +2077,7 @@ or delimiters with more consecutive angles than your text contains: A formatting code ends at the matching closing angle bracket(s), or at the end of the enclosing block or formatting code in which the opening angle bracket was specified, whichever comes first (this includes paragraph -and abbreviated blocks, ending with blank a line). Pod parsers are +and abbreviated blocks, ending with blank a line). Podlite parsers are required to issue a warning whenever a formatting code is terminated by the end of an outer block rather than by its own delimiter (unless the user explicitly disables the warning). @@ -2091,7 +2085,7 @@ user explicitly disables the warning). =head3 Significance indicators -Pod provides three formatting codes that flag their contents with +Podlite provides three formatting codes that flag their contents with increasing levels of significance: =item @@ -2121,7 +2115,7 @@ mistake and should not be included in the document. =head3 Text positioning -Pod provides two formatting codes that allow positioning characters or words. +Podlite provides two formatting codes that allow positioning characters or words. =begin item To create subscript text, you can use the C> formatting code, where 'J' represents @@ -2174,7 +2168,7 @@ term (or any of its specified synonyms) within a hypertext. =head3 Example specifiers -Pod provides formatting codes for specifying inline examples of input, +Podlite provides formatting codes for specifying inline examples of input, output, code, and metasyntax: =begin item @@ -2314,7 +2308,7 @@ L block|#Comments>. =head4 Comments as category markers -Most Pod renderers will provide a mechanism that allows particular Pod +Most Podlite renderers will provide a mechanism that allows particular Pod blocks to be explicitly excluded or included if they match a particular pattern. For example, a renderer might be instructed to omit any block that contains the pattern C. Corresponding "invisibility @@ -2344,7 +2338,7 @@ any link specification. Usually, in schemes where an internal address makes sense, it will be separated from the preceding external address by a C<#>, unless the particular addressing scheme requires some other syntax. When new -addressing schemes are created specifically for Pod it is strongly +addressing schemes are created specifically for Podlite it is strongly recommended that C<#> be used to mark the start of internal addresses. Standard schemes include: @@ -2521,7 +2515,7 @@ For example: =head3 Contextual backlinks -Pod introduces the concept of contextual backward links C> (or contextual backlinks), +Podlite introduces the concept of contextual backward links C> (or contextual backlinks), enhancing the traditional L mechanism by allowing to not only reference another location but also provide specific context around that reference. This context can take the form of opinions, @@ -2596,7 +2590,7 @@ The emergency signal is: dot dot dot dash dash dash dot dot dot. =head3 Entities To include Unicode code points or HTML5 character references in a -Pod document, specify the required D using the C> code. +Podlite document, specify the required D using the C> code. If the C> contains a number, that number is treated as the decimal Unicode value for the desired code point. For example: @@ -2813,16 +2807,16 @@ subsequent instances of the code. =head2 Aliases The C<=alias> directive provides a way to define lexically scoped -synonyms for longer Pod sequences, (meta)object declarators from the +synonyms for longer Podlite sequences, (meta)object declarators from the code, or even entire chunks of ambient source. These synonyms can then -be inserted into subsequent Pod using the +be inserted into subsequent Podlite using the L formatting code>|#Alias placements>. -Note that C<=alias> is a fundamental Pod directive, like C<=begin> or +Note that C<=alias> is a fundamental Podlite directive, like C<=begin> or C<=for>; there are no equivalent paragraph or delimited forms. There are two forms of C<=alias> directive: macro aliases and contextual -aliases. Both forms are lexically scoped to the surrounding Pod block. +aliases. Both forms are lexically scoped to the surrounding Podlite block. =head3 Macro aliases @@ -2990,7 +2984,7 @@ attribute. By default, handles are opened to the file "C". C<=config> Lexical modifications to a block or formatting code C<=end> Explicit termination of a C<=begin> block C<=for> Start of an implicitly (blank-line) terminated block - C<=alias> Define a Pod macro + C<=alias> Define a Podlite macro =end table From be8f4058109d56afe5f693cd010489f25db0aea3 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 21 Jan 2024 17:41:55 +0100 Subject: [PATCH 45/47] align --- README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.md b/README.md index fe9f3ac9..076dcaec 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ +
+ [![Podlite](https://github.com/zag/specs/raw/podlite-specification/assets/podlite_logo_256x256.png)](https://podlite.org) +
**Podlite is a block-based markup language designed for flexibility and ease of use.** From 33ae31b8a9b07ef66fe05c349b07f2413e80c1a7 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 28 Jan 2024 10:36:14 +0100 Subject: [PATCH 46/47] introduce parser modes --- S26-documentation.pod6 | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index 0f07e960..d4baea57 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -113,9 +113,9 @@ file, representing it as a "ambient" block. Renderers will I ignore such blocks, but see L<#Aliases>. All directives have a defined terminator and the Podlite parser always reverts to -"ambient" at the end of each Podlite directive or block. To cause the parser -to remain in "Pod" mode, you must enclose the desired Podlite region in a -C block: +D<"ambient"|Ambient mode; parser modes> at the end of each Podlite directive or +block. To cause the parser to remain in "Pod" mode, you must enclose the desired +Podlite region in a C block: =begin code :allow B<=begin pod> @@ -129,9 +129,14 @@ C block: B<=end pod> =end code -For files with the extensions '.pod6' and '.podlite', their contents -are implicitly wrapped in a C directive. Thus, the parser operates -in "Pod" mode until the end of the file. +The contents of files with the extensions '.pod6' and '.podlite' are +implicitly wrapped in a C<=pod> directive. This puts the parser in +D<"Pod" mode|Pod mode; parser modes> for the entire file, treating + all text as Podlite even if it's not inside an explicit block. + +For '.md' and '.markdown' files, the parser operates in D<"Markdown" +mode|Markdown mode; parser modes> for the entire file, treating all +text as markdown even if it is not inside an C<=markdown> block. =head3 Delimited blocks @@ -2481,7 +2486,7 @@ The scheme name may also be omitted in that case: This mechanism is described under L> below. =end code -Pod include the possibility of assigning a unique identifier to a block. +Podlite include the possibility of assigning a unique identifier to a block. These identifiers can be explicitly assigned to any blocks using the C<:id> attribute. Later, these identifiers are utilized for adressing blocks and creating links. From 45485938c2f4a22670aadf2bb870498c5d418ef3 Mon Sep 17 00:00:00 2001 From: Aliaksandr Zahatski Date: Sun, 4 Feb 2024 11:39:18 +0100 Subject: [PATCH 47/47] fix versioning, naming, correct examples, marked sections under development --- S26-documentation.pod6 | 73 +++++++++++++++++++++--------------------- 1 file changed, 37 insertions(+), 36 deletions(-) diff --git a/S26-documentation.pod6 b/S26-documentation.pod6 index d4baea57..8d99d2e1 100644 --- a/S26-documentation.pod6 +++ b/S26-documentation.pod6 @@ -23,11 +23,11 @@ our L. =item Aliaksandr Zahatski |mailto:zag@cpan.org>> =end AUTHORS -=VERSION pre-1.0.0 +=VERSION 1.0.0-beta1 =begin CHANGES -=head2 pre-1.0.0 +=head2 1.0.0-beta1 =head3 New: =item add C<:id>, C<:caption>, C<:lang> attributes, =item task lists, C<=item> and C<:checked> attribute, @@ -214,7 +214,7 @@ This is a universal feature of Podlite. Note also that in the following specifications, a "blank line" is a line that is either empty or that contains only whitespace characters. That -is, a blank line matches the Raku pattern: C. Podlite uses +is, a blank line matches the following pattern: C. Podlite uses blank lines as delimiters, rather than empty lines, to minimize unpleasant surprises when stray spaces or tabs mysteriously turn up in hitherto empty lines. @@ -1650,9 +1650,13 @@ an C<=finish> block is in all other respects identical to a C<=pod> block. =head3 Data blocks -Named Pod blocks whose typename is C are the Raku equivalent of +This section is not yet implemented + +=begin comment + +Named Podlite blocks whose typename is C are the Podlite equivalent of the Perl 5 C<__DATA__> section. The difference is that C<=data> blocks are -just regular Pod blocks and may appear anywhere within a source file, and as +just regular Podlite blocks and may appear anywhere within a source file, and as many times as required. There is a corresponding variable, C<$=data>, from which each C<=data> block @@ -1691,24 +1695,21 @@ they appear in the file. For example: =end code -Note that, as the preceding example illustrates, because Pod is a -compile-time phenomenon, it is possible to specify C<=data> blocks -I the point in the source where their contents will be used -(provided they're not being used in a C, of course). +Note that in Podlite, it is possible to specify C<=data> blocks +I the point in the source where their contents will be used. When C<$=data> itself is stringified, it returns the concatenation of all the unkeyed C<=data> blocks the parser has seen. -C<=data> blocks are never rendered by the standard Pod renderers. +C<=data> blocks are never rendered by the standard Podlite renderers. +=end comment =head3 Semantic blocks All uppercase block typenames are reserved for specifying standard documentation, publishing, source components, or meta-information of a -compunit it needs to be able to be selected for loading. In particular, all the -standard components found in Raku and manpage documentation have -reserved uppercase typenames. +compunit it needs to be able to be selected for loading. Standard semantic blocks include: @@ -2600,36 +2601,35 @@ Podlite document, specify the required D using the C> code. If the C> contains a number, that number is treated as the decimal Unicode value for the desired code point. For example: - Raku makes considerable use of E<171> and E<187>. + Podlite makes considerable use of E<171> and E<187>. -You can also use explicit binary, octal, decimal, or hexadecimal numbers -(using the Raku notations for explicitly based numbers): +You can also use explicit binary, octal, decimal, or hexadecimal numbers: - Raku makes considerable use of E<0b10101011> and E<0b10111011>. - Raku makes considerable use of E<0o253> and E<0o273>. - Raku makes considerable use of E<0d171> and E<0d187>. - Raku makes considerable use of E<0xAB> and E<0xBB>. + Podlite makes considerable use of E<0b10101011> and E<0b10111011>. + Podlite makes considerable use of E<0o253> and E<0o273>. + Podlite makes considerable use of E<0d171> and E<0d187>. + Podlite makes considerable use of E<0xAB> and E<0xBB>. If the C> contains anything that is not a number, the contents are interpreted as a Unicode character name (which is always uppercase), or else as an HTML5 named character reference. For example: - Raku makes considerable use of E + Podlite makes considerable use of E and E. or, equivalently: - Raku makes considerable use of E and E. + Podlite makes considerable use of E and E. To include emoji codes, you can use the C> code along with the colon-prefixed and postfix emoji shortname: - Pod uses emoji codes to express emotions and actions, + Podlite uses emoji codes to express emotions and actions, such as E<:thumbsup:> for approval and E<:smile:> for happiness. In this example, C<:smile:> and C<:thumbsup:> are emoji codes representing the respective emojis. You can use any valid emoji code in this format -to include emojis in your Pod document. +to include emojis in your Podlite document. Note that the specific emoji codes and the emojis they represent may vary depending on the platform or system you are using. @@ -2637,7 +2637,7 @@ depending on the platform or system you are using. Multiple consecutive entities (in any format) can be specified in a single C> code, separated by semicolons: - Raku makes considerable use of E. + Podlite makes considerable use of E. =head3 Indexing terms @@ -2697,9 +2697,8 @@ Anything enclosed in an C> code is an inline B. For example: =begin code :allow - Use a C loop instead.B loop is far more - powerful than its Perl 5 predecessor.>> Preferably with an explicit - iterator variable. + Space stations feature hydroponic gardens B>, a necessity for long-term missions. =end code Renderers may render such annotations in a variety of ways: as @@ -2708,23 +2707,24 @@ expandable tags, etc. They are never, however, rendered as unmarked inline text. So the previous example might be rendered as: =nested -Use a C loop instead.E Preferably with an explicit iterator -variable. - +Space stations feature hydroponic gardens E, a necessity for +long-term missions. and later: =begin nested B =para -E The Raku C loop is far more powerful than its Perl 5 -predecessor. +E Plants grow without soil, using mineral nutrient solutions. =end nested =head3 Module-defined formatting codes -Modules loaded with a L|#How Pod is parsed and processed> +This section is not yet implemented + +=begin comment +Modules loaded with a L|#How Podlite is parsed and processed> can define classes that implement new formatting codes, which can then be specified using the C> code. An C> code must start with a colon-terminated scheme specifier. The rest of the enclosed text is @@ -2754,6 +2754,7 @@ unformatted) contents. If the formatting code is unrecognized, the contents of the code (i.e. everything after the first colon) would normally be rendered as ordinary text. +=end comment =head2 Block pre-configuration @@ -2830,7 +2831,7 @@ identifier (which is usually specified in uppercase, though this is certainly not mandatory). The second argument consists of one or more lines of replacement text. -This creates a lexically scoped Raku macro that can be invoked during +This creates a lexically scoped Podlite macro that can be invoked during document generation by placing the identifier (i.e. the first argument of the alias) in an C> formatting code. This formatting code is then replaced by the text returned by new macro. @@ -2895,7 +2896,7 @@ and some portion of the following code is used as the value returned by the alias macro. Note that the code block following the C<=alias> line is still treated -as real code by the Raku parser, but its contents are I used to +as real code by the Podlite parser, but its contents are I used to create the replacement macro of the alias. This allows the developer to reproduce chunks of actual source code directly in the documentation, without having to copy it.