├── LICENSE ├── README.md ├── S01-overview.pod ├── S02-bits.pod ├── S03-operators.pod ├── S04-control.pod ├── S05-regex.pod ├── S06-routines.pod ├── S07-lists.pod ├── S08-capture.pod ├── S09-data.pod ├── S10-packages.pod ├── S11-modules.pod ├── S12-objects.pod ├── S13-overloading.pod ├── S14-roles-and-parametric-types.pod ├── S15-unicode.pod ├── S16-io-OLD.pod ├── S16-io.pod ├── S17-concurrency.pod ├── S19-commandline.pod ├── S21-calling-foreign-code.pod ├── S22-package-format.pod ├── S24-testing.pod ├── S26-documentation.pod ├── S27-perl-culture-draft.pod6 ├── S28-special-names.pod ├── S29-functions.pod ├── S31-pragmatic-modules.pod ├── S32-setting-library ├── Basics.pod ├── Callable.pod ├── Containers.pod ├── Exception.pod ├── IO-OLD.pod ├── IO.pod ├── Numeric.pod ├── Rules.pod ├── Str.pod └── Temporal.pod ├── S99-glossary.pod ├── html ├── hilite-full.png ├── hilite-small.png ├── index.html ├── perl-with-historical-message.css ├── perl.css └── style.css ├── pod6-files └── v6d.pod /LICENSE: -------------------------------------------------------------------------------- 1 | The Artistic License 2.0 2 | 3 | Copyright (c) 2000-2015, The Perl Foundation. 4 | 5 | Everyone is permitted to copy and distribute verbatim copies 6 | of this license document, but changing it is not allowed. 7 | 8 | Preamble 9 | 10 | This license establishes the terms under which a given free software 11 | Package may be copied, modified, distributed, and/or redistributed. 12 | The intent is that the Copyright Holder maintains some artistic 13 | control over the development of that Package while still keeping the 14 | Package available as open source and free software. 15 | 16 | You are always permitted to make arrangements wholly outside of this 17 | license directly with the Copyright Holder of a given Package. If the 18 | terms of this license do not permit the full use that you propose to 19 | make of the Package, you should contact the Copyright Holder and seek 20 | a different licensing arrangement. 21 | 22 | Definitions 23 | 24 | "Copyright Holder" means the individual(s) or organization(s) 25 | named in the copyright notice for the entire Package. 26 | 27 | "Contributor" means any party that has contributed code or other 28 | material to the Package, in accordance with the Copyright Holder's 29 | procedures. 30 | 31 | "You" and "your" means any person who would like to copy, 32 | distribute, or modify the Package. 33 | 34 | "Package" means the collection of files distributed by the 35 | Copyright Holder, and derivatives of that collection and/or of 36 | those files. A given Package may consist of either the Standard 37 | Version, or a Modified Version. 38 | 39 | "Distribute" means providing a copy of the Package or making it 40 | accessible to anyone else, or in the case of a company or 41 | organization, to others outside of your company or organization. 42 | 43 | "Distributor Fee" means any fee that you charge for Distributing 44 | this Package or providing support for this Package to another 45 | party. It does not mean licensing fees. 46 | 47 | "Standard Version" refers to the Package if it has not been 48 | modified, or has been modified only in ways explicitly requested 49 | by the Copyright Holder. 50 | 51 | "Modified Version" means the Package, if it has been changed, and 52 | such changes were not explicitly requested by the Copyright 53 | Holder. 54 | 55 | "Original License" means this Artistic License as Distributed with 56 | the Standard Version of the Package, in its current version or as 57 | it may be modified by The Perl Foundation in the future. 58 | 59 | "Source" form means the source code, documentation source, and 60 | configuration files for the Package. 61 | 62 | "Compiled" form means the compiled bytecode, object code, binary, 63 | or any other form resulting from mechanical transformation or 64 | translation of the Source form. 65 | 66 | 67 | Permission for Use and Modification Without Distribution 68 | 69 | (1) You are permitted to use the Standard Version and create and use 70 | Modified Versions for any purpose without restriction, provided that 71 | you do not Distribute the Modified Version. 72 | 73 | 74 | Permissions for Redistribution of the Standard Version 75 | 76 | (2) You may Distribute verbatim copies of the Source form of the 77 | Standard Version of this Package in any medium without restriction, 78 | either gratis or for a Distributor Fee, provided that you duplicate 79 | all of the original copyright notices and associated disclaimers. At 80 | your discretion, such verbatim copies may or may not include a 81 | Compiled form of the Package. 82 | 83 | (3) You may apply any bug fixes, portability changes, and other 84 | modifications made available from the Copyright Holder. The resulting 85 | Package will still be considered the Standard Version, and as such 86 | will be subject to the Original License. 87 | 88 | 89 | Distribution of Modified Versions of the Package as Source 90 | 91 | (4) You may Distribute your Modified Version as Source (either gratis 92 | or for a Distributor Fee, and with or without a Compiled form of the 93 | Modified Version) provided that you clearly document how it differs 94 | from the Standard Version, including, but not limited to, documenting 95 | any non-standard features, executables, or modules, and provided that 96 | you do at least ONE of the following: 97 | 98 | (a) make the Modified Version available to the Copyright Holder 99 | of the Standard Version, under the Original License, so that the 100 | Copyright Holder may include your modifications in the Standard 101 | Version. 102 | 103 | (b) ensure that installation of your Modified Version does not 104 | prevent the user installing or running the Standard Version. In 105 | addition, the Modified Version must bear a name that is different 106 | from the name of the Standard Version. 107 | 108 | (c) allow anyone who receives a copy of the Modified Version to 109 | make the Source form of the Modified Version available to others 110 | under 111 | 112 | (i) the Original License or 113 | 114 | (ii) a license that permits the licensee to freely copy, 115 | modify and redistribute the Modified Version using the same 116 | licensing terms that apply to the copy that the licensee 117 | received, and requires that the Source form of the Modified 118 | Version, and of any works derived from it, be made freely 119 | available in that license fees are prohibited but Distributor 120 | Fees are allowed. 121 | 122 | 123 | Distribution of Compiled Forms of the Standard Version 124 | or Modified Versions without the Source 125 | 126 | (5) You may Distribute Compiled forms of the Standard Version without 127 | the Source, provided that you include complete instructions on how to 128 | get the Source of the Standard Version. Such instructions must be 129 | valid at the time of your distribution. If these instructions, at any 130 | time while you are carrying out such distribution, become invalid, you 131 | must provide new instructions on demand or cease further distribution. 132 | If you provide valid instructions or cease distribution within thirty 133 | days after you become aware that the instructions are invalid, then 134 | you do not forfeit any of your rights under this license. 135 | 136 | (6) You may Distribute a Modified Version in Compiled form without 137 | the Source, provided that you comply with Section 4 with respect to 138 | the Source of the Modified Version. 139 | 140 | 141 | Aggregating or Linking the Package 142 | 143 | (7) You may aggregate the Package (either the Standard Version or 144 | Modified Version) with other packages and Distribute the resulting 145 | aggregation provided that you do not charge a licensing fee for the 146 | Package. Distributor Fees are permitted, and licensing fees for other 147 | components in the aggregation are permitted. The terms of this license 148 | apply to the use and Distribution of the Standard or Modified Versions 149 | as included in the aggregation. 150 | 151 | (8) You are permitted to link Modified and Standard Versions with 152 | other works, to embed the Package in a larger work of your own, or to 153 | build stand-alone binary or bytecode versions of applications that 154 | include the Package, and Distribute the result without restriction, 155 | provided the result does not expose a direct interface to the Package. 156 | 157 | 158 | Items That are Not Considered Part of a Modified Version 159 | 160 | (9) Works (including, but not limited to, modules and scripts) that 161 | merely extend or make use of the Package, do not, by themselves, cause 162 | the Package to be a Modified Version. In addition, such works are not 163 | considered parts of the Package itself, and are not subject to the 164 | terms of this license. 165 | 166 | 167 | General Provisions 168 | 169 | (10) Any use, modification, and distribution of the Standard or 170 | Modified Versions is governed by this Artistic License. By using, 171 | modifying or distributing the Package, you accept this license. Do not 172 | use, modify, or distribute the Package, if you do not accept this 173 | license. 174 | 175 | (11) If your Modified Version has been derived from a Modified 176 | Version made by someone other than you, you are nevertheless required 177 | to ensure that your Modified Version complies with the requirements of 178 | this license. 179 | 180 | (12) This license does not grant you the right to use any trademark, 181 | service mark, tradename, or logo of the Copyright Holder. 182 | 183 | (13) This license includes the non-exclusive, worldwide, 184 | free-of-charge patent license to make, have made, use, offer to sell, 185 | sell, import and otherwise transfer the Package with respect to any 186 | patent claims licensable by the Copyright Holder that are necessarily 187 | infringed by the Package. If you institute patent litigation 188 | (including a cross-claim or counterclaim) against any party alleging 189 | that the Package constitutes direct or contributory patent 190 | infringement, then this Artistic License to you shall terminate on the 191 | date that such litigation is filed. 192 | 193 | (14) Disclaimer of Warranty: 194 | THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS 195 | IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED 196 | WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR 197 | NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL 198 | LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL 199 | BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL 200 | DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF 201 | ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Perl 6 Design Documents 2 | ======================= 3 | 4 | This repository contains the Perl 6 design documents, also called "Synopses", 5 | in Pod (5 and 6) format. 6 | 7 | The name of the language changed from Perl6 to Raku in Oct 2019. 8 | 9 | More information can be found at [raku.org](https://raku.org) 10 | 11 | Historically, these documents have determined the direction of Perl 6. As 12 | implementations matured, this role shifted (and still shifts) towards 13 | documenting the experience from the implementations. 14 | 15 | Instead the [test suite](https://github.com/perl6/roast/) is becoming the 16 | specification, and the "specs" in the repository name of the design documents 17 | tends to mean "speculations" now. 18 | -------------------------------------------------------------------------------- /S01-overview.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | Synopsis 1: Overview 7 | 8 | =head1 VERSION 9 | 10 | Created: 10 Aug 2004 11 | 12 | Last Modified: 11 Feb 2015 13 | Version: 10 14 | 15 | This document originally summarized Apocalypse 1, which covers the 16 | initial design concept. That original summary may be found below 17 | under "Random Thoughts". However, these Synopses also contain 18 | updates to reflect the evolving design of Perl 6 over time, unlike 19 | the Apocalypses, which are frozen in time as "historical documents". 20 | These updates are not marked--if a Synopsis disagrees with its 21 | Apocalypse, assume the Synopsis is correct. 22 | 23 | Another assumption has been that if we don't talk about something in these 24 | Synopses, it's the same as it is in Perl 5. Soon we plan to fill in 25 | the gaps with the Perl 5 details though. 26 | 27 | =head1 Project Plan 28 | 29 | Mostly, we're just a bunch of ants all cooperating (sort of) to haul 30 | food toward the nest (on average). There are many groups of people 31 | working on various bits and pieces as they see fit, since this is 32 | primarily a volunteer effort. 33 | 34 | This document does not attempt to summarize all these subprojects--see 35 | L for such information. What we can say here 36 | is that, unlike how it was with Perl 5, none of these projects is 37 | designed to be the Official Perl. Perl 6 is anything that passes the 38 | official test suite. This test suite was initially developed under the 39 | Pugs project because that project was at one point the furthest along 40 | in exploring the high-level semantics of Perl 6. (Other projects 41 | may be better at other things, such as speed or interoperability. 42 | This is fine; it is not necessary that all implementations be equally 43 | good at everything.) The official test suite is community property, 44 | and is intended to be platform neutral, so that Perl 6 is defined 45 | primarily by its desired semantics, not by accidents of history. 46 | 47 | Another aspect of this is the Perl 6 compiler will be self-hosting. 48 | That is, the compiler will eventually compile itself, at least down 49 | to the point where various code-generating backends can take over. 50 | This largely removes platform dependencies from the frontend, so that 51 | only the backends need to worry about platform-specific issues. 52 | 53 | But above all, our project plan is simply to help people find a 54 | spot where they can feel like they're creating the future, both for 55 | themselves and for others. Around here, that's what we call fun. 56 | 57 | =head1 Random Thoughts 58 | 59 | =over 4 60 | 61 | =item * 62 | 63 | The word "apocalypse" historically meant merely "a revealing", 64 | and we're using it in that unexciting sense. 65 | 66 | =item * 67 | 68 | If you ask for RFCs from the general public, you get a lot of 69 | interesting but contradictory ideas, because people tend to stake 70 | out polar positions, and none of the ideas can build on each other. 71 | 72 | =item * 73 | 74 | Larry's First Law of Language Redesign: Everyone wants the colon. 75 | 76 | =item * 77 | 78 | RFCs are rated on "PSA": whether they point out a real B

roblem, 79 | whether they present a viable Bolution, and whether that solution is 80 | likely to be Bccepted as part of Perl 6. 81 | 82 | =item * 83 | 84 | Languages should be redesigned in roughly the same order as you would 85 | present the language to a new user. 86 | 87 | =item * 88 | 89 | Perl 6 should be malleable enough that it can evolve into the imaginary 90 | perfect language, Perl 7. This darwinian imperative implies support 91 | for multiple syntaxes above and multiple platforms below. 92 | 93 | =item * 94 | 95 | Many details may change, but the essence of Perl will remain unchanged. 96 | Perl will continue to be a multiparadigmatic, context-sensitive 97 | language. We are not turning Perl into any other existing language. 98 | 99 | =item * 100 | 101 | Migration is important. A Perl 6 interpreter, if invoked as "C", will assume that it 102 | is being fed Perl 5 code unless the code starts with a "class" or 103 | "module" keyword, or you specifically tell it you're running Perl 6 104 | code in some other way, such as by: 105 | 106 | #!/usr/bin/perl6 107 | use v6.0; 108 | 109 | Also, a file with a C<.p6> extension may be taken as indicative, 110 | as may any other extension containing the digit C<6>, such as C 111 | or C or C or C. (Though C<.pl> and C<.pm> are still 112 | perfectly acceptable extensions as long as the Perl-6-ness is indicated 113 | by one of the other indicators.) 114 | 115 | =item * 116 | 117 | Migration in the other direction is also important. In Perl 6 118 | mode, one can drop back to Perl 5 mode with C at the 119 | beginning of a lexical block. Such blocks may be nested: 120 | 121 | use v6; 122 | # ...some Perl 6 code... 123 | { 124 | use v5; 125 | # ...some Perl 5 code... 126 | { 127 | use v6; 128 | # ...more Perl 6 code... 129 | } 130 | } 131 | 132 | Some platforms may restrict this to a subset of Perl 5 when it is 133 | not expedient to include a full Perl 5 interpreter. The standard 134 | Perl 6 grammar will include the ability to parse a well-behaved 135 | subset of Perl 5 on its own (much like PPI does); implementations 136 | are required only to support this subset, though of course they may 137 | also choose to implement bug-for-bug compatibility. 138 | 139 | =item * 140 | 141 | Scaling is one of those areas where Perl needs to be multiparadigmatic 142 | and context sensitive. Perl 5 code is not strict by default, while 143 | Perl 6 code is. But it should be easy to relax with C<-e> or the 144 | 'no strict' pragma: 145 | 146 | perl -e '$x = 1' 147 | 148 | #!/usr/bin/perl 149 | no strict; 150 | $x = 1; 151 | 152 | =item * 153 | 154 | It must be possible to write policy metamodules that invoke other 155 | modules on the user's behalf. 156 | 157 | =item * 158 | 159 | If you want to treat everything as objects in Perl 6, Perl will help 160 | you do that. If you don't want to treat everything as objects, Perl 161 | will help you with that viewpoint as well. 162 | 163 | =item * 164 | 165 | Operators are just functions with funny names and syntax. 166 | 167 | =item * 168 | 169 | Language designers are still necessary to synthesize unrelated ideas 170 | into a coherent whole. 171 | 172 | =item * 173 | 174 | The language designer is neither omniscient nor omnipotent, and never 175 | will be, despite requests for those particular features. Therefore 176 | the design process will be spiral, cooperative, and convergent. 177 | The rate of convergence is an emergent property, and cannot be forced, 178 | only encouraged. As long as anyone is hacking on any implementation 179 | of Perl 6 to make it conform to the test suite, or hacking on the 180 | test suite to make it reflect consensus of specification, the rate 181 | of convergence will be deemed to be positive. If you are unhappy 182 | with the current rate of convergence, please cooperate more with 183 | someone else you think is interested in convergence. 184 | 185 | =item * 186 | 187 | The spec will not be frozen prematurely, but will continue to solidify 188 | as various aspects of it are proven (or disproven) in various 189 | implementations. Many parts of the spec are already effectively 190 | frozen, or are in a slushy state. "The future is already here, 191 | it's just unevenly distributed." 192 | 193 | =item * 194 | 195 | All specced features that have not been proven in an implementation 196 | should be considered somewhat conjectural, even if not so marked. 197 | As implementations start to agree on what is practical and what is not, 198 | do not be surprised if some features that are currently specced may be 199 | deferred to future versions; these should still be considered long-term 200 | direction in the evolution of Perl 6 over time, and the short-term 201 | design should be conservative in preserving that long-term evolution. 202 | Note that we are not in a hurry to defer any sections of the spec, 203 | even if that would give the illusion of progress. Convergence 204 | of specs and implementations will happen naturally as we get 205 | implementations that are closer to the spec. It is quite likely 206 | that the first practical implementation will largely determine 207 | which features are considered to be required in 6.0.0. 208 | 209 | =item * 210 | 211 | Everyone is allowed to panic I. However, continual panic will 212 | be deemed poisonous. Nobody gets special treatment, even if they 213 | think special treatment is necessary for success. This means you. 214 | 215 | =back 216 | 217 | =head1 About These Documents 218 | 219 | If you are reading the HTML version, it is generated from the POD sources 220 | in the specs repository under L, so edit 221 | it there in the git repository if you would like to make changes. 222 | 223 | =head2 Additions 224 | 225 | Please post errors and feedback to perl6-language. If you are making 226 | a general laundry list, please separate messages by topic. 227 | 228 | =head1 AUTHORS 229 | 230 | Larry Wall 231 | 232 | =for vim:set expandtab sw=4: 233 | -------------------------------------------------------------------------------- /S07-lists.pod: -------------------------------------------------------------------------------- 1 | =encoding utf8 2 | 3 | =head1 TITLE 4 | 5 | Synopsis 7: Lists and Iteration 6 | 7 | =head1 VERSION 8 | 9 | Created: 07 September 2015 10 | 11 | Last Modified: 07 September 2015 12 | Version: 1 13 | 14 | =head1 Design Overview 15 | 16 | Perl 6 provides a wide array of list-related features, including eager, lazy, 17 | and parallel evaluation of sequences of values, and arrays offering compact 18 | and multi-dimensional storage. Laziness in particular needs careful handling, 19 | so as to provide the power advanced users desire while not creating surprises 20 | for typical language users who have the (reasonable) expectation that an 21 | assignment into an array will have immediate effect. Additionally, it is 22 | important to give the programmer control of when values will and won't be 23 | retained. Finally, all of this needs to be done in a way that provides 24 | the convenience that a Perl is expected to provide, while still having a 25 | model that can be understood through understanding a small number of rules. 26 | 27 | =head2 Sequences vs. Lists 28 | 29 | In Perl 6, we use the term "sequence" to refer to something that can, when 30 | requested, produce a sequence of values. Of note, it can only be asked to 31 | produce them once. We use the term "list" to refer to things that hold (and 32 | so remember) values. There are various concrete types that represent various 33 | kinds of list and sequence with different semantics: 34 | 35 | (1, 2, 3) # a List, the simplest kind of list 36 | [1, 2, 3] # an Array, a list of (assignable) Scalar containers 37 | |(1, 2) # a Slip, a list which flattens into a surrounding List 38 | $*IN.lines # a Seq, a sequence that can be processed serially 39 | (^1000).race # a HyperSeq, a sequence that can be processed in parallel 40 | 41 | =head2 The single argument rule 42 | 43 | The C<@> sigil in Perl indicates "these", while C<$> indicates "the". This 44 | kind of plural/single distinction shows up in various places in the language, 45 | and much convenience in Perl comes from it. Flattening is the idea that an 46 | C<@>-like thing will, in certain contexts, have its values automatically 47 | incorporated into the surrounding list. Traditionally this has been a source 48 | of both great power and great confusion in Perl. Perl 6 has been through a 49 | number of models relating to flattening during its evolution, before settling 50 | on a straightforward one known as the "single argument rule". 51 | 52 | The single argument rule is best understood by considering the number of 53 | iterations that a C loop will do. The thing to iterate over is always 54 | treated as a single argument to the C loop, thus the name of the rule. 55 | 56 | for 1, 2, 3 { } # List of 3 things; 3 iterations 57 | for (1, 2, 3) { } # List of 3 things; 3 iterations 58 | for [1, 2, 3] { } # Array of 3 things (put in Scalars); 3 iterations 59 | for @a, @b { } # List of 2 things; 2 iterations 60 | for (@a,) { } # List of 1 thing; 1 iteration 61 | for (@a) { } # List of @a.elems things; @a.elems iterations 62 | for @a { } # List of @a.elems things; @a.elems iterations 63 | 64 | The first two are equivalent because parentheses do not actually construct a 65 | list, but only group. It is the C<< infix:<,> >> operator that forms a list. 66 | The third also performs three iterations, since in Perl 6 C<[...]> constructs 67 | an C but does not wrap it into a C container. The fourth will 68 | do two iterations, since the argument is a list of two things; that they both 69 | happen to have the C<@>-sigil does not, alone, lead to any kind of flattening. 70 | The same goes for the fifth; C<< infix:<,> >> will happily form a list of one 71 | thing. 72 | 73 | The single argument rule does respect C containers. Therefore: 74 | 75 | for $(1, 2, 3) { } # List in a Scalar; 1 iteration 76 | for $[1, 2, 3] { } # Array in a Scalar; 1 iteration 77 | for $@a { } # Array in a Scalar; 1 iteration 78 | 79 | The single argument rule is implemented consistently throughout the language. 80 | For example, consider the C method: 81 | 82 | @a.append: 1, 2, 3; # appends 3 values to @a 83 | @a.append: [1, 2, 3]; # appends 3 values to @a 84 | @a.append: @b; # appends @b.elems values to @a 85 | @a.append: @b,; # same, trailing comma doesn't make > 1 argument 86 | @a.append: $(1, 2, 3); # appends 1 value (a List) to @a 87 | @a.append: $[1, 2, 3]; # appends 1 value (an Array) to @a 88 | 89 | Additionally, the list constructor (the C<< infix:<,> >> operator) and the 90 | array composer (the C<[...]> circumfix) follow the rule: 91 | 92 | [1, 2, 3] # Array of 3 elements 93 | [@a, @b] # Array of 2 elements 94 | [@a, 1..10] # Array of 2 elements 95 | [@a] # Array with the elements of @a copied into it 96 | [1..10] # Array with 10 elements 97 | [$@a] # Array with 1 element (@a) 98 | [@a,] # Array with 1 element (@a) 99 | [[1]] # Same as [1] 100 | [[1],] # Array with a single element that is [1] 101 | [$[1]] # Array with a single element that is [1] 102 | 103 | The only one of these that is likely to provide a surprise is C<[[1]]>, but it 104 | is deemed sufficiently rare that it does not warrant an exception to the very 105 | general single argument rule. 106 | 107 | =head1 User-level Types 108 | 109 | =head2 List 110 | 111 | A C is an immutable, potentially infinite, list of values. The simplest 112 | way to form a List is with the C<< infix:<,> >> operator: 113 | 114 | 1, 2, 3 115 | 116 | A C can be indexed and, provided it is finite, asked for its number of 117 | elements: 118 | 119 | say (1, 2, 3)[1]; # 2 120 | say (1, 2, 3).elems; # 3 121 | 122 | As it is immutable, it is not possible to C, C, C, 123 | C, or C a C. The C and C operations 124 | return new Cs. 125 | 126 | While a C itself is immutable, it may freely contain mutable things, 127 | including C containers. Thus: 128 | 129 | my $a = 2; 130 | my $b = 4; 131 | ($a, $b)[0]++; 132 | ($a, $b)[1] *= 2; 133 | say $a; # 3 134 | say $b; # 8 135 | 136 | Trying to assign to an immutable value in a C is an error, however. 137 | 138 | (1, 2, 3)[0]++; # Dies: Cannot assign to an immutable value 139 | 140 | =head2 Slip 141 | 142 | The C type is a subclass of C. A C will have its values 143 | incorporated into a surrounding C. 144 | 145 | (1, (2, 3), 4).elems # 3 146 | (1, slip(2, 3), 4).elems # 4 147 | 148 | It is possible to coerce a C to a C, so the above can also be 149 | written as: 150 | 151 | (1, (2, 3).Slip, 4).elems # 4 152 | 153 | This is a common way to get flattening in places it will not magically take 154 | place: 155 | 156 | my @a = 1, 2, 3; 157 | my @b = 4, 5; 158 | for @a.Slip, @b.Slip { } # 5 iterations 159 | 160 | It's also a bit verbose, which is why the C<< prefix:<|> >> operator will, 161 | anywhere other than a function call argument list, do a C coercion: 162 | 163 | my @a = 1, 2, 3; 164 | my @b = 4, 5; 165 | for |@a, |@b { } # 5 iterations 166 | 167 | It can also be useful in forms such as: 168 | 169 | my @prefixed-values = 0, |@values; 170 | 171 | Where the single argument rule would otherwise make C<@prefixed-values> have 172 | two elements, the zero and C<@values>. 173 | 174 | The C type is also respected by C, C/C, and lazy 175 | loops. It is the way a C can place multiple values into its result 176 | stream: 177 | 178 | my @a = 1, 2; 179 | say @a.map({ $_ xx 2 }).elems; # 2 180 | say @a.map({ |($_ xx 2) }).elems; # 4 181 | 182 | =head2 Array 183 | 184 | An C is a subclass of C that places values assigned to it into 185 | C containers, meaning they can be mutated. It is the default type 186 | that an C<@>-sigil variable gets. 187 | 188 | my @a = 1, 2, 3; 189 | say @a.WHAT; # (Array) 190 | @a[1]++; 191 | say @a; # 1 3 3 192 | 193 | In the absence of a shape specification, it will grow automatically. 194 | 195 | my @a; 196 | @a[5] = 42; 197 | say @a.elems; # 6 198 | 199 | An C supports C, C, C, C, and C. 200 | 201 | Assignment to an array is eager by default, and creates a new set of Scalar 202 | containers: 203 | 204 | my @a = 1, 2, 3; 205 | my @b = @a; 206 | @a[1]++; 207 | say @b; # 1, 2, 3 208 | 209 | Note that the C<[...]> C constructor is equivalent to creating and 210 | then assigning to an anonymous C, and so has the same semantics with 211 | regard to eagerness and fresh containers. 212 | 213 | =head2 Seq 214 | 215 | A C is a one-shot producer of values. Most list processing operations 216 | return a C, as do most synchronous sources of multiple values. 217 | 218 | say (1, 2, 3).map(* + 1).^name; # Seq 219 | say (1, 2 Z 'a', 'b').^name; # Seq 220 | say (1, 1, * + * ... *).^name; # Seq 221 | say $*IN.lines.^name; # Seq 222 | 223 | Since a C will not by default remember its values, it can only be 224 | consumed once. For example, if a C is stored: 225 | 226 | my \seq = (1, 2, 3).map(* + 1); 227 | 228 | Then only one attempt to iterate it will work; subsequent attempts will die 229 | as the values have already been consumed: 230 | 231 | for seq { .say } # 2\n3\n4\n 232 | for seq { .say } # Dies: This Seq has already been iterated 233 | 234 | This means you can be confident that a loop going over a file's lines: 235 | 236 | for open('data').lines { 237 | .say if /beer/; 238 | } 239 | 240 | Will not be retaining the lines of the file in memory. Additionally, it is 241 | easy to set up processing pipelines that also will not retain all of the 242 | lines in memory: 243 | 244 | my \lines = open('products').lines; 245 | my \beer = lines.grep(/beer/); 246 | my \excited = beer.map(&uc); 247 | .say for excited; 248 | 249 | However, any attempt to re-use C, C, or C will result 250 | in an error. This program is equivalent in performance to: 251 | 252 | .say for open('products').lines.grep(/beer/).map(&uc); 253 | 254 | But provides a chance to name the stages. Note that it's possible to use 255 | C variables instead, but the single argument rule means that the 256 | final loop would have to be: 257 | 258 | .say for |$excited; 259 | 260 | Assigning a C to an C will - so long as the sequence is not 261 | marked lazy - eagerly perform the operation and store the results into 262 | the C. Therefore, there are no surprises to anyone writing: 263 | 264 | my @lines = open('products').lines; 265 | my @beer = @lines.grep(/beer/); 266 | my @excited = @beer.map(&uc); 267 | .say for @excited; 268 | 269 | Re-using any of these arrays will work out fine. Of course, the memory 270 | behavior of this program is radically different, and it will be slower 271 | due to all of the extra C containers created (resulting in extra 272 | garbage collection) and poor locality of reference (we have to talk about 273 | the same string many times over the programs lifetime). 274 | 275 | Occasionally it can be useful to request that a C cache itself. This 276 | can be done by calling the C method on a C, which makes a lazy 277 | C from the C and returns it. Subsequent calls to C will 278 | return the same lazy list. Note that the first call to C counts as 279 | consuming the C, and so it will not work out if any prior iteration 280 | has taken place, and any later attempt to iterate the C after calling 281 | C will also fail. It is only C<.cache> which may be called more than 282 | once. 283 | 284 | A C does not do the C role like a C. Therefore, 285 | it can not be bound to an C<@>-sigil variable: 286 | 287 | my @lines := $*IN.lines; # Dies 288 | 289 | One consequence of this is that, naively, you could not pass a C as an 290 | argument to be bound to an C<@>-sigil parameter: 291 | 292 | sub process(@data) { 293 | } 294 | process($*IN.lines); 295 | 296 | This would be rather too inconvenient. Therefore, the signature binder (which 297 | actually uses C<::=> assignment semantics rather than C<:=>) will spot failure 298 | to bind the <@>-sigil parameter, and then check if the argument does the 299 | C role. If it does, then it will call the C 300 | method on the argument and bind the result of that instead. 301 | 302 | =head2 Iterable 303 | 304 | Both C and C, along with various other types in Perl 6, do the 305 | C role. The primary purpose of this role is to promise that an 306 | C method is available. The average Perl 6 user will rarely need 307 | to care about the C method and what it returns. 308 | 309 | The secondary purpose of C is to mark out things that will 310 | flatten on demand, when the C method or function is used on them. 311 | 312 | my @a = 1, 2, 3; 313 | my @b = 4, 5; 314 | for flat @a, @b { } # 5 iterations 315 | say [flat @a, @b].elems; # 5 316 | 317 | Another use of C is to flatten nested C structure. For example, 318 | the C (zip) operator produces a C of C: 319 | 320 | say (1, 2 Z 'a', 'b').perl; # ((1, "a"), (2, "b")).Seq 321 | 322 | A C can be used to flatten these, which is useful in conjunction with 323 | a C loop using a pointy block with multiple parameters: 324 | 325 | for flat 1, 2 Z 'a', 'b' -> $num, $letter { } 326 | 327 | Note that C respects C containers, and so: 328 | 329 | for flat $(1, 2) { } 330 | 331 | Will only do one iteration. Remember that an C stores everything in a 332 | C container, and so C on an C - short of weird tricks 333 | with binding - will always be the same as iterating over the C itself. 334 | In fact, the C method on an C returns identity. 335 | 336 | =head2 HyperSeq 337 | 338 | =head2 array 339 | 340 | =head1 The Iterator API and Implementation Types 341 | 342 | =head2 The Iterator role 343 | 344 | =head2 The IterationBuffer class 345 | 346 | =head1 Parallelism 347 | 348 | =head1 AUTHORS 349 | 350 | Jonathan Worthington 351 | 352 | =for vim:set expandtab sw=4: 353 | -------------------------------------------------------------------------------- /S08-capture.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | Synopsis 8: Capture and Argument Lists 7 | 8 | =head1 VERSION 9 | 10 | Created: 20 Sep 2009 11 | 12 | Last Modified: 16 Oct 2015 13 | Version: 3 14 | 15 | =head1 Introduction 16 | 17 | Unlike most programming languages, the data structure that is used to 18 | send the parameters into a routine invocation (be it a method or a 19 | sub) is exposed to the language as a built-in type like any 20 | other. This represents a very important aspect of the Perl 6 runtime 21 | requirements. 22 | 23 | Additionally to the fact that this data structure is visible in the 24 | language type system, it is not assumed that the capture is a native 25 | type, which means that the internal representation of the data is 26 | subject to change. The only thing the runtime can assume is the API 27 | described here. 28 | 29 | Of course the runtime can cheat whenever it knows the capture is 30 | implemented by its own internal data structure for optimization 31 | purposes, but it should allow the use of foreign types when invoking a 32 | routine, as long as the object says true to C<.^does(Capture)>. 33 | 34 | Captures and argument lists are also the basis for the multidimensionality of 35 | lists in Perl 6. Unlike Perl 5, no flattening happens unless it's 36 | explicitly required by the user, which is done by enforcing the list 37 | context. If you use the item context the dimensionality should be 38 | preserved. 39 | 40 | In addition to the list and item context, there's also a special 41 | context, which is, in a simplified way, called "Capture context", but 42 | it actually means "deferred context", in a way that the Capture or 43 | List is kept as-is while they are manipulated in the code. This is 44 | useful to avoid unwanted flattening as well as avoiding the DWIMmy 45 | features that might change the capture's behavior. 46 | 47 | This is the main point of why Captures replace Perl 5 48 | references; they allow you to send data untouched from one place to 49 | another. The second reason is that as in Perl 6 everything is an 50 | object, there isn't really "pass-by-value" anymore, you're always 51 | sending a reference, Captures simply carry other objects 52 | without enforcing any context on them. 53 | 54 | =head1 Capture or List 55 | 56 | While a C is the object that holds the parameters sent to a 57 | routine (positional and named), a C is a more fundamental data 58 | structure that doesn't really differentiate named arguments from 59 | positional arguments. 60 | 61 | A list doesn't enforce any context, so a way that no flattening 62 | or coercion is done. When you examine a list object, it 63 | will include all the listed items, whether they look like named 64 | arguments or positional arguments. For example: 65 | 66 | 1, 2, :a 67 | 68 | The list represented here has 3 positional items. A List 69 | might be statically converted to a Capture if it's clear to the parser 70 | that it's being used as the arguments to a routine call. 71 | 72 | A Capture, on the other hand, is not required to keep the positional 73 | information for the named arguments, for example: 74 | 75 | foo(1,:a,2) 76 | 77 | In the call to the routine foo, there are only two positional 78 | arguments and one named argument, and you won't be able to find "b" 79 | from the C interface, but only from the Associative. 80 | 81 | The differentiation from List and Capture is important to keep the 82 | regular use of inline declarations consistent, let's say you do the 83 | following: 84 | 85 | my $a = (0, :a, 2); 86 | say $a[2]; 87 | 88 | If we had Capture and List as the same data structure, you wouldn't 89 | get C<2> as the result of the above code, because there are only two 90 | positional arguments, not three. Using the same example: 91 | 92 | sub foo($p1, $p2, :$a) {...} 93 | foo(|$a); 94 | 95 | In that case, the List is converted into a Capture, and therefore 96 | the pair C<< :a >> is no longer visible as a positional argument, 97 | only as named. 98 | 99 | Note that once you convert a List into a Capture, you won't be able 100 | to get the original List again, because a Capture doesn't hold the 101 | information about the position of named arguments. 102 | 103 | =head1 Multidimensionality 104 | 105 | Probably the most important task of Lists and Captures is to 106 | implement the multidimensionality of lists in Perl 6, this means that 107 | the barrier used to detect the dimensionality of the data structures 108 | by the operators is whatever the item inside it implements List or 109 | Capture. For instance: 110 | 111 | my $a = (1, (2, (3, 4))); 112 | say $a[1]; 113 | 114 | In that case, you'll get C<2, (3, 4)> (or whatever is implemented in 115 | the .Str method of that specific List). 116 | 117 | But, you should be able to: 118 | 119 | say $a[1;0]; 120 | 121 | Which is going to return C<2>, which is almost the same as: 122 | 123 | say $a[1][0]; 124 | 125 | But the first provides a more convenient and optimizeable way of 126 | asking for it. If you want to get the value C<4> from that data 127 | structure you need to: 128 | 129 | say $a[1;1;1]; 130 | 131 | Note that if you assign that list to an array, it will be flattened, 132 | so: 133 | 134 | my @a = 1, (2, (3, 4)); 135 | say @a[3]; 136 | 137 | Would print C<4>, at the same time that trying to ask for 138 | multidimensionality information from that list would result in a 139 | failure: 140 | 141 | say @a[1;1;1]; 142 | 143 | As the element 1 of the array C<@a> is not a Capture or a List, it is 144 | not possible for the C<.[]> operator to traverse it. 145 | 146 | [Conjecture: It is still not clear if the multidimensional access 147 | should be able to get into regular arrays, i.e.: C<[1,[2,[3,[4]]]] ]> 148 | 149 | It is important to realize that it's not the parens that are creating 150 | the List, but the C<< infix:<,> >>. The parens are only required in 151 | order to define a sub-list. 152 | 153 | On the other hand, if you bind a list to a variable, it doesn't 154 | really matter which sigil it uses: 155 | 156 | my @a := (1, (2, (3, 4))); 157 | say @a[1;1;1]; # "4" 158 | say @a[3]; # failure 159 | 160 | Captures and argument lists are seen the same way regarding 161 | multidimensionality, for instance: 162 | 163 | my $a = ((map { $_ * 2 }, 1..5),(map { $_ / 2 }, 1..5)); 164 | say $a[0;0]; # 2 165 | say $a[1;0]; # 0.5 166 | 167 | The same way, if each map closure returns more than one item inside 168 | its capture: 169 | 170 | my $a = ((map { $_ * 2, $_ / 2 }, 1..5),(map { $_ / 2, $_ * 2 }, 1..5)); 171 | say $a[0;0;0]; # 2 172 | say $a[0;0;1]; # 0.5 173 | say $a[1;0;0]; # 0.5 174 | say $a[1;0;0]; # 2 175 | 176 | The flattening process will traverse into Lists and Captures, so: 177 | 178 | 1, (2, (3, 4)) 179 | 180 | will result in: 181 | 182 | 1, 2, 3, 4 183 | 184 | after flattening, while: 185 | 186 | 1, [2, [3, 4]] 187 | 188 | Would remain as-is. 189 | 190 | =head1 Context deferral 191 | 192 | Also known as "Capture Context", defines how you can defer the context 193 | coercion for a given value. That is a fundamental feature because 194 | something as simple as assigning to a scalar might imply context 195 | coercion that would get you a modified value. 196 | 197 | Capture context is able to preserve the values as-is, 198 | in a way that you can later apply any context and have the same result 199 | as if the context was applied immediately. 200 | 201 | Context deferral is actually the reason why Perl 6 no longer supports 202 | the "wantarray" operator, nor does it provide any substitute. The way 203 | you should implement wantarray-like behavior is by properly overriding 204 | the coercion for each context. The Contextual::Return module is an 205 | implementation of that concept in Perl 5. 206 | 207 | [ The capture sigil does not exist, though left in this document for the time 208 | being pending a suitable replacement mechanism to handle context deferral.] 209 | 210 | In order to use the context deferral in your code, you need to use the 211 | "capture sigil", which can be presented in two forms: 212 | 213 | my ¢a = (1, (2, (3, 4))); 214 | 215 | =head1 AUTHORS 216 | 217 | Daniel Ruoso 218 | 219 | =for vim:set expandtab sw=4: 220 | -------------------------------------------------------------------------------- /S10-packages.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | Synopsis 10: Packages 7 | 8 | =head1 VERSION 9 | 10 | Created: 27 Oct 2004 11 | 12 | Last Modified: 9 Jul 2010 13 | Version: 13 14 | 15 | =head1 Overview 16 | 17 | This synopsis summarizes Apocalypse 10, which discusses packages 18 | despite never having been written. 19 | 20 | =head1 Packages 21 | 22 | As in Perl 5, packages are the basis of modules and classes. Unlike in 23 | Perl 5, modules and classes are declared with distinct keywords, 24 | but they're still just packages with extra behaviors. Likewise every 25 | typename has an associated package namespace, even if unused. 26 | 27 | An ordinary package is declared with the C keyword. Unlike in 28 | earlier versions of Perl 5, in Perl 6 it can only be used with a block: 29 | 30 | package Bar {...} # block is in package Bar 31 | 32 | A named package declaration can occur as part of an expression, just like 33 | named subroutine declarations. 34 | 35 | As a special exception, if a braceless C declaration occurs 36 | as the first executable statement in a file, then it's taken to mean that the rest of 37 | the file is Perl 5 code. 38 | 39 | package Foo; # the entire file is Perl 5 40 | ... 41 | 42 | This form is illegal in a Perl 6 file. If you wish to have a file-scoped package, 43 | either use the brace form or declare it with the C keyword instead. 44 | 45 | Since there are no barewords in Perl 6, package names must be predeclared. 46 | Alternatively, the sigil-like C<::PackageName> syntax may be used to indicate 47 | that the type will be supplied some other way, however this syntax is not valid 48 | in declarative scenarios, especially parameter lists where it has entirely 49 | different semantics. The C<::> prefix does not imply globalness as it does in 50 | Perl 5. (Use C for that.) 51 | 52 | A bare C declarator (without an explicit scope declarator 53 | such as C) declares an C package within the current package 54 | (or module, or class, or role, or...). Use C to declare 55 | a global package name. 56 | 57 | To declare a lexically scoped package, use C. 58 | 59 | To declare an anonymous package you can use either of 60 | 61 | package {...} 62 | package :: {...} 63 | 64 | All files start out being parsed in the C 65 | package, but may switch to some other package scope depending on the first 66 | package-ish declaration. If that first declaration is not a package variant, then 67 | the parsing switches to the "C

" package for Perl 5 code. Perl 6 code 68 | stays C in that situation. The mainline code is thus in the 69 | C namespace unless declared otherwise. 70 | 71 | Package traits are set using C: 72 | 73 | package Foo is bar {...} 74 | 75 | All symbolic links are done with the C<::($expr)> syntax, which is 76 | legal in any variable, package, module, or class name anywhere a 77 | C<::Ident> is legal. The string returned by the expression will be 78 | parsed for C<::> indicating subpackage names. Do not confuse this 79 | with the 80 | 81 | Foo::{$key} 82 | 83 | syntax that lets you do a lookup in a particular symbol table. In this case, 84 | the key is not parsed for C<::>. It's just a hash lookup. 85 | 86 | All package bodies (including module and class bodies) execute at the 87 | normal execution time of the code in which they are embedded. For normal 88 | mainline code, this is the normal flow of execution; if this is too late 89 | to initialize something in the package that you want to be initialized, consider 90 | use of a MAIN subroutine, which is invoked at the end of normal execution. 91 | See L subroutine>. 92 | 93 | For packages (modules, classes, roles, etc.) defined in separate files 94 | from the mainline code, there can be no mainline code by definition, 95 | but the top-level code in the used module needs to be executed at 96 | some point in case things need initialization. Invocation of this 97 | pseudo-mainline code in the module notionally happens no later than at 98 | the point of the C or C call in the process of compilation, 99 | but the module's code is assumed to be sufficiently uninteresting that 100 | it need be executed only once regardless of how many times the module 101 | is used subsequently in the compilation. (In fact, it might not need 102 | to run at all if the result of some previous compilation's run has 103 | been cached.) 104 | 105 | If it is desired to have code that varies in meaning from run to run, 106 | then you should put such code into an C block. (Likewise, you 107 | could put code into a C block that has inconsistent semantics 108 | from compilation to compilation, but that's probably a bad idea.) 109 | 110 | In any case, it is erroneous for any external module to depend 111 | on any knowledge of its user with respect to compilation order or 112 | other dynamic information, since other users may also depend on 113 | this single "first-use" execution and expect consistent semantics. 114 | (Really, all such dynamic dependencies should be passed in at run 115 | time to the routines or methods of your module as normal parameters or 116 | as dynamic variables. For instance, you cannot know at module compile 117 | time whether your caller is going to be using 'fatal' semantics or not. 118 | That is dynamically scoped info.) 119 | 120 | If you wish to have a module that does something extra if invoked 121 | standalone, define a MAIN subroutine, which will be ignored if 122 | the module is merely used/needed elsewhere. 123 | 124 | =head1 Package nesting 125 | 126 | A declaration of any object of the form C also creates (if needed) 127 | an empty package C, and an empty package C inside of C, in addition to creating 128 | C inside of C. Such empty packages may subsequently be redeclared as any other 129 | package-like object (module, class, etc.), and no redeclaration warning will be issued 130 | for such a redeclaration. If a parent package already exists, no stub package 131 | needs to be created, and no declaration of the form C has anything 132 | to say about the type of package C or package C, since any package variant 133 | can function as a package for the purposes of naming things. 134 | 135 | Apart of package declaration constructs, package names are always searched 136 | for from the innermost lexical scope to outermost. If not defined in any 137 | surrounding lexical scope, the package is searched for from the current 138 | package up through the containing packages to C. If it is not found, 139 | a compiler error results. 140 | 141 | As with an initial C<::>, the presence of a C<::> within the name 142 | does not imply globalness (unlike in Perl 5). True globals are always 143 | in the C namespace. 144 | 145 | The C namespace, shared by all interpreters within the process, 146 | is notionally outside of C, but package searches do not look 147 | there for anything. (Contextual variable searches do; C<$*PID> will eventually 148 | locate C<$PROCESS::PID> if not hidden by an inner callframe's C<$*PID>.) 149 | 150 | =head1 Autoloading 151 | 152 | A package (or any other similar namespace) can control autoloading. 153 | However, Perl 5's C is being superseded by MMD autoloaders 154 | that distinguish declaration from definition, but are not restricted 155 | to declaring subs. A run-time declarator multisub is declared as: 156 | 157 | multi CANDO ( MyPackage, $type, $name, *%args) 158 | 159 | which stands in for the declaration of a container object within 160 | another container object; it is called when anyone is searching for 161 | a name in the package (or module, or class), and the name doesn't 162 | already exist in the package. (In particular, C<.can> calls C 163 | when trying to determine if a class supports a particular method.) 164 | The arguments to C include type information on what kind 165 | of object is expected in context, or this may be intuited from the 166 | name requested. In any case, there may be multiple C routines 167 | that are dispatched via MMD: 168 | 169 | multi CANDO ( MyPackage, Item, $name, *%args) 170 | multi CANDO ( MyPackage, Array, $name, *%args) 171 | multi CANDO ( MyPackage, Hash, $name, *%args) 172 | multi CANDO ( MyPackage, Code, $name, *%args) 173 | 174 | The package itself is just passed as the first argument, since it's 175 | the container object. Subsequent arguments identify the desired type 176 | of the inner container and the "name" or "key" by which the object is 177 | to be looked up in the outer container. Such a name does not include 178 | its container name, unlike Perl 5's magical C<$AUTOLOAD> variable. 179 | Nor does it include the type information of a Code object's "long 180 | name"; this information comes in via the type parameter, and may be 181 | matched against using ordinary subsignature matching: 182 | 183 | multi CANDO ( MyPackage, &:($), $name, *%args) # 1 arg 184 | multi CANDO ( MyPackage, &:($,$), $name, *%args) # 2 args 185 | 186 | The slurpy C<%args> hash is likely to be empty in standard Perl 6 187 | usage, but it's possible that some dialects of Perl will desire 188 | a mechanism to pass in additional contextual information, so this 189 | parameter is reserved for such purposes. 190 | 191 | The C is expected to return an inner container object of 192 | the proper sort (i.e. a variable, subroutine, or method object), 193 | or a proxy object that can "autovivify" lazily, or C if that 194 | name is not to be considered declared in the namespace in question. 195 | (Only bare C is interpreted as "not there", since typed undefs 196 | may function as autovivifiable proxy objects. See S12.) 197 | 198 | The declaration merely defines the interface to the new object. That object 199 | need not be completely defined yet, though the C routine is certainly 200 | I to define it eagerly, and even install the inner object into the 201 | outer container (the symbol table) if it wants to cache the declaration. 202 | 203 | At declaration time it might not yet be known whether the inner 204 | container object will be used in lvalue or rvalue context; the use 205 | of a proxy object can supply either readonly or rw semantics later. 206 | 207 | When the package in question is a class, it is also possible to declare 208 | real methods or submethods: 209 | 210 | multi method CANDO ($self: Code, $name, *%args) 211 | 212 | multi submethod CANDO ($self: Item, $name, *%args) 213 | 214 | The method form is inherited by subclasses. Submethods are never 215 | inherited but may still do MMD within the class. (Ordinary multisubs 216 | are "inherited" only to the extent allowed by nested lexical scopes.) 217 | 218 | When the package in question is not a class, there is a slight problem 219 | insofar as Perl 6 doesn't by default look into packages for functions 220 | anymore, only lexical scopes. However, we'd still like the ability 221 | to dynamic add functions to a package, so there are two ways to get 222 | around the lexical limitation. 223 | 224 | First, presuming you have a C that adds to your current package, 225 | you can simply call a newly-minted subroutine explicitly via the 226 | current package: 227 | 228 | OUR::($somename)(); 229 | 230 | This bypasses the lexical namespaces entirely. Alternately, we can set 231 | up a mechanism whereby, if you import or define a C into a given 232 | lexical scope, all calls from within that scope register a failover that 233 | adds the current package to the list of places to look for subroutines (or, 234 | obviously, call the C as a last resort after that). There is no 235 | performance impact on existing lexically scoped definitions, including those 236 | from C. This approach does require that failure to find a function name 237 | cannot be reported at compile time, but must be delayed till run time instead. 238 | Another potential disadvantage is that the package's symbols are also shadowed 239 | by all symbols defined in your outer lexical scopes, including C. 240 | If this is a problem, use the direct C call above. 241 | 242 | Another way to look at it is that a lexical C adds itself to 243 | the end of the function dispatcher's search, but sets up the current 244 | package as a kind of cache for newly-defined functions just ahead of itself 245 | in the search path. 246 | 247 | =head1 AUTHORS 248 | 249 | Larry Wall 250 | 251 | =for vim:set expandtab sw=4: 252 | -------------------------------------------------------------------------------- /S13-overloading.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | Synopsis 13: Overloading 7 | 8 | =head1 VERSION 9 | 10 | Created: 2 Nov 2004 11 | 12 | Last Modified: 17 Jan 2012 13 | Version: 17 14 | 15 | =head1 Overview 16 | 17 | This synopsis discusses those portions of Apocalypse 12 that ought to have 18 | been in Apocalypse 13. 19 | 20 | =head1 Multiple dispatch 21 | 22 | The overloading mechanism of Perl 5 has been superseded by Perl 6's 23 | multiple dispatch mechanism. Nearly all internal functions 24 | are defined as C subs or C methods on generic types. 25 | Built-in operators are merely oddly named functions with an alternate 26 | call syntax. All you have to do to overload them is to define your 27 | own C subs and methods that operate on arguments with more 28 | specific types. 29 | 30 | For unary operators, this makes little effective difference, but for 31 | binary operators, multiple dispatch fixes the Perl 5 problem of paying 32 | attention only to the type of the left argument. Since both argument 33 | types are used in deciding which routine to call, there is no longer 34 | any trickery involving swapping the arguments to use the right argument's 35 | type instead of the left one. And there's no longer any need to 36 | examine a special flag to see if the arguments were reversed. 37 | 38 | For much more about multiple dispatch, see S12. 39 | 40 | =head1 Syntax 41 | 42 | There is no longer any special C syntax separate from the 43 | declarations of the C routines themselves. To overload an 44 | existing built-in sub, say something like: 45 | 46 | multi sub uc (TurkishStr $s) {...} 47 | 48 | A C is automatically exported if governed by a proto that is exported. 49 | It may also be explicitly exported: 50 | 51 | multi sub uc (TurkishStr $s) is export {...} 52 | 53 | Now if you call C on any Turkish string, it will call your 54 | function rather than the built-in one. 55 | 56 | If you import a multi into a UNIT scope, it is automatically re-exported. 57 | 58 | The types of the parameters are included in the I of any C 59 | sub or method. So if you want to overload string concatenation for Arabic 60 | strings so you can handle various ligatures, you can say: 61 | 62 | multi sub infix:<~>(ArabicStr $s1, ArabicStr $s2) {...} 63 | multi sub infix:<~>(Str $s1, ArabicStr $s2) {...} 64 | multi sub infix:<~>(ArabicStr $s1, Str $s2) {...} 65 | 66 | The C syntax had one benefit over Perl 6's syntax in that 67 | it was easy to alias several different operators to the same service 68 | routine. This can easily be handled with Perl 6's aliasing: 69 | 70 | multi sub unimpl (MyFoo $x, MyFoo $y) { upchuck(); } 71 | &infix:<+> ::= &unimpl; 72 | &infix:<-> ::= &unimpl; 73 | &infix:<*> ::= &unimpl; 74 | &infix: ::= &unimpl; 75 | 76 | A C is in effect only within the scope in which it is defined or 77 | imported. Generally you want to put your C subs into a package 78 | that will be imported wherever they are needed. 79 | 80 | Conjectural: If the first parameter to a C signature is followed 81 | by an invocant colon, that signature represents two signatures, one 82 | for an ordinary method definition, and one for the corresponding C 83 | definition that has a comma instead of the colon. This form is legal 84 | only where the standard method definition would be legal, and only 85 | if any declared type of the first parameter is consistent with C<$?CLASS>. 86 | 87 | =head1 Fallbacks 88 | 89 | Dispatch is based on a routine's signature declaration without regard 90 | to whether the routine is defined yet. If an attempt is made to 91 | dispatch to a declared but undefined routine, Perl will redispatch 92 | to an C submethod [conjectural] as appropriate to define the routine. This provides 93 | a run-time mechanism for fallbacks. By default, these declarations 94 | are taken at face value and do not specify any underlying semantics. 95 | As such, they're a "shallow" interpretation. 96 | 97 | [Note: the following section on "is deep" may no longer be necessary given 98 | the way metaoperators are now constructed.] 99 | 100 | However, sometimes you want to specify a "deep" interpretation of 101 | your operators. That is, you're specifying the abstract operation, 102 | which may be used by various shallow operators. Any deep multi 103 | declarations will be "amplified" into all the shallow operators that 104 | can be logically based on it. If you say: 105 | 106 | multi sub infix:<%> (Us $us, Them $them) is deep { mymod($us,$them) } 107 | 108 | then 109 | 110 | multi sub infix:<%=> (Us $us, Them $them) { $us = $us % $them } 111 | 112 | is also generated for you (unless you define it yourself). 113 | The mappings of magical names to sub definitions is controlled by the 114 | C<%?DEEPMAGIC> compiler hash. Pragmas can influence the contents of 115 | this hash over a lexical scope, so you could have different policies 116 | on magical autogeneration. The default mappings correspond to the 117 | standard fallback mappings of Perl 5 overloading. 118 | 119 | These deep mappings are mainly intended for infix operators that would have 120 | difficulty naming all their variants. Prefix operators tend to be simpler; 121 | note in particular that 122 | 123 | multi prefix:<~> is deep {...} 124 | 125 | is better written: 126 | 127 | method Stringy {...} 128 | 129 | (see below). 130 | 131 | =head1 Type Casting 132 | 133 | A class may define methods that allow it to respond as if it were a 134 | routine, array, or hash. The long forms are as follows: 135 | 136 | method postcircumfix:<( )> (|capture) {...} 137 | method postcircumfix:<[ ]> (**@slice) {...} 138 | method postcircumfix:<{ }> (**@slice) {...} 139 | 140 | Those are a bit unwieldy, so you may also use these short forms: 141 | 142 | method &.( |capture ) {...} 143 | method @.[ **@slice ] {...} 144 | method %.{ **@slice } {...} 145 | 146 | The sigil-dot sequence in these short forms autogenerates the 147 | corresponding public operators, in exactly the same way that 148 | the sigil-dot in: 149 | 150 | has $.action; 151 | has @.sequence; 152 | has %.mapping; 153 | 154 | autogenerates public accessor methods. 155 | 156 | And because it uses the same method-autogeneration mechanism, the 157 | specific sigil used to specify a short-form postcircumfix operator 158 | doesn't actually matter...as long as it's followed by a dot and the 159 | bracket pair containing the signature. (Though it's probably kinder 160 | to future readers of your code to stick with the "natural" sigil 161 | for each type of bracket.) 162 | 163 | Note that the angle bracket subscripting form C<< . >> 164 | automatically translates itself into a call to C< .{'a','b','c'} >, 165 | so defining methods for angles is basically useless. 166 | 167 | The expected semantics of C<&.()> is that of a type 168 | on which may 169 | or may not create a new object. So if you say: 170 | 171 | $fido = Dog.new($spot) 172 | 173 | it certainly creates a new C object. But if you say: 174 | 175 | $fido = Dog($spot) 176 | 177 | it might call C, or it might pull a C with Spot's 178 | identity from the dog cache, or it might do absolutely nothing if 179 | C<$spot> already knows how to be a C. As a fallback, if no 180 | method responds to a coercion request, the class will be asked to attempt to 181 | do C instead. 182 | 183 | It is also possible (and often preferable) to specify coercions from 184 | the other end, that is, for a class to specify how to coerce one of 185 | its values to some other class. So, if you define a method whose name 186 | happens to be type name, you can view it as a coercion to that type. But that method 187 | is a regular method even its name happens to be a type name. That means the 188 | compiler does not enforce the type of the returned value. 189 | 190 | method Str { self.makestringval() } 191 | 192 | As with all methods, you can also export the corresponding C: 193 | 194 | multi method Str is export { self.makestringval() } 195 | 196 | in which case you can use both calling forms: 197 | 198 | $x.Str 199 | Str($x) 200 | 201 | If the source class and the destination class both specify a 202 | coercion routine, the ambiguity is settled by the ordinary rules 203 | of dispatch. That is, C<$x.Str> will always prefer the method form 204 | and C will always prefer the functional form. 205 | 206 | Note that, because the name of an anonymous class is unknown, coercion to 207 | an anonymous class can only be specified by the destination class: 208 | 209 | $someclass = generate_class(); 210 | $someclass($x); 211 | 212 | =head1 AUTHORS 213 | 214 | Larry Wall 215 | 216 | =for vim:set expandtab sw=4: 217 | -------------------------------------------------------------------------------- /S16-io-OLD.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | DRAFT: Synopsis 16: IO / Name Services 7 | 8 | =head1 VERSION 9 | 10 | Created: 12 Sep 2006 11 | 12 | Last Modified: 19 Nov 2009 13 | Version: 23 14 | 15 | This is a draft document. Many of these functions will work as in Perl 16 | 5, except we're trying to rationalize everything into roles. For 17 | now you can assume most of the important functions will automatically 18 | be in the * namespace. However, with IO operations in particular, 19 | many of them are really methods on an IO handle, and if there is a 20 | corresponding global function, it's merely an exported version of 21 | the method. 22 | 23 | =head1 IO 24 | 25 | =head2 Overridable IO handles 26 | 27 | In Perl 6, there are the I IO handles, and any number of overriding 28 | inner filehandles for the same symbol. 29 | 30 | The I handles are our old familiar friends (with new names). 31 | Standard input changed from STDIN to C<$*IN>, standard output changed 32 | from STDOUT to C<$*OUT>, and standard error changed from STDERR to 33 | C<$*ERR>. In Perl 6 these symbols represent more of a concept than 34 | a given filehandle, since the meaning is contextually determined. 35 | The process's version of these handles live in the C 36 | namespace, which is more global than the per-interpreter C 37 | namespace. 38 | 39 | When no explicit filehandle is used, the standard IO operators are 40 | defined in terms of the dynamic variables. So the C function 41 | prints to C<$*OUT>, while C warns to C<$*ERR>. The C<< lines() >> 42 | term inputs from C<$*ARGFILES> which defaults to C<$*IN> in the absence of any 43 | filenames. So any given dynamic scope (interpreter, 44 | thread, function or method call) may redefine the current meaning of 45 | any of those filehandles within the dynamic scope of itself and of 46 | its called routines. 47 | 48 | So to put it another way, when you write something like 49 | 50 | say "Howdy, world!" 51 | 52 | the C function looks for the current meaning of C<$*OUT>, and 53 | takes the closest definition it can find in its callers. If none 54 | of the callers have overridden the definition, it looks in the 55 | interpreter's C namespace. If the interpreter hasn't overridden 56 | the meaning, it takes the meaning from C. In essence, any 57 | dynamic scope in Perl 6 is allowed to do IO redirection much like 58 | a Unix shell does with its subprocesses, albeit with a different 59 | syntax: 60 | 61 | { 62 | temp $*OUT = open $newfile, :w; 63 | foo() # all stdout goes to $newfile 64 | } 65 | # stdout reverts to outer scope's definition 66 | 67 | =head2 Roles and Classes 68 | 69 | The roles and classes that define most of the functionality for IO are defined in 70 | S32-setting-library/IO.pod. The main functions used are listed in S29 with references to 71 | S32-setting-library/IO.pod. 72 | 73 | =head2 Special Quoting Syntax 74 | 75 | The use of filenames requires a special quoting syntax. It works as follows: 76 | 77 | qp{/path/to/file} 78 | q:p{/path/to/file} 79 | 80 | Both of the above result in the same C object. 81 | 82 | The quote characters can be any of the usual ones, although / is probably a bad choice 83 | for filenames. 84 | 85 | The code shown above returns a Path object (or a descendant thereof). 86 | 87 | Naturally you can also ask for interpolation in filenames: 88 | 89 | qp:qq{$directory/$file} 90 | qq:p{$directory/$file} 91 | 92 | There are a number of special adverbs that can be applied to the file quoting 93 | operator. Most of these are filesystem-specific. They confine what can be 94 | included in a filename. 95 | 96 | Any path that starts with a "/" is considered an absolute path, otherwise 97 | the path is considered relative. 98 | 99 | When creating a path with qp{}, the Path.Encoding attribute is set to $?ENC, unless 100 | the :bin modifier (see below) is used. 101 | 102 | =head3 Default constraints 103 | 104 | The default constraints can be set with the "use path" pragma, for example: 105 | 106 | use path :posix; 107 | use path :modern; 108 | use path :local; 109 | 110 | The default when in strict mode is "use path :posix", whereas the default in 111 | lax mode is "use path :local". 112 | 113 | =head3 :posix constraints 114 | 115 | The :modern set of constraints paths are portable POSIX paths (see POSIX.1-2008 sections 116 | 4.7 and 3.276). If platform/filesystem specific behavior is needed, 117 | specific constraints should be applied as needed (see below). 118 | 119 | The default constraints are to only allow "/" as separator and only allows 120 | portable POSIX filenames. That means A-Z, a-z, 0-9, , , 121 | and . Additionally, hyphen may not be the first character in the path. 122 | 123 | Any path that starts with a "/" is considered an absolute path, otherwise 124 | the path is considered relative. 125 | 126 | =head3 :portable 127 | 128 | In addition to the POSIX constraints above, the path should fit into 8 129 | characters, followed by a full stop, and then three more characters. Only 130 | the one full stop should appear in the filename. Additionally, no path 131 | may be longer than 64 characters. 132 | 133 | =head3 :local 134 | 135 | This is :win on a Windows platform, :unix on a Unix platform, etc. Note 136 | that this is specifically not portable between platforms with different 137 | constraint sets. 138 | 139 | =head3 :modern constraints 140 | 141 | The :modern set of constraints are the same as :posix, except that they 142 | may contain any UTF-8 character, rather than just those listed. 143 | 144 | =head3 :win constraints 145 | 146 | We allow Windows style paths so converting and maintaining code on this 147 | platform is not a pain. 148 | 149 | my Path $path = p:win{C:\Program Files\MS Access\file.file}; 150 | 151 | Note that this specifically excludes the backslash quoting usually used with 152 | q{}. 153 | 154 | =head3 :unix constraints 155 | 156 | For Unix specific behavior we have a p:unix{} literal. Here the only 157 | limits are what is defined by the locale and the filesystem type. So we won't 158 | be able to write full Unicode if locale is set to Latin1. 159 | 160 | my Path $path = p:unix{/usr/src/bla/myfile?:%.file}; 161 | 162 | =head3 :bin constraints (no constraints at all) 163 | 164 | If the above are causing problems, p:bin{} can be used as no checking is 165 | done here. However, this leaves the Path.Encoding attribute undefined, which 166 | means that certain features of Path will remain unavailable unless this 167 | attribute is set. 168 | 169 | =head3 Other constraints 170 | 171 | It is expected that other sets of constraints, such as VMS, DOS, and old-style 172 | Mac will be provided by modules. 173 | 174 | =head2 $*CWD 175 | 176 | The global variable $*CWD is a C object with certain special 177 | properties, mainly: 178 | 179 | * It must check whether the path exists before changing its value 180 | * It can only be assigned an absolute path; if you want to make relative 181 | changes, use the Array interface with .push and .pop 182 | 183 | $*CWD is specific to the current thread, unlike C<< %*ENVZ<> >> or the 184 | native getcwd/chdir path, which are both usually process-wide. 185 | 186 | The variable is used in at least these cases: 187 | 188 | * When a IO::Path object is created, if the string it is given is not an 189 | absolute path, then $*CWD is prepended to it. 190 | * When a subprocess is executed, it is executed with the current 191 | thread's $*CWD as its working directory. 192 | 193 | =head2 $*TMPDIR 194 | 195 | The global variable $*TMPDIR is an IO::Path object which points to the system's 196 | temporary directory. It will check the usual places such a C<< %*ENVZ<> >>, 197 | C, C, etc (depending on the OS) for a writable directory. 198 | If a writable directory isn't found, it is set to $*CWD. 199 | 200 | =head1 Name Services 201 | 202 | =head2 User role 203 | 204 | role User { 205 | has $username; # Username (some descendants(?) may want to implement a real $name) 206 | has $id; # User ID 207 | has $dir; # Home directory for files 208 | } 209 | 210 | =over 211 | 212 | =item new 213 | 214 | method User new($Username?, $UID?) {...} 215 | 216 | Creates a new User object, fetching the information either by username or user ID. 217 | 218 | =item write 219 | 220 | method write() {...} 221 | 222 | Tries to write the current User object to the user database. This may well fail. 223 | 224 | =item Str 225 | 226 | When converted to a Str, returns $username. 227 | 228 | =item Num 229 | 230 | When converted to a Num, returns $uid. 231 | 232 | =back 233 | 234 | =head2 OS::Unix::User role 235 | 236 | role OS::Unix::User does User { 237 | has $password; 238 | has $gid; 239 | has $gecos; 240 | has $shell; 241 | } 242 | 243 | All the information is naturally fetched from the system via getpwuid, getpwnam, or the 244 | like. 245 | 246 | =head2 Group role 247 | 248 | role Group { 249 | has $name; 250 | has $id; 251 | has @members; 252 | } 253 | 254 | =over 255 | 256 | =item new 257 | 258 | method Group new(:$Name, :$ID); 259 | 260 | =item write 261 | 262 | method write(); 263 | 264 | Tries to write the group entry into the system group database. 265 | 266 | =back 267 | 268 | =head2 OS::Unix::NameServices role 269 | 270 | The NameServices role has a bunch of functions that between them will return the whole 271 | Name Services database between them, as lists of objects. The lists are specifically 272 | intended to be lazy. 273 | 274 | role NameServices { 275 | method List of User users() {...} # getpwent, setpwent, endpwent 276 | method List of Group groups() {...} # getgrent, setgrent, endgrent 277 | method List of Service services() {...} # getservent, setservent, endservent 278 | method List of Protocol protocols() {...} # getprotoent, setprotoent, endprotoent 279 | method List of Network networks() {...} # getnetent, setnetent, endnetent 280 | method List of Host hosts() {...} # gethostent, sethostent, endhostent 281 | } 282 | 283 | =cut 284 | 285 | =head1 AUTHORS 286 | 287 | Largely, the authors of the related Perl 5 docs. 288 | Larry Wall 289 | Mark Stosberg 290 | Tim Nelson 291 | Daniel Ruoso 292 | 293 | =for vim:set expandtab sw=4: 294 | -------------------------------------------------------------------------------- /S16-io.pod: -------------------------------------------------------------------------------- 1 | 2 | =encoding utf8 3 | 4 | =head1 TITLE 5 | 6 | Synopsis 16: I/O 7 | 8 | =head1 VERSION 9 | 10 | Created: 12 Sep 2006 11 | 12 | Last Modified: 5 Nov 2014 13 | Version: 28 14 | 15 | Many of these functions will work as in Perl 5, except we're trying to rationalize everything into roles. For 16 | now you can assume most of the important functions will automatically 17 | be in the * namespace. However, with IO operations in particular, 18 | many of them are really methods on an IO handle, and if there is a 19 | corresponding global function, it's merely an exported version of 20 | the method. 21 | 22 | =head1 IO 23 | 24 | =head2 Overridable IO handles 25 | 26 | In Perl 6, there are the I IO handles, and any number of overriding 27 | inner filehandles for the same symbol. 28 | 29 | The I handles are our old familiar friends (with new names). 30 | Standard input changed from STDIN to C<$*IN>, standard output changed 31 | from STDOUT to C<$*OUT>, and standard error changed from STDERR to 32 | C<$*ERR>. In Perl 6 these symbols represent more of a concept than 33 | a given filehandle, since the meaning is contextually determined. 34 | The process's version of these handles live in the C 35 | namespace, which is more global than the per-interpreter C 36 | namespace. 37 | 38 | When no explicit filehandle is used, the standard IO operators are 39 | defined in terms of the dynamic variables. So the C function 40 | prints to C<$*OUT>, while C prints to C<$*ERR>. The C 41 | term inputs from C<$*ARGFILES> which defaults to C<$*IN> in the absence of any 42 | filenames. So any given dynamic scope (interpreter, 43 | thread, function or method call) may redefine the current meaning of 44 | any of those filehandles within the dynamic scope of itself and of 45 | its called routines. 46 | 47 | So to put it another way, when you write something like 48 | 49 | say "Howdy, world!" 50 | 51 | the C function looks for the current meaning of C<$*OUT>, and 52 | takes the closest definition it can find in its callers. If none 53 | of the callers have overridden the definition, it looks in the 54 | interpreter's C namespace. If the interpreter hasn't overridden 55 | the meaning, it takes the meaning from C. In essence, any 56 | dynamic scope in Perl 6 is allowed to do IO redirection much like 57 | a Unix shell does with its subprocesses, albeit with a different 58 | syntax: 59 | 60 | { 61 | my $*OUT will leave *.close = open $newfile, :w; 62 | say "Written to $newfile"; 63 | } 64 | # stdout reverts to outer scope's definition, and closed the file 65 | 66 | In short: 67 | 68 | default handle 69 | routine for sub form purpose 70 | ======= =========== ======= 71 | print $*OUT string-based writing 72 | say $*OUT string-based writing 73 | get $*ARGFILES read a line (Str) 74 | lines $*ARGFILES read all lines (Str) 75 | words $*ARGFILES read all words (Str) 76 | read binary reading (Buf) 77 | write binary writing (Buf) 78 | 79 | =head2 Path Names and the .IO coercer 80 | 81 | Path names are just strings (C). Methods that return path names, will 82 | just return strings. As soon as you need to do manipulation on the path name 83 | (e.g. to find out its C or C), you can create an 84 | C object out of the string by applying the C<.IO> coercer: 85 | 86 | my $path = $filename.IO; 87 | 88 | Then you can use any of the C methods, such as C: 89 | 90 | my $handle = $newfile.IO.open(:w); 91 | 92 | Note that the C sub, is just really syntactic sugar for the above: 93 | 94 | my $handle = open $newfile, :w; 95 | 96 | =head2 $*SPEC 97 | 98 | The current system's path semantics are encapsulated in C<$*SPEC> dynamic 99 | variable. It adheres to the C interface, and is automatically 100 | initialized for the current environment. But like any dynamic variable, 101 | can be overridden in a scope: 102 | 103 | { # Win32 path semantics in here 104 | my $*SPEC = IO::Spec::Win32; 105 | ... # your code 106 | } 107 | # original path semantics here again 108 | 109 | Please note that it does B need to be an instantiated object: the standard 110 | C subclasses only provide class methods, and therefore do not need an 111 | instantiated object. But that could be different for a very specific 112 | third-party implementation of an C class. 113 | 114 | =head2 $*CWD and chdir() 115 | 116 | The dynamic variable $*CWD is an C object representing the current 117 | working directory. It is normally set with the C function, which will 118 | check whether the specified path exists as a directory and is accessible 119 | (C<-x>). 120 | 121 | chdir($dir); # sets $*CWD of scope, usually PROCESS::<$CWD> 122 | 123 | The C function returns a C Failure if the path does 124 | not exist, or is not a directory, or is not accessible. Otherwise 125 | returns a newly created C object (which will be C). 126 | 127 | Please note that the path in C<$*CWD> does not have any bearing on what the 128 | underlying operating system's concept of a "current directory". It is simply 129 | the path that will prepended before any implicit or explicit relative paths, 130 | and the default path that will be used when executing a sub-process. 131 | 132 | To be changing C<$*CWD> just for a given scope, you can use C: 133 | 134 | indir $dir, { 135 | ... your code in $dir ... 136 | }; 137 | ... your code in $*CWD again ... 138 | 139 | or you can use C with a temporary C<$*CWD>: 140 | 141 | { 142 | temp $*CWD = chddir($dir); 143 | ... your code in $dir ... 144 | } 145 | ... your code in $*CWD again ... 146 | 147 | =head2 $*TMPDIR and tmpdir() 148 | 149 | The dynamic variable C<$*TMPDIR> is an C object which points to the 150 | system's directory for temporary files. It can be set with the C 151 | function which will check whether the specified path exists as a directory and 152 | has complete access (C<+rwx>). 153 | 154 | tmpdir($dir); # sets $*TMPDIR of scope, usually PROCESS::<$TMPDIR> 155 | 156 | To set a locally scoped version of C<$*TMPDIR>, you can use C with 157 | a temporary C<$*TMPDIR>: 158 | 159 | { 160 | temp $*TMPDIR = $tmpdir($dir); 161 | ... your code with $*TMPDIR being $dir ... 162 | } 163 | ... your code in original $*TMPDIR again ... 164 | 165 | It will return a newly created C object (which is C) or an 166 | appropriate C. 167 | 168 | The initialization of C<$*TMPDIR> at startup is set depending on the OS you're 169 | on. 170 | 171 | =head2 $*HOME and homedir() 172 | 173 | The dynamic variable C<$*HOME> is an C object which points to the 174 | user's home directory. It can be set with the C function 175 | which will check whether the specified path exists as a directory and is 176 | completely accessible (C<+rwx>). 177 | 178 | homedir($dir); # sets $*HOME of scope, usually PROCESS::<$HOME> 179 | 180 | To set a locally scoped version of C<$*HOME>, you can use C with a 181 | temporary C<$*HOME>: 182 | 183 | { 184 | temp $*HOME = homedir($dir); 185 | ... your code with $*HOME being $dir ... 186 | } 187 | ... your code in original $*HOME again ... 188 | 189 | It will return a newly created C object (which is C) or an 190 | appropriate C. 191 | 192 | The initialization of C<$*HOME> at startup is set depending on the OS you're on. 193 | 194 | =head2 System dependent path semantics and IO::Spec 195 | 196 | Each time an C object is created, the current C<$*SPEC> will be 197 | encapsulated in the object, to be used for all path related operations. 198 | 199 | Of course, it is also possible to specify a specify a specific system's 200 | path semantics module when creating an C object with the C<:SPEC> 201 | named parameter: 202 | 203 | my $SPEC = IO::Spec::Win32; 204 | my $path = $fileonNTFS.IO(:$SPEC); 205 | 206 | or: 207 | 208 | my $path = $fileonNTFS.IO(:SPEC); # auto-expand to IO::Spec::Win32 209 | 210 | =head2 Functions and Classes 211 | 212 | The functions and classes that define most of the functionality for IO are 213 | more thoroughly defined in S32-setting-library/IO.pod. The main functions 214 | used are listed in S29 with references to S32-setting-library/IO.pod. 215 | An overview: 216 | 217 | =head3 Functions 218 | 219 | print(@text) # print text on $*OUT 220 | say(@text) # print text + newline on $*OUT 221 | note(@text) # print text + newline on $*ERR 222 | dd($a,$b,$c) # tiny data dumper on $*ERR 223 | $line = prompt($message) # print message on $*OUT, obtain next line 224 | 225 | $handle = open($path) # open a file, return IO::Handle 226 | 227 | @paths = dir # paths (as IO::Path) in $*CWD 228 | @paths = dir($dir) # paths (as IO::Path) in $dir 229 | 230 | $contents = slurp($handle) # read all that's left of an opened filehandle 231 | $contents = slurp($filename) # read all from given filename 232 | 233 | spurt($handle,$contents) # write $contents to $handle 234 | spurt($filename,$contents) # write $contents to $filename 235 | 236 | mkdir($dir) # create a directory 237 | rmdir($dir) # remove a directory 238 | mkpath($path) # create directory and parents as appropriate 239 | 240 | chdir($dir) # set $*CWD 241 | temp $*CWD = chdir($dir) # set $*CWD for the current scope 242 | 243 | indir($dir, { ... }) # execute code with temporary $*CWD 244 | ... 245 | }; 246 | 247 | tmpdir($dir) # set $*TMPDIR 248 | temp $*TMPDIR = tmpdir($dir) # set $*TMPDIR for the current scope 249 | 250 | homedir($dir) # set $*HOME 251 | temp $*HOME = homedir($dir) # set $*HOME for the current scope 252 | 253 | copy($from,$to) # copy a file 254 | rename($from,$to) # rename (move) a file on same physical storage 255 | move($from,$to) # move (rename) a file to other storage 256 | unlink(*@files) # remove one or more files 257 | chmod($permission,*@files) # change permissions of one or more files 258 | 259 | link($target,$source) # create a hard-link to a file 260 | symlink($target,$source) # create a symbolic link to a file 261 | 262 | =head3 IO::Spec Class 263 | 264 | The C itself only has one method: C 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 |
61 |

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.

62 | 63 |

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." 64 |

65 | 66 | 82 | 83 | 87 | 88 |
89 | 90 | 91 | 92 | 93 |         94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | 185 | 186 | 187 | 188 | 189 | 190 | 191 | 192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 209 | 210 | 211 | 212 | 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | 236 | 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | 348 | 349 |
(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
350 | 351 |
352 |

Indexes

353 | 354 | 358 |
359 | 360 |
361 |

S32 Key

362 | 363 |
364 |
* = Documents related types as well
365 |
+ = Not a type name, but documents a group of types
366 |
367 |
368 |
369 | 370 |
371 |

Differences from Perl 5

372 | 373 | 376 | 377 |

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

382 |
383 | 384 |
385 |

Further reading

386 | 387 |

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

390 |
391 |
392 | 393 |
394 |

About this page

395 | 396 |

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

406 |
407 | 408 | 409 | 410 | 411 | -------------------------------------------------------------------------------- /html/perl-with-historical-message.css: -------------------------------------------------------------------------------- 1 | @import 'perl.css'; 2 | /* We can't include the rules below inside perl.css, because it's used by other sites, 3 | and we can't specify more than one stylesheet to the podhtml.pl program. So... import 4 | */ 5 | 6 | body { 7 | padding-top: 100px; 8 | margin: 5px auto; 9 | } 10 | 11 | body:before { 12 | content: "Note: these documents may be out of date. For Perl 6 documentation see docs.perl6.org; for specs, see the official test suite."; 13 | text-align: center; 14 | background: #600; 15 | color: white; 16 | width: 100%; 17 | display: block; 18 | padding: 10px 20px; 19 | font-size: 110%; 20 | position: fixed; 21 | z-index: 10; 22 | top: 0; 23 | left: 0; 24 | } 25 | 26 | :target { 27 | display: block; 28 | padding-top: 90px; 29 | } 30 | 31 | [id^="line_"] { 32 | position: relative; 33 | } 34 | 35 | [id^="line_"]::before { 36 | color: transparent; 37 | content: attr(id); 38 | left: -9em; 39 | position: absolute; 40 | } 41 | 42 | [id^="line_"] + [id^="line_"]::before { 43 | content: none; 44 | } 45 | 46 | 47 | [id^="line_"] { 48 | position: relative; 49 | } 50 | 51 | .pod:hover [id^="line_"]::before { 52 | color: #ddd; 53 | } 54 | -------------------------------------------------------------------------------- /html/perl.css: -------------------------------------------------------------------------------- 1 | /* 2 | 3 | 4 | WARNING: this file is used by multiple .perl6.org websites (like docs.perl6.org) 5 | 6 | 7 | */ 8 | 9 | /* CSS File for Modern Browsers */ 10 | /* also, perl-ns4.css stops ns4 from crashing. */ 11 | /* Originates from svn:pugs/docs/feather/perl.css */ 12 | 13 | BODY { 14 | font-family:helvetica,sans-serif; 15 | font-size:14px; 16 | font-weight:normal; 17 | width: 730px; 18 | margin: 5px; 19 | } 20 | 21 | UL{ 22 | list-style-type: square; 23 | } 24 | 25 | A { 26 | text-decoration: none; 27 | } 28 | 29 | th { 30 | text-align: left; 31 | } 32 | 33 | tr th { 34 | font-weight: bold; 35 | } 36 | 37 | .RIGHT { 38 | text-align: right; 39 | } 40 | 41 | .HOME { 42 | text-align: right; 43 | text-decoration: underline; 44 | } 45 | 46 | .error { 47 | color: #DD0000; 48 | } 49 | 50 | /* specify link and visited so the 'hover' style doesn't apply to 51 | other links, like those which are just NAME anchors. */ 52 | A:link:hover { 53 | text-decoration: underline; 54 | color: #8B0000; /* dark red */ 55 | } 56 | A:visited:hover { 57 | text-decoration: underline; 58 | color: #8B0000; /* dark red */ 59 | } 60 | 61 | TD { 62 | font-size:14px; 63 | } 64 | 65 | .SHADED { 66 | background-color: #d2b48c; 67 | font-size:14px; 68 | font-weight: bold; 69 | font-family:helvetica,sans-serif; 70 | } 71 | 72 | /* Header */ 73 | .BANNER { 74 | font-weight: bold; 75 | font-size:18px; 76 | color: #fff; 77 | font-family:helvetica,sans-serif; 78 | background-color:#191970; 79 | padding-top: .5em; 80 | padding-left:.5em; 81 | padding-bottom:.5em; 82 | border-bottom: 4px solid #39f; 83 | border-top: 4px solid #39f; 84 | letter-spacing: 2px; 85 | /* not valid CSS 86 | line-spacing: 2px; */ 87 | } 88 | 89 | /* Navigation */ 90 | #NAV { 91 | width: 180px; 92 | font-size:12px; 93 | margin:0em; 94 | margin-top: -1px; 95 | padding:7px; 96 | background-color:#eee; 97 | border-right:1px solid #191970; 98 | border-left:1px solid #191970; 99 | } 100 | 101 | .topNAV { 102 | } 103 | 104 | .sideNAV { 105 | background-image: url("/simages/onion/onion-160x160a.gif"); 106 | background-position: bottom; 107 | background-repeat: no-repeat; 108 | } 109 | 110 | #MAIN { 111 | font-size:12px; 112 | margin-top:1em; 113 | margin-left:1em; 114 | } 115 | 116 | #MAIN TD { 117 | font-size:12px; 118 | } 119 | 120 | .INDENT { 121 | font-size:12px; 122 | margin-left:1em; 123 | } 124 | 125 | .BEGINNER { 126 | font-size:12px; 127 | border:1px solid orange; 128 | background-color: #fffacd; /* lemonchiffon */ 129 | padding:10px; 130 | width: 400px; 131 | margin-top: 1.5em; 132 | } 133 | 134 | .NAVITEM { 135 | padding-bottom:.5em; 136 | padding-top:1em; 137 | width: 180px; 138 | } 139 | 140 | .MENU { 141 | padding-bottom:1em; 142 | width: 180px; 143 | border-bottom:1px solid #191970; 144 | } 145 | 146 | .TOPIC { 147 | font-weight: bolder; 148 | font-size: 16px; 149 | color: #191970; 150 | font-family:helvetica,sans-serif; 151 | text-decoration: underline; 152 | padding-bottom: 4px; 153 | } 154 | 155 | .NAVLINE { 156 | font-size:12px; 157 | } 158 | .SMALL { 159 | font-size: xx-small; 160 | } 161 | /* 162 | .TITLE { 163 | color: #ccff66; 164 | } 165 | */ 166 | .ITEMS { 167 | font-size:14px; 168 | } 169 | 170 | .CR { 171 | border-left: 1px solid #191970; 172 | border-right: 1px solid #191970; 173 | border-bottom: 1px solid #191970; 174 | width: 180px; 175 | background-color:#eee; 176 | color: #333; 177 | padding:7px; 178 | font-size: x-small; 179 | } 180 | 181 | .DESCRIPTION { 182 | padding-bottom:1em; 183 | padding-right:1em; 184 | } 185 | 186 | .TAGLINE { 187 | letter-spacing: 2.5px; 188 | color: #666; 189 | font-size: 14px; 190 | font-family: Verdana, Sans-Serif; 191 | font-weight: 800; 192 | font-style: italic; 193 | padding-top: 3px; 194 | border-top:2px solid #191970; 195 | margin-top: -10px 196 | } 197 | 198 | /* for perl-directory style */ 199 | .PDFOOTER { 200 | font-size: 12px; 201 | padding-top: 0px; 202 | padding-bottom: 2px; 203 | margin-bottom: 12px; 204 | } 205 | 206 | /* for default style */ 207 | .FOOTER { 208 | font-size: 12px; 209 | padding-top: 3px; 210 | border-top:2px solid #191970; 211 | margin-top: -10px 212 | } 213 | 214 | HR { 215 | color: #191970; 216 | text-align: center; /* what does this do on a HR? */ 217 | padding-top: .5em; 218 | padding-bottom:.5em; 219 | } 220 | 221 | .CAMEL { 222 | float: right; 223 | /* margin-top: -5em; */ 224 | } 225 | 226 | H3 { 227 | font-size: 14px; 228 | font-family:verdana,helvetica,sans-serif; 229 | font-weight: bolder; 230 | } 231 | 232 | TR { 233 | vertical-align: top; 234 | } 235 | 236 | TD.NOVERTPAD { 237 | padding-top: 0; 238 | padding-bottom: 0; 239 | } 240 | 241 | IMG.border { 242 | border-width: 1px; 243 | border-color: #191970; 244 | border-style: solid; 245 | padding: 4px; 246 | margin: 2px; 247 | background: white; 248 | } 249 | 250 | .newsitem { 251 | width: 80%; 252 | text-align: justify; 253 | } 254 | 255 | P.fancyp:first-letter { 256 | font-size: 215%; float: left; font-family: serif; padding: 1px; 257 | } 258 | 259 | .orangebox { 260 | padding: 4px; 261 | border: 1px solid orange; 262 | font-size: 120%; 263 | font-weight: 800; 264 | text-align: center; 265 | padding: 10px 0 10px 0; 266 | margin-top: 10px; 267 | } 268 | 269 | .smartlink { 270 | margin: 0 0 0 0; 271 | padding: 0 0 0 0; 272 | background-color: #def; 273 | color: #000; 274 | } 275 | 276 | .smartlink a { 277 | color: #039; 278 | } 279 | 280 | .snip { 281 | font-family: "Courier New", Courier, Monospace; 282 | font-size: 12px; 283 | line-height: 0.8em; 284 | } 285 | 286 | .smartlink-file { 287 | text-align: right; 288 | margin: 0 0 0 0; 289 | padding: 0 0 0 0; 290 | } 291 | 292 | -------------------------------------------------------------------------------- /html/style.css: -------------------------------------------------------------------------------- 1 | body { 2 | font-family: sans-serif; 3 | line-height: 1.2; 4 | margin: 0; 5 | padding: 1.5em 0; 6 | } 7 | 8 | header, main, footer { 9 | box-sizing: border-box; 10 | margin: auto; 11 | max-width: 100vw; 12 | width: 800px; 13 | } 14 | 15 | header, aside { 16 | background: #eee; 17 | border-radius: 1em; 18 | border: 0.2em solid #ddd; 19 | color: #000; 20 | margin-bottom: 1em; 21 | padding: 0em 1em; 22 | } 23 | 24 | header { 25 | box-shadow: 0.3em 0.3em 0.6em #888; 26 | font-weight: bold; 27 | min-height: 200px; 28 | } 29 | 30 | body > header img { 31 | float: right; 32 | position: relative; 33 | right: -2em; 34 | top: -1.5em; 35 | } 36 | 37 | .specs { 38 | background: #e47286; 39 | border-color: #e43b59; 40 | } 41 | 42 | header + * { 43 | clear: both; 44 | } 45 | 46 | table { 47 | overflow-x: auto; 48 | } 49 | 50 | tbody th { 51 | text-align: left; 52 | } 53 | 54 | a:link { 55 | border-bottom: 1px dotted currentColor; 56 | text-decoration: none; 57 | } 58 | 59 | a:link:hover { 60 | border-bottom: none; 61 | text-decoration: underline; 62 | } 63 | 64 | html { 65 | padding-top: 100px; 66 | } 67 | 68 | html:before { 69 | content: "Note: these documents may be out of date. For Perl 6 documentation see docs.perl6.org; for specs, see the official test suite."; 70 | text-align: center; 71 | background: #600; 72 | color: white; 73 | width: 100%; 74 | display: block; 75 | padding: 10px 20px; 76 | font-size: 110%; 77 | position: fixed; 78 | z-index: 10; 79 | top: 0; 80 | left: 0; 81 | } 82 | 83 | :target { 84 | display: block; 85 | padding-top: 90px; 86 | } 87 | -------------------------------------------------------------------------------- /pod6-files: -------------------------------------------------------------------------------- 1 | # this file contains a list of all the synpses that are written in 2 | # Perl 6 pod, and what files they should generate. They are handled 3 | # by a separate tool. 4 | # input and output file name must be separated by a hard tab character. 5 | S15-unicode.pod S15.html 6 | S26-documentation.pod S26.html 7 | # vim: noexpandtab ts=30 8 | -------------------------------------------------------------------------------- /v6d.pod: -------------------------------------------------------------------------------- 1 | =encoding utf8 2 | 3 | This document moved to L 4 | 5 | =cut 6 | --------------------------------------------------------------------------------