diff --git a/CREDITS b/CREDITS index 64f5d33fa..e19b72fd4 100644 --- a/CREDITS +++ b/CREDITS @@ -107,6 +107,10 @@ E: dha@pobox.com N: David M. Cawthon E: dmc00@fastmail.com +N: David Simon Schultz +U: schultzdavid +E: dss@noreply.codeberg.org + N: Dmitriy Olshevskiy E: olshevskiy87@bk.ru @@ -117,6 +121,10 @@ N: Elizabeth Mattijsen U: lizmat E: liz@wenzperl.nl +N: Eric Forste +U: arkiuat +E: arkiuat@mm.st + N: ennio E: scriplit@yahoo.com @@ -376,7 +384,8 @@ N: Wenzel P. P. Peppmeyer U: gfldex E: wenzel.peppmeyer@gmx.de -N: Will "Coke" Coleda +N: Will Coleda +N: Coke E: will@coleda.com N: Xtreak diff --git a/doc/Language/about.rakudoc b/doc/Language/about.rakudoc index f996d02db..771ba7e50 100644 --- a/doc/Language/about.rakudoc +++ b/doc/Language/about.rakudoc @@ -2,7 +2,7 @@ =TITLE About the docs -=SUBTITLE How to contribute to Raku and to the documents, how to generate the docs locally +=SUBTITLE How to locally generate the Raku documentation; and how to contribute to it. This document collection represents the on-going effort to document the Raku programming language with the goals of being comprehensive, diff --git a/doc/Language/control.rakudoc b/doc/Language/control.rakudoc index 0f54d5df2..e7b3e2e88 100644 --- a/doc/Language/control.rakudoc +++ b/doc/Language/control.rakudoc @@ -273,6 +273,27 @@ for it more strongly: $_ = 1; if 42 -> $a { $_.say; $a.say } ; # says "1" then says "42" $_ = 1; if 42 { $_.say; $^a.say } ; # says "1" then says "42" +This is especially useful for patterns of the kind +"if something does not evaluate to False, do something with it": + + sub get-user-id($username) { #`(return 0 if no such username exists) } + + if prompt 'Enter username: ' -> $username { + if get-user-id($username) -> $user-id { + say "Found id $user-id for name $username"; + } + } + +Here C<$username> and C<$user-id> are only defined inside +their respective C block that guarantees their being C. +This gives this solution an advantage +over the more conventional C. + +Compare L|/language/control#with>, which tests +for definedness rather than truth, and topicalizes by default. +(The second C in the above example could be replaced by C if the routine +C returned C rather than 0 for nonexistent usernames.) + =head2 X|Control flow,else elsif> A compound conditional may be produced by following an C conditional @@ -583,7 +604,7 @@ list when they are needed, so to read a file line by line, you could use: =for code -for $*IN.lines -> $line { .say } +for $*IN.lines -> $ln { $ln.say } Iteration variables are always lexical, so you don't need to use C to give them the appropriate scope. Also, they are read-only aliases. If you need them diff --git a/doc/Language/modules.rakudoc b/doc/Language/modules.rakudoc index 3ad116dab..86a6bb09c 100644 --- a/doc/Language/modules.rakudoc +++ b/doc/Language/modules.rakudoc @@ -312,7 +312,7 @@ no matter whether the using program adds any tag or not. =end code 5. Multiple tags may be used in the C trait, but they must - all be separated by either commas, or whitespace, but not both. + all be separated by whitespace, with or without commas. =begin code sub foo() is export(:foo :s2 :net) {} diff --git a/doc/Language/perl-op.rakudoc b/doc/Language/perl-op.rakudoc index 543417329..005931831 100644 --- a/doc/Language/perl-op.rakudoc +++ b/doc/Language/perl-op.rakudoc @@ -52,7 +52,7 @@ also used for method calls. So Perl's C«$arrayref->[7]» becomes Raku's C<$arrayref.[7]> and C«$user->name» becomes C<$user.name>. Note that dereferencing is rare in Raku. -Raku uses the C<->> to attach L|/type/Signature>s to +Raku uses the C«->» to attach L|/type/Signature>s to L|/type/Block>s. =head2 Auto-increment and auto-decrement diff --git a/doc/Language/pod.rakudoc b/doc/Language/pod.rakudoc index f075f09f7..ce0a5e444 100644 --- a/doc/Language/pod.rakudoc +++ b/doc/Language/pod.rakudoc @@ -550,9 +550,16 @@ C C +If the enclosed code itself contains an unmatched C«>», +enclose it in C +=for code :lang +C«sub f(Int --> Int) {}» + +C«sub f(Int --> Int) {}» + =head2 Links -To create a link enclose it in C>: +To create a link enclose it in C> =for code :lang Raku homepage L diff --git a/doc/Language/pragmas.rakudoc b/doc/Language/pragmas.rakudoc index 56499a0c5..d779201ab 100644 --- a/doc/Language/pragmas.rakudoc +++ b/doc/Language/pragmas.rakudoc @@ -55,16 +55,27 @@ use v6.*; # Enables the available experimental preview features =head2 X +C + This pragma is not currently part of any Raku specification, but is present in Rakudo as a synonym to C (see below). =head2 X +C + +Enables usage of the C routine, +which due to its dangerousness would otherwise trigger a compiler error. +For details, see L|/type/Independent-routines#routine_EVAL>. -L +Note that, unlike the I, the C I on an object +can be executed without this pragma, +i.e. an absence of C pragmas is no guarantee against C calls. =head2 X -L +C + +Enables C for adding methods (though not attributes) to existing classes and grammars. See L. =head2 X diff --git a/doc/Language/quoting.rakudoc b/doc/Language/quoting.rakudoc index 4683407b1..a0fdfd41e 100644 --- a/doc/Language/quoting.rakudoc +++ b/doc/Language/quoting.rakudoc @@ -193,8 +193,8 @@ interpolated whenever the occur (unless escaped); that's why, in the example above, C<"$color"> became C. Variables with other sigils, however, only trigger interpolation when you follow -the variable with the appropriate postfix (C<[]> for Arrays, C«<>», for Hashes, -C<&> for Subs). This allows you to write expressions like +the variable with the appropriate postfix (C<[]> for Arrays, C«<>» or C«{}» for Hashes, +C<()> for Subs). This allows you to write expressions like C<"documentation@raku.org"> without interpolating the C<@raku> variable. To interpolate an Array (or other L|/type/Positional> variable), @@ -562,6 +562,14 @@ some multi line =end code I include the newline from before the terminator. +A common idiom to remove it is to put a L|/type/Str#routine_chomp> at the beginning, for example: + +=begin code +my $s = chomp q:to/END/; +The result will have +no final newline. +END +=end code To allow interpolation of variables use the C form, but you will then have to escape metacharacters C<\{> as well as C<$> if it is not the sigil for a diff --git a/doc/Language/regexes.rakudoc b/doc/Language/regexes.rakudoc index dc6d18f89..fc8de77b9 100644 --- a/doc/Language/regexes.rakudoc +++ b/doc/Language/regexes.rakudoc @@ -523,6 +523,7 @@ Examples of word characters: 03B4 δ GREEK SMALL LETTER DELTA 03F3 ϳ GREEK LETTER YOT 0409 Љ CYRILLIC CAPITAL LETTER LJE + 99F1 駱 CJK UNIFIED IDEOGRAPH-99F1 =end code =head3 X and C<\C>|Regexes,\c;Regexes,\C> @@ -580,7 +581,7 @@ L and C<\C>|#\c_and_\C>. | \d | Decimal digits | | Hexadecimal digit [0-9A-Fa-f] | \w | plus - | | Punctuation and Symbols (only Punct beyond ASCII) + | | Punctuation and Symbols (ASCII and non-ASCII) | | plus | \s | Whitespace | | Control characters @@ -619,7 +620,7 @@ L) shown below: Token | Regex equivalent | Description =========+===================================== | \s*: | Word-separating whitespace (including zero, e.g. at EOF) - | <.alpha> \w*: | Basic identifier (no support for ' or -). + | <.alpha> \w*: | L (no support for ' or -). =head2 X«Unicode properties|Regexes,<:property>» @@ -694,7 +695,7 @@ Categories can be used together, with an infix operator: Operator | Meaning ==========+========= \+ | set union - \- | set difference + - | set difference =end table To match either a lowercase letter or a number, write @@ -1079,7 +1080,7 @@ a regex C that matches a quoted string, then C && <-[x]>* /> matches a quoted string that does not contain the character C. Note that you cannot easily obtain the same behavior with a lookahead, that -is, a regex doesn't consume characters, because a lookahead doesn't stop +is, a regex that doesn't consume characters, because a lookahead doesn't stop looking when the quoted string stops matching. =begin code @@ -1256,18 +1257,20 @@ character of an input string. =begin table - Anchor | Description | Examples - ========+=====================+================= - ^ | Start of string | "⏏two\nlines" - ^^ | Start of line | "⏏two\n⏏lines" - $ | End of string | "two\nlines⏏" - $$ | End of line | "two⏏\nlines⏏" - << or « | Left word boundary | "⏏two ⏏words" - >> or » | Right word boundary | "two⏏ words⏏" - | Any word boundary | "⏏two⏏ ⏏words⏏~!" - | Not a word boundary | "t⏏w⏏o w⏏o⏏r⏏d⏏s~⏏!" - | Within word | "t⏏w⏏o w⏏o⏏r⏏d⏏s~!" - | Not within word | "⏏two⏏ ⏏words⏏~⏏!⏏" + Anchor | Description | Examples + =========+=====================+================= + ^ | Start of string | "⏏two\nlines" + ^^ | Start of line | "⏏two\n⏏lines" + $ | End of string | "two\nlines⏏" + $$ | End of line | "two⏏\nlines⏏" + << or « | Left word boundary | "⏏two ⏏words" + >> or » | Right word boundary | "two⏏ words⏏" + | Any word boundary | "⏏two⏏ ⏏words⏏~!" + | Not a word boundary | "t⏏w⏏o w⏏o⏏r⏏d⏏s~⏏!" + | Within word | "t⏏w⏏o w⏏o⏏r⏏d⏏s~!" + | Not within word | "⏏two⏏ ⏏words⏏~⏏!⏏" + | After nth character | "abc⏏de" for + | Not after nth char | "⏏a⏏b⏏cd⏏e" for =end table @@ -1315,6 +1318,15 @@ negative lookaround assertion behaves in the same way. In the fourth statement the last digit is matched but not consumed, thus the match includes only the first two digits. +The inbuilt named assertion C«» also works like a lookaround assertion: +It requires that the next and previous character are the same, +but consumes none of them. + +=for code +say '123345' ~~ m/ \d+ /; # OUTPUT: «｢345｣␤ same => ｢｣␤» +say 'aa11' ~~ m/ /; # OUTPUT: «False␤» + + =head2 X«Lookahead assertions|Regexes,before;Regexes,» To check that a pattern appears before another pattern, use a @@ -1583,7 +1595,7 @@ say HasOur.parse('Þor is mighty'); # OUTPUT: «｢Þor is mighty｣␤» say $HasOur::our; # OUTPUT: «Þor␤» =end code -Once the parsing has been done successfully, we use the FQN name of the C<$our> +Once the parsing has been done successfully, we use the L of the C<$our> variable to access its value, that can be none other than C<Þor>. =head2 X @@ -1681,10 +1693,13 @@ C and the other delimiters are used for other purposes. If you use balancing curly braces, square brackets, or parentheses, the substitution works like this instead: + =begin code :preamble s[replace] = 'with'; + $str ~~ s[replace] = 'with'; + =end code -The right-hand side is now a (not quoted) Raku expression, in which C<$/> -is available as the current match: +The right-hand side of the equal sign is now a (not quoted) Raku expression, +in which C<$/> is available as the current match: $_ = 'some 11 words 21'; s:g[ \d+ ] = 2 * $/; @@ -1792,7 +1807,7 @@ text out there. =head2 Common adverbs The full list of adverbs that you can apply to regular expressions can be found -elsewhere in this document (L
), but the most +elsewhere in this document (section L), but the most common are probably C<:g> and C<:i>. =item Global adverb C<:g> @@ -1823,7 +1838,7 @@ case-insensitive. .say; # OUTPUT: «vegetable␤» For more information on what these adverbs are actually -doing, refer to the L
section of this document. +doing, refer to the L section of this document. These are just a few of the transformations you can apply with the substitution operator. Some of the simpler uses in the real world include removing personal @@ -1917,11 +1932,11 @@ example, consider this Regex: / '(' <-[()]>* ')' || '('[ <-[()]>* <~~> <-[()]>* ]* ')' / -This says "match B an open parentheses, followed by zero or more -non-parentheses characters, followed by a close parentheses B an open -parentheses followed by zero or more non-parentheses characters, followed by +This says "match B an open parenthesis, followed by zero or more +non-parentheses characters, followed by a close parenthesis B an open +parenthesis followed by zero or more non-parentheses characters, followed by I, followed by zero or more non-parentheses -characters, followed by a close parentheses." This Regex allows you to match +characters, followed by a close parenthesis." This Regex allows you to match arbitrarily many nested parentheses, as show below: my $paren = rx/ '(' <-[()]>* ')' || '('[ <-[()]>* <~~> <-[()]>* ]* ')' /; @@ -1933,7 +1948,7 @@ arbitrarily many nested parentheses, as show below: Note that the last expression shown above does I match all the way to the final C<)>, as would have happened with C, nor does it match only to the first C<)>. Instead, it correctly matches -to the close parentheses paired with the first opening parentheses, an +to the close parenthesis paired with the first opening parenthesis, an effect that is very difficult to duplicate without recursive regexes. When using recursive regexes (as with any other recursive data @@ -2157,8 +2172,8 @@ C<@(code)>. In this example, both regexes are equivalent: my %h = a => 1, b => 2; my @a = %h.keys; - say S:g/@(%h.keys)/%h{$/}/ given 'abc'; # OUTPUT: «12c> - say S:g/@a/%h{$/}/ given 'abc'; # OUTPUT: «12c> + say S:g/@(%h.keys)/%h{$/}/ given 'abc'; # OUTPUT: «12c␤» + say S:g/@a/%h{$/}/ given 'abc'; # OUTPUT: «12c␤» The use of hashes in regexes is reserved. @@ -2316,10 +2331,10 @@ Square brackets and parentheses limit the scope of an adverb: Alternations and conjunctions, and their branches, have no impact on the scope of an adverb: -/ :i a | b c /; # matches 'a', 'A', 'bc', 'Bc', 'bC' or 'BC' -/ [:i a | b] c /; # matches 'ac', 'Ac', 'bc', or 'Bc' but not 'aC', 'AC', 'bC' or 'BC' + / :i a | b c /; # matches 'a', 'A', 'bc', 'Bc', 'bC' or 'BC' + / [:i a | b] c /; # matches 'ac', 'Ac', 'bc', or 'Bc' but not 'aC', 'AC', 'bC' or 'BC' -When two adverbs are used together, they keep their colon at the front +When two adverbs are used together, they each keep their colon at the front: "þor is Þor" ~~ m:g:i/þ/; # OUTPUT: «(｢þ｣ ｢Þ｣)␤» @@ -2331,7 +2346,7 @@ correspond to the same adverb, as in C<:ov> or C<:P5>. The C<:ignorecase> or C<:i> adverb instructs the regex engine to ignore the distinction between uppercase, lowercase, and titlecase letters. -See the L
+See the section L for examples. =head3 X @@ -2356,7 +2371,7 @@ in one direction and can't backtrack. Without this adverb, parts of a regex will try different ways to match a string in order to make it possible for other parts of the regex to match. For example, in C<'abc' ~~ /\w+ ./>, the C<\w+> first eats up the whole -string, C but then the C<.> fails. Thus C<\w+> gives up a character, +string, C, but then the C<.> fails. Thus C<\w+> gives up a character, matching only C, and the C<.> can successfully match the string C. This process of giving up characters (or in the case of alternations, trying a different branch) is known as backtracking. @@ -2499,7 +2514,7 @@ whitespace) is significant, it's advisable to override C. =head3 Perl compatibility adverb -The B> or B> adverb switch the Regex parsing and matching +The B> or B> adverb switches the Regex parsing and matching to the way Perl regexes behave: so 'hello world' ~~ m:Perl5/^hello (world)/; # OUTPUT: «True␤» @@ -2783,23 +2798,25 @@ last one being the I. The following is an excerpt of the output: =begin code :lang === Iteration 1 === -Capture 0 = PostgreSQL is a -Capture 1 = SQL -Capture 2 = database! [PostgreSQL is a ][SQL][ database!] === Iteration 2 === -Capture 0 = PostgreSQL is a -Capture 1 = SQL -Capture 2 = database [PostgreSQL is a ][SQL][ database] ... +=== Iteration 10 === +[PostgreSQL is a ][SQL][ ] + +=== Iteration 11 === +[Postgre][SQL][ is a SQL database!] + +=== Iteration 12 === +[Postgre][SQL][ is a SQL database] + +... + === Iteration 24 === -Capture 0 = Postgre -Capture 1 = SQL -Capture 2 = is a [Postgre][SQL][ is a ] =end code @@ -2807,18 +2824,10 @@ In the first iteration the I part of I is kept within the word: the regular expression asks for, so there's the need for another iteration. The second iteration will move back, in particular one character back (removing thus the final I) and try to match again, resulting in a fail since again the I is still kept within I. -After several iterations, the final result is match. - -It is worth noting that the final iteration is number I<24>, and that such number is exactly -the distance, in number of chars, from the end of the string to the first I occurrence: - -=begin code :preamble -say $string.chars - $string.index: 'SQL'; # OUTPUT: «23␤» -=end code - -Since there are 23 chars from the very end of the string to the very first I of I -the backtracking engine will need 23 "useless" matches to find the right one, that is, -it will need 24 steps to get the final result. +After ten iterations (the initial run and nine shortenings), the last capture C<$2> cannot be shortened any further, +so now capture C<$1> changes to matching the first instead of the second I. +The rest of the string is left for C<$2>, including the part that was backtracked before but now needs to be backtracked anew. +After 14 further iterations (the initial run and 13 shortenings), the final result is a match. Backtracking is a costly machinery, therefore it is possible to disable it in those cases where the matching can be found I only. @@ -2838,88 +2847,83 @@ occurrence of the word I (as C<$1> in the regular expression). Since the engine is not able to get backward and change the path to match, the regular expression fails. -It is worth noting that disabling backtracking will not prevent the engine -to try several ways to match the regular expression. -Consider the following slightly changed example: +In general, disabling backtracking does not mean disabling possible +multiple iterations of the matching engine, but rather disabling the backward +matching tuning. -=begin code -my $string = 'PostgreSQL is a SQL database!'; -say $string ~~ / (SQL) (.+) $1 /; # OUTPUT: «Nil␤» -=end code +To address problematic backtracking, there are also other, at times better ways. -Since there is no specification for a character before the word I, -the engine will match against the rightmost word I and go forward -from there. Since there is no repetition of I remaining, the -match fails. -It is possible, again, to inspect what the engine performs -introducing a dumping piece of code within the regular expression: +One is by using frugal quantifiers (or by leaving out certain capture groups altogether). +Most of the backtracking in our example above is indeed necessary because the +greedy capture groups C<(.+)> (especially the first one) +immediately eat up as many characters as they can. -=begin code :preamble -my $iteration = 0; -sub show-captures( Match $m ){ - my Str $result-split; - say "\n=== Iteration {++$iteration} ==="; - for $m.list.kv -> $i, $capture { - say "Capture $i = $capture"; - $result-split ~= '[' ~ $capture ~ ']'; - } +By making the first one frugal, C<(.+?)>, +we cause it to extend only until the beginning of the first I. +This way, the capture groups C<$0> and C<$1> attain +their final result right off the bat, so that the characters at the very end +need to be backtracked only once (rather than twice like above): - say $result-split; -} +=begin code :lang +$string ~~ / (.+?) (SQL) (.+) { show-captures( $/ ); } $1 /; + +=== Iteration 1 === +[Postgre][SQL][ is a SQL database!] + +=== Iteration 2 === +[Postgre][SQL][ is a SQL database] -$string ~~ / (SQL) (.+) { show-captures( $/ ); } $1 /; +... + +=== Iteration 13 === +[Postgre][SQL][ is a S] + +=== Iteration 14 === +[Postgre][SQL][ is a ] =end code -that produces a rather simple output: +Frugality of the I C<(.+)> can also helps us. +In our case, it is most useful when combined with frugality of the first. +Observe how it changes the behavior of the capture group C<$2> +from gradual shortening to gradual lengthening: =begin code :lang +$string ~~ / (.+?) (SQL) (.+?) { show-captures( $/ ); } $1 /; + === Iteration 1 === -Capture 0 = SQL -Capture 1 = is a SQL database! -[SQL][ is a SQL database!] +[Postgre][SQL][ ] === Iteration 2 === -Capture 0 = SQL -Capture 1 = database! -[SQL][ database!] -=end code +[Postgre][SQL][ i] -Even using the L<:r|/language/regexes#Ratchet> adverb to prevent backtracking will not -change things: - -=begin code :preamble -my $iteration = 0; -sub show-captures( Match $m ){ - my Str $result-split; - say "\n=== Iteration {++$iteration} ==="; - for $m.list.kv -> $i, $capture { - say "Capture $i = $capture"; - $result-split ~= '[' ~ $capture ~ ']'; - } +... - say $result-split; -} +=== Iteration 5 === +[Postgre][SQL][ is a] -$string ~~ / :r (SQL) (.+) { show-captures( $/ ); } $1 /; +=== Iteration 6 === +[Postgre][SQL][ is a ] =end code -and the output will remain the same: +On the other hand, combining ratcheting I frugal quantifiers would not help in our case. +For example: =begin code :lang +$string ~~ /:r (.+?) (SQL) { show-captures( $/ ); } (.+?) $1 /; + === Iteration 1 === -Capture 0 = SQL -Capture 1 = is a SQL database! -[SQL][ is a SQL database!] +Capture 0 = e +Capture 1 = SQL # from the word "PostgreSQL" +[e][SQL] === Iteration 2 === -Capture 0 = SQL -Capture 1 = database! -[SQL][ database!] +Capture 0 = # one whitespace +Capture 1 = SQL # from the stand-alone word "SQL" +[ ][sql] =end code -This demonstrates that disabling backtracking does not mean disabling possible -multiple iterations of the matching engine, but rather disabling the backward -matching tuning. +You can play around with putting the C<{ show-captures( $/ ); }> in different places +to get a better feel of how C<:r> and frugal as well as greedy quantifiers interact. =head2 Backtracking control @@ -2938,7 +2942,7 @@ for the third (C<\d+>). C<:ratchet> is enabled by default in Cs and Cs; see L for more details. -Raku also offers three regex metacharacters to control backtracking at for an +Raku also offers three regex metacharacters to control backtracking for an individual atom. =head3 X|Regexes,:;Regexes,disable backtracking> diff --git a/doc/Language/signatures.rakudoc b/doc/Language/signatures.rakudoc index 5971b7c43..7cf14b5bb 100644 --- a/doc/Language/signatures.rakudoc +++ b/doc/Language/signatures.rakudoc @@ -56,7 +56,6 @@ multi stuff(Int) { 3 } multi stuff(Complex) { 66 } say stuff($_) for (33, ⅓, i, 48); # OUTPUT: «58␤43␤66␤3␤» - However, you can't use C or C as literals in signatures since they will always succeed (or fail). A warning will be issued if you do so: @@ -99,15 +98,20 @@ L|/type/Signature> literals can contain string/numeric literals my $sig = :('Þor', Str, Int); say <Þor Hammer 1> ~~ $sig; # OUTPUT: «True␤» -And they can also contain the invocant marker, explained in the next section: +Signatures can contain a named L, +which I any extra named arguments into one big hash. +It can have any name; conventionally, it's an underscore: - class Foo { - method bar( $self: ){ "baz" } - }; - say Foo.^methods.first(*.name eq 'bar').signature ~~ :($: *%) ; - # OUTPUT: «True␤» + my $sig = :($p, :$n, *%_); +Signatures can also contain a slurpy positional parameter +(which must be the last of all positional parameters); +it slurps up any extra positional arguments into one big array. +The slurpy positional parameter can be one of L: + my $sig = :($p, :$n, **@_); # keep arguments the way they are + my $sig = :($p, :$n, *@_); # flatten any iterable arguments + my $sig = :($p, :$n, +@_); # flatten the argument if it is _one_ iterable, else act like **@_ =head1 Parameter separators @@ -117,9 +121,9 @@ commas. my $sig = :($a, @b, %c); sub add($a, $b) { $a + $b }; -As an exception the first parameter may be followed by a colon instead +As an exception, the first parameter may be followed by a colon instead of a comma to mark the invocant of a method. This is done in order to -distinguish it from what would then be a regular positional parameter. +distinguish it from what would otherwise be a regular positional parameter. The invocant is the object that was used to call the method, which is usually bound to L|/routine/self>. By specifying it in the signature, you can change the variable name it is bound to. @@ -132,6 +136,11 @@ change the variable name it is bound to. } } say Foo.whoami; # OUTPUT: «Well I'm class Foo, of course!␤» + say Foo.^methods.first(*.name eq 'whoami').signature ~~ :($: *%) ; # OUTPUT: «True␤» + +Another exception is the L|/language/Signatures#The_;;_separator>, +which can take the place of one comma in a L signature +to declare that the subsequent parameters should not contribute to its precedence in multiple dispatch. A further exception is the L|/language/Signatures#The_;;_separator>, which can be used in L signatures to declare that all subsequent parameters should not @@ -373,10 +382,10 @@ known collectively as I: say Int ~~ Any:_; # OUTPUT: «True␤» # Checking a subset - subset Even of Int where * // 2; - say 3 ~~ Even:D; # OUTPUT: «True␤» + subset Even of Int where * %% 2; + say 3 ~~ Even:D; # OUTPUT: «False␤» say 3 ~~ Even:U; # OUTPUT: «False␤» - say Int ~~ Even:U; # OUTPUT: «True␤» + say Int ~~ Even:U; # OUTPUT: «Use of uninitialized value of type Int in numeric context␤...␤True␤» # Checking an object instance say 42 ~~ Any:D; # OUTPUT: «True␤» @@ -424,9 +433,9 @@ positional or named, gets no value I. f Nil; # OUTPUT: «Nil␤answer␤» C<$a> has 42 as its default value. With no value, C<$a> will be assigned the -default value declared in the L|/type/Signature>. However, in the second case, it +default value declared in the L|/type/Signature>. However, in the second case, the parameter C<$a> I receive a value, which happens to be L|/type/Nil>. Assigning L|/type/Nil> to -any variable resets it to its default value, which has been declared as +any I resets it to its default value, which for C<$b> has been declared as C<'answer'> by use of the I trait. That explains what happens the second time we call C. Routine parameters and variables deal differently with default value, which is in part clarified by the different way default values are @@ -480,37 +489,42 @@ so that even an instantiated L|/type/Failure> acts as an undefined va =head2 Constraining signatures of L|/type/Callable>s -:u - -whitespace allowed): +The signature of a L parameter can be constrained by +specifying a L literal right after the parameter +(no whitespace allowed): + =begin code :skip-test sub apply(&l:(Int:D --> Int:D), Int:D \n) { l(n) } - sub identity(Int:D \i --> Int:D) { i } sub double(Int:D \x --> Int:D) { 2 * x } + say apply &double, 10; # OUTPUT: «20␤» - say apply &identity, 10; # OUTPUT: «10␤» - say apply &double, 10; # OUTPUT: «20␤» + sub general-double(Numeric:D \x --> Numeric:D) { 2 * x } + say apply &general-double, 10; # OUTPUT: «Signature constraint check failed(…)␤» + =end code -Typed L also work with -constrained callable parameters. +This shorthand syntax for constraining the signature of C<&l> +is only available because it has the C<&> sigil. +For C<$>-sigiled callable parameters, you need to use the long version with C: + + sub apply($l where .signature ~~ :(Int:D --> Int:D), Int:D \n) { + $l(n) + } + +You can also pass typed L +for constrained callable parameters like C<&l> or C<$l>: =for code :preamble say apply -> Int:D \x --> Int:D { 2 * x }, 3; # OUTPUT: «6␤» say apply -> Int:D \x --> Int:D { x ** 3 }, 3; # OUTPUT: «27␤» -Note that this shorthand syntax is available only for parameters with the C<&> -sigil. For others, you need to use the long version: +Constraints without type smileys are also possible. - sub play-with-tens($c where .signature ~~ :(Int, Str)) { say $c(10, 'ten') } - sub by-joining-them(Int $i, Str $s) { $s ~ $i } - play-with-tens &by-joining-them; # OUTPUT: «ten10␤» - play-with-tens -> Int \i, Str \s { s x (1..10).roll mod i }; # OUTPUT: «tenten␤» - - sub g(Num $i, Str $s) { $s ~ $i } - # play-with-tens(&g); # Constraint type check failed + sub play-with-tens(&c:(Int, Str)) { say c(10, 'ten') } + play-with-tens -> Int \i, Str \s { s ~ i } # OUTPUT: «ten10» + play-with-tens -> Int \i, Str \s { s x (1..30).roll mod i} # OUTPUT: «tenten(…)ten␤» =head2 Constraining return types @@ -526,11 +540,12 @@ chain. sub foo(--> Int) { Nil }; say foo.raku; # OUTPUT: «Nil␤» -Type captures are not supported. +A L can also be used +as the return type constraint (see there for details). X«|Syntax,-->» X«|Syntax,Return type arrow» -=head3 Return type arrow: C<-->> +=head3 Return type arrow: C«-->» This form of indicating return types (or constants) in the signature is preferred, since it can handle constant values while the others can't. For @@ -572,10 +587,11 @@ cannot use it in a block either. That is why the pointy arrow form is always preferred. =for code -sub greeting(Str $name) returns Str { say "Hello, $name" } # Valid +sub greeting(Str $name) returns Str { say "Hello, $name" }; # Valid +say &greeting.signature # OUTPUT: «(Str $name --> Str)␤» =for code :skip-test -sub favorite-number returns 42 { } # This will fail. +sub favorite-number returns 42 { }; # This will fail. =head3 C @@ -583,19 +599,22 @@ C is just the real name of the C keyword. =for code sub foo() of Int { 42 }; # Valid +say &foo.signature # OUTPUT: «( --> Int)␤» =for code :skip-test -sub foo() of 42 { }; # This will fail. +sub foo() of 42 { }; # This will fail. -=head3 prefix(C-like) form +=head3 prefix (C-like) form This is similar to placing type constraints on variables like C, except the C<$var> is a definition for a routine. =for code my Int sub bar { 1 }; # Valid +say &bar.signature # OUTPUT: «( --> Int)␤» + =for code :skip-test -my 42 sub bad-answer {}; # This will fail. +my 42 sub bad-answer { }; # This will fail. =head2 X @@ -603,8 +622,8 @@ To accept one type but coerce it automatically to another, use the accepted type as an argument to the target type. If the accepted type is L|/type/Any> it can be omitted. - sub f(Int(Str) $want-int, Str() $want-str) { - say $want-int.^name ~ ' ' ~ $want-str.^name + sub f(Int(Str) $becomes-int, Str() $becomes-str) { + say $becomes-int.^name ~ ' ' ~ $becomes-str.^name } f '10', 10; # OUTPUT: «Int Str␤» @@ -652,6 +671,110 @@ bar(3); =end code +X<|Language,Type capture> +=head1 Type captures + +Type captures allow deferring the specification of a type constraint to the time +the function is called. They allow referring to a type both in the signature and +the function body. + + sub f(::T $p1, T $p2, ::C){ + # $p1 and $p2 are of the same type T, that we don't know yet + # C will hold a type we derive from a type object or value + my C $division = $p1 / $p2; + return sub (T $p1) { + $division * $p1; + } + } + + # The first parameter is Int and so must be the 2nd. + # We derive the 3rd type from calling the operator that is used in &f. + my &s = f(10, 2, Int.new / Int.new); + say s(2); # 10 / 2 * 2 == 10 + +A captured type can be used as the return type constraint +(cf. L): + + sub cast-by-example(Any $x, ::T $example --> T) { T($x) } + sub cast-or-create(Any $x, ::T $example --> T:D) { with $x { T($x) } else { T.new } } + +Captured types can also be used to coerce other parameters to that type +(just like it is done in section L +for fixed types). +For example, this function coerces the second parameter C, which must be of type L|/type/Cool>, +to whichever type the first parameter C has: + + sub accum( ::T \a, T(Cool) \b ) { a += b }; + + my $t = 3; # Int + accum( $t, 5/3 ); # OUTPUT: «4␤» + + my $t = 3.0; # Rat + accum( $t, 5/3 ); # OUTPUT: «4.666667␤» + + my $t = 3.0; # Rat, and the second parameter an Array + accum ( $t, ["x","y"] ); # OUTPUT: «5.0» + +Type captures can also be subject to type constraints. +In the example above, certain nonsensical calls could be prevented by changing +the signature to one of the following: + + =for code :skip-test + (Numeric ::T \a, T(Cool) \b ) + (::T Numeric \a, T(Cool) \b ) + +See also section C +in the type reference for C. + + +X<|Language,positional argument> +X<|Language,named argument> +=head1 Positional vs. named arguments + +An argument can be I or I. By default, arguments are +positional, except slurpy hash and arguments marked with a leading colon C<:>. +The latter is called a L. Check the following signatures +and what they denote: + +=for code :preamble +$sig1 = :($a); # a positional argument +$sig2 = :(:$a); # a named argument of name 'a' +$sig3 = :(*@a); # a slurpy positional argument +$sig4 = :(*%h); # a slurpy named argument + +On the caller side, positional arguments are passed in the same order as the +arguments are declared. + + sub pos($x, $y) { "x=$x y=$y" } + pos(4, 5); # OUTPUT: «x=4 y=5» + +In the case of named arguments and parameters, only the name is used for mapping +arguments to parameters. If a fat arrow is used to construct a +L|/type/Pair> only those with valid identifiers as keys are recognized as +named arguments. + +=for code +sub named(:$x, :$y) { "x=$x y=$y" } +named( y => 5, x => 4); # OUTPUT: «x=4 y=5» + +You can invoke the routine using a variable with the same name as the named +argument; in that case C<:> will be used for the invocation so that the name of +the variable is understood as the key of the argument. + + sub named-shortcut( :$shortcut ) { + say "Looks like $shortcut" + } + named-shortcut( shortcut => "to here"); # OUTPUT: «Looks like to here␤» + my $shortcut = "Þor is mighty"; + named-shortcut( :$shortcut ); # OUTPUT: «Looks like Þor is mighty␤» + +It is possible to have a different name for a named argument than the +variable name: + + sub named(:official($private)) { "Official business!" if $private } + named :official; + + X<|Syntax,*@> X<|Syntax,*%> X<|Language,slurpy argument> @@ -665,8 +788,8 @@ make routines that use them I, and by extension are called variadic arguments. Here we will focus on slurpy parameters, or simply I. An array or hash parameter can be -marked as I by leading single (*) or double asterisk (**) or a -leading plus (+). A slurpy parameter can bind to an arbitrary number of +marked as I by leading single (C<*>) or double asterisk (C<**>) or a +leading plus (C<+>). A slurpy parameter can bind to an arbitrary number of arguments (zero or more), and it will result in a type that is compatible with the sigil. @@ -739,7 +862,7 @@ L, as described in L. -Methods automatically get a C<*%_> slurpy named parameter added if they +L automatically get a C<*%_> slurpy named parameter added if they don't have another slurpy named parameter declared. =head1 Types of slurpy array parameters @@ -775,6 +898,17 @@ a(($_ for 1, 2, 3)); # OUTPUT: «[1, 2, 3]␤» A single asterisk slurpy flattens all given iterables, effectively hoisting any object created with commas up to the top level. +Such flattening can be prevented for individual arguments +by putting them in an L. +This can be done by prepending the sigil C<$> or by applying the C<.item> method: + +=begin code +sub slurp(*@pos) { say @pos; } +my @array = [5,6]; +slurp([1,2], $[3,4], $@array); # OUTPUT: «[1 2 [3 4] [5 6]]␤» +slurp([1,2], [3,4].item, @array.item) # OUTPUT: «[1 2 [3 4] [5 6]]␤» +=end code + =head2 X Slurpy parameters declared with two stars do not flatten any @@ -798,7 +932,6 @@ in the slurpy array. X<|Syntax,+ (Single argument rule slurpy)> =head2 Single argument rule slurpy - A slurpy parameter created using a plus engages the I<"single argument rule">, which decides how to handle the slurpy argument based upon context. Basically, if only a single argument is passed and that argument is @@ -818,73 +951,6 @@ c(($_ for 1, 2, 3)); # OUTPUT: «[1, 2, 3]␤» For additional discussion and examples, see L. -X<|Language,Type capture> -=head1 Type captures - -Type captures allow deferring the specification of a type constraint to the time -the function is called. They allow referring to a type both in the signature and -the function body. - - sub f(::T $p1, T $p2, ::C){ - # $p1 and $p2 are of the same type T, that we don't know yet - # C will hold a type we derive from a type object or value - my C $division = $p1 / $p2; - return sub (T $p1) { - $division * $p1; - } - } - - # The first parameter is Int and so must be the 2nd. - # We derive the 3rd type from calling the operator that is used in &f. - my &s = f(10, 2, Int.new / Int.new); - say s(2); # 10 / 2 * 2 == 10 - -X<|Language,positional argument> -X<|Language,named argument> -=head1 Positional vs. named arguments - -An argument can be I or I. By default, arguments are -positional, except slurpy hash and arguments marked with a leading colon C<:>. -The latter is called a L. Check the following signatures -and what they denote: - -=for code :preamble -$sig1 = :($a); # a positional argument -$sig2 = :(:$a); # a named argument of name 'a' -$sig3 = :(*@a); # a slurpy positional argument -$sig4 = :(*%h); # a slurpy named argument - -On the caller side, positional arguments are passed in the same order as the -arguments are declared. - - sub pos($x, $y) { "x=$x y=$y" } - pos(4, 5); # OUTPUT: «x=4 y=5» - -In the case of named arguments and parameters, only the name is used for mapping -arguments to parameters. If a fat arrow is used to construct a -L|/type/Pair> only those with valid identifiers as keys are recognized as -named arguments. - -=for code -sub named(:$x, :$y) { "x=$x y=$y" } -named( y => 5, x => 4); # OUTPUT: «x=4 y=5» - -You can invoke the routine using a variable with the same name as the named -argument; in that case C<:> will be used for the invocation so that the name of -the variable is understood as the key of the argument. - - sub named-shortcut( :$shortcut ) { - say "Looks like $shortcut" - } - named-shortcut( shortcut => "to here"); # OUTPUT: «Looks like to here␤» - my $shortcut = "Þor is mighty"; - named-shortcut( :$shortcut ); # OUTPUT: «Looks like Þor is mighty␤» - -It is possible to have a different name for a named argument than the -variable name: - - sub named(:official($private)) { "Official business!" if $private } - named :official; X<|Language,argument aliases> =head1 Argument aliases @@ -999,14 +1065,14 @@ Table showing checks of whether an argument was passed for a given parameter: ===============|================|============================|======================== Slurpy | *@array | Don't check using .defined | if not @array Required | $foo | Can't be omitted | (not applicable) - Optional | @bar = default | Pick a suitable default¹ | if @bar =:= default + Optional | @bar = default | Pick a suitable default¹ | if @bar === default =end table -¹ A suitable default is an Object that has a distinct identity, as may be checked by the L|https://docs.raku.org/type/Mu#method_WHICH> method. +¹ A suitable default is an Object that has a distinct identity, as may be checked by the L|/type/Mu#method_WHICH> method. A parameter with a default is always I, so there is no need to mark it with a C. -Then you can use the C<===> L in the body of the routine to check +Then you can use the C<===> L in the body of the routine to check whether this exact default object was bound to the parameter. These examples use names like C to reflect that the C<.WHICH> test invoked by C<===> returns an object of type L|/type/ObjAt>. @@ -1014,7 +1080,7 @@ Example with a positional parameter: =begin code my constant PositionalAt = Positional.new; -sub a (@list = PositionalAt) { say @list === PositionalAt } # here, one can also use =:=, the container identity operator +sub a (@list = PositionalAt) { say @list === PositionalAt } a; # OUTPUT: «True␤» a [1, 2, 3]; # OUTPUT: «False␤» =end code @@ -1023,13 +1089,13 @@ Example with some scalar parameters: =begin code my constant AnyAt = Any.new; -sub b ($x=AnyAt, :$y=AnyAt) { say $x === AnyAt; say $y === AnyAt } # here, =:= would always produce False +sub b ($x=AnyAt, :$y=AnyAt) { say $x === AnyAt; say $y === AnyAt } b 1; # OUTPUT: «False␤True␤» b 1, :2y; # OUTPUT: «False␤False␤» =end code -If your parameters are typed, then the L can be used with -L|https://docs.raku.org/language/functions#Multi-dispatch>s like this: +If your parameters are typed, then the L can be used with +L|/language/functions#Multi-dispatch>s like this: =begin code multi c (Int:U $z) { say 'Undefined' } @@ -1156,23 +1222,23 @@ Consider this example with a named parameter: # both 42 and ｢｣␤ in sub e at line 1␤» Here it was the I multi that got executed, -because its signature is narrower than the first and does in fact match C, even though $s then stays undefined. -By adding C<;;>, we can lower its precedence: +because its signature is narrower than the first and does in fact match C, even though C<$s> then stays undefined. +By adding C<;;>, we can lower its precedence to match that of the first: - multi f(Int $i) { say "just $i" }; - multi f(Int $i;; Str :$s) { say "both $i and ｢$s｣" }; - f(42); - # OUTPUT: «Ambiguous call to 'e(Int)'; these signatures all match: + multi baz(Int $i) { say "just $i" }; + multi baz(Int $i;; Str :$s) { say "both $i and ｢$s｣" }; + baz(42); + # OUTPUT: «Ambiguous call to 'baz(Int)'; these signatures all match: # (Int $i) from line 1␤ (Int $i;; Str :$s) from line 1␤ ...» One could then give the first multi the trait L|/type/Routine#trait_is_default>, whose exact effect is -to break a tie between multiple signatures of the same precedence. +to break a tie between signatures of the same precedence. There is more than one way to control the narrowness (and thereby, precedence) of signatures. Other options include making parameters optional via C or required via C. -The double semicolon C<;;> can also be used in signatures of L. +The double semicolon C<;;> can also be used in signatures of L. Parameterized roles have a so-called "long name" generated from their signature, which can be used for introspection. Only parameters to the left of C<;;> contribute to it. diff --git a/doc/Type/Any.rakudoc b/doc/Type/Any.rakudoc index 5a342da88..2ef10502e 100644 --- a/doc/Type/Any.rakudoc +++ b/doc/Type/Any.rakudoc @@ -352,22 +352,6 @@ is considered to be a key again). It returns a L|/type/Seq> of L| say (a => 1, 'b', 'c').pairup.raku; # OUTPUT: «(:a(1), :b("c")).Seq␤» X<|Syntax,$ (item contextualizer)> -=head2 sub item - - multi item(\x) - multi item(|c) - multi item(Mu $a) - -Forces given object to be evaluated in item context and returns the value of it. - - say item([1,2,3]).raku; # OUTPUT: «$[1, 2, 3]␤» - say item( %( apple => 10 ) ).raku; # OUTPUT: «${:apple(10)}␤» - say item("abc").raku; # OUTPUT: «"abc"␤» - -You can also use C<$> as item contextualizer. - - say $[1,2,3].raku; # OUTPUT: «$[1, 2, 3]␤» - say $("abc").raku; # OUTPUT: «"abc"␤» =head2 method Array @@ -667,8 +651,9 @@ function called from the C statement. .say for 3; # OUTPUT: «3␤» -Most subclasses redefine this method for optimization, so it's mostly types that -do not actually iterate the ones that actually use this implementation. +An iterable subclass should provide its own implementation of this +method, but other classes can inherit this as-is to provide a +single-item-list iterator in contexts that require one. =head2 method pick diff --git a/doc/Type/DateTime.rakudoc b/doc/Type/DateTime.rakudoc index 30a5d0c82..4312f3366 100644 --- a/doc/Type/DateTime.rakudoc +++ b/doc/Type/DateTime.rakudoc @@ -280,6 +280,10 @@ is used in astronomy to define times of celestial objects transiting the Earth's Prime Meridian. For any instant, it is the sum of the number of whole days and the fraction of a day from that epoch to that instant. +Before Rakudo release 2025.08, the C method does B +use any timezone information, and silently ignores it in the +C object. + Available as of the 2021.04 Rakudo compiler release. =head2 method modified-julian-date @@ -296,6 +300,10 @@ reference the same epoch (November 17, 1858). The MJD is obtained by subtracting the constant C<2_400_000.5> from the I and is used to simplify transformations between civil and astronomical time systems. +Before Rakudo release 2025.08, the C method +does B use any timezone information, and silently ignores it in +the C object. + Available as of the 2021.04 Rakudo compiler release. =head2 method posix diff --git a/doc/Type/Iterable.rakudoc b/doc/Type/Iterable.rakudoc index 59f13a865..e8243cbbd 100644 --- a/doc/Type/Iterable.rakudoc +++ b/doc/Type/Iterable.rakudoc @@ -68,7 +68,7 @@ C«(, 'c').flat» returns C<('a', 'b', 'c')>, which has three elems. Note that the flattening is recursive, so C<((("a", "b"), "c"), "d").flat> returns C<("a", "b", "c", "d")>, but it does not flatten -itemized sublists: +L sublists: say ($('a', 'b'), 'c').flat; # OUTPUT: «($("a", "b"), "c")␤» diff --git a/doc/Type/Mu.rakudoc b/doc/Type/Mu.rakudoc index ddb0f3083..7765a229b 100644 --- a/doc/Type/Mu.rakudoc +++ b/doc/Type/Mu.rakudoc @@ -16,7 +16,6 @@ L|/type/Any>. =head1 Methods - =head2 method iterator method iterator(--> Iterator) @@ -28,37 +27,31 @@ method and uses L«C|/type/Iterable#method_iterator» on it. say $it.pull-one; # OUTPUT: «(Mu)␤» say $it.pull-one; # OUTPUT: «IterationEnd␤» -=head2 method defined +=head2 routine defined multi method defined( --> Bool:D) + multi defined(Mu --> Bool:D) -Returns C on a type object, and C otherwise. +Returns C on a type object, and C otherwise. (The sub +evaluates its argument, and the method its invocant.) say Int.defined; # OUTPUT: «False␤» say 42.defined; # OUTPUT: «True␤» -A few types (like L|/type/Failure>) override C to return -C even for instances: +A few types (like L|/type/Failure>) override C to +return C even for instances: sub fails() { fail 'oh noe' }; say fails().defined; # OUTPUT: «False␤» - -=head2 routine defined - - multi defined(Mu --> Bool:D) - -invokes the C<.defined> method on the object and returns its result. - - -=head2 routine isa +=head2 method isa multi method isa(Mu $type --> Bool:D) multi method isa(Str:D $type --> Bool:D) Returns C if the invocant is an instance of class C<$type>, a subset type or a derived class (through inheritance) of C<$type>. -L|/routine/does#(Mu)_routine_does> is similar, but includes roles. +L|/method/does#(Mu)_method_does> is similar, but includes roles. my $i = 17; say $i.isa("Int"); # OUTPUT: «True␤» @@ -69,8 +62,7 @@ L|/routine/does#(Mu)_routine_does> is similar, but includes roles. say $but-true.does(Truish); # OUTPUT: «True␤» say $but-true.isa(Truish); # OUTPUT: «False␤» - -=head2 routine does +=head2 method does method does(Mu $type --> Bool:D) @@ -82,7 +74,7 @@ say $d.does(Dateish); # OUTPUT: «True␤» (Date does role Datei say $d.does(Any); # OUTPUT: «True␤» (Date is a subclass of Any) say $d.does(DateTime); # OUTPUT: «False␤» (Date is not a subclass of DateTime) -Unlike L|/routine/isa#(Mu)_routine_isa>, which +Unlike L|/method/isa#(Mu)_method_isa>, which returns C only for superclasses, C includes both superclasses and roles. @@ -98,8 +90,8 @@ Using the smartmatch operator L<~~|/routine/~~> is a more idiomatic alternative. =head2 routine Bool - multi Bool(Mu --> Bool:D) multi method Bool( --> Bool:D) + multi Bool(Mu --> Bool:D) Returns C on the type object, and C otherwise. @@ -143,8 +135,8 @@ readable. Method L|/type/Str> warns on type objects, and produces the emp =head2 routine gist - multi gist(+args --> Str) multi method gist( --> Str) + multi gist(+args --> Str) Returns a string representation of the invocant, optimized for fast recognition by humans. As such lists will be truncated at 100 elements. Use C<.raku> to get @@ -184,15 +176,25 @@ that can be used via L«C|/routine/EVAL» to reconstruct the value of the say (1..3).Set.raku; # OUTPUT: «Set.new(1,2,3)␤» -=head2 method item +=head2 routine item method item(Mu \item:) is raw + multi item(\x) + multi item(|c) + multi item(Mu $a) -Forces the invocant to be evaluated in item context and returns the value of it. +Forces the invocant to be evaluated in item context and returns the +value of it. say [1,2,3].item.raku; # OUTPUT: «$[1, 2, 3]␤» say %( apple => 10 ).item.raku; # OUTPUT: «${:apple(10)}␤» - say "abc".item.raku; # OUTPUT: «"abc"␤» + say item([1,2,3]).raku; # OUTPUT: «$[1, 2, 3]␤» + say item("abc").raku; # OUTPUT: «"abc"␤» + +You can also use C<$> as item contextualizer. + + say $[1,2,3].raku; # OUTPUT: «$[1, 2, 3]␤» + say $("abc").raku; # OUTPUT: «"abc"␤» =head2 method self @@ -343,7 +345,7 @@ initializing any attributes. say Mu.CREATE.defined; # OUTPUT: «True␤» -=head2 method print +=head2 routine print multi method print(--> Bool:D) @@ -352,7 +354,7 @@ adding a newline at end. "abc\n".print; # OUTPUT: «abc␤» -=head2 method put +=head2 routine put multi method put(--> Bool:D) @@ -361,7 +363,7 @@ stringifying non-L|/type/Str> object using the C<.Str> method. "abc".put; # OUTPUT: «abc␤» -=head2 method say +=head2 routine say multi method say() @@ -456,7 +458,8 @@ are marked as C. See L for more details. -=head2 method return + +=head2 routine return method return() @@ -470,12 +473,12 @@ can be caught with L. sub f { (1|2|3).return }; say f(); # OUTPUT: «any(1, 2, 3)␤» -=head2 method return-rw +=head2 routine return-rw -Same as method L|/type/Mu#method_return> except that C returns a writable +Same as routine L|/type/Mu#routine_return> except that C returns a writable container to the invocant (see more details here: L|/language/control#return-rw>). -=head2 method emit +=head2 routine emit method emit() @@ -492,11 +495,23 @@ L block. # received Int (42) # received Rat (0.5) -=head2 method take +=head2 routine take + sub take(\item) method take() -Returns the invocant in the enclosing L block. +The sub takes the given item and passes it to the enclosing C +block. + + #| randomly select numbers for lotto + my $num-selected-numbers = 6; + my $max-lotto-numbers = 49; + gather for ^$num-selected-numbers { + take (1 .. $max-lotto-numbers).pick(1); + }.say; # six random values + +The method returns the invocant in the enclosing +L block. sub insert($sep, +@list) { gather for @list { @@ -508,20 +523,7 @@ Returns the invocant in the enclosing L bl say insert ':', ; # OUTPUT: «(a : b : c)␤» -=head2 routine take - - sub take(\item) - -Takes the given item and passes it to the enclosing C block. - - #| randomly select numbers for lotto - my $num-selected-numbers = 6; - my $max-lotto-numbers = 49; - gather for ^$num-selected-numbers { - take (1 .. $max-lotto-numbers).pick(1); - }.say; # six random values - -=head2 routine take-rw +=head2 sub take-rw sub take-rw(\item) @@ -533,7 +535,7 @@ Returns the given item to the enclosing C block, without introducing a n say @a; # OUTPUT: «[2 3 4]␤» -=head2 method so +=head2 routine so method so() @@ -557,7 +559,7 @@ any(False, False), any(False, False), any(True, False))>. That is actually a I value; thus, negating it will yield C. The negation of that result will be C. C is performing all those operations under the hood. -=head2 method not +=head2 routine not method not() diff --git a/doc/Type/Range.rakudoc b/doc/Type/Range.rakudoc index 996330060..139bb428f 100644 --- a/doc/Type/Range.rakudoc +++ b/doc/Type/Range.rakudoc @@ -116,6 +116,12 @@ with the exception. It will print C by default. =head1 Methods +=head2 method new + + multi method new(Range: \min, \max, :$excludes-min, :$excludes-max) + +Creates a new Range with the given minimum and maximum, and with the min and +max excluded based on the values passed in the corresponding named arguments. =head2 method ACCEPTS diff --git a/doc/Type/independent-routines.rakudoc b/doc/Type/independent-routines.rakudoc index bd4e64534..2e43938de 100644 --- a/doc/Type/independent-routines.rakudoc +++ b/doc/Type/independent-routines.rakudoc @@ -31,8 +31,8 @@ such as a variable or string with embedded code, is illegal by default. This can be overridden in any of several ways: use MONKEY-SEE-NO-EVAL; # Or... - use MONKEY; # shortcut that turns on all MONKEY pragmas - use Test; + use MONKEY; # shortcut that turns on all MONKEY pragmas, or... + use Test; # a module that activates MONKEY-SEE-NO-EVAL. my $init = 0; my $diff = 10; diff --git a/util/test-modified.sh b/util/test-modified.sh index 327c690ac..d85d47701 100755 --- a/util/test-modified.sh +++ b/util/test-modified.sh @@ -1,3 +1,5 @@ +#!/bin/sh + # This script will run make xtest on any files in the repository that have not yet been committed # use before 'git commit' to ensure your commit doesn't require correction. diff --git a/xt/pws/code.pws b/xt/pws/code.pws index 6e0485abc..d4fc5571a 100644 --- a/xt/pws/code.pws +++ b/xt/pws/code.pws @@ -130,6 +130,7 @@ cha charbuf childclass childname +cjk cliché clogger cn diff --git a/xt/pws/words.pws b/xt/pws/words.pws index 6b8975c29..ebe847190 100644 --- a/xt/pws/words.pws +++ b/xt/pws/words.pws @@ -289,6 +289,7 @@ cwd cx cygwin daenerys +dangerousness dany dataflow datehash diff --git a/xt/type-graph.rakutest b/xt/type-graph.rakutest index ca8c0e40e..06f3c64b0 100755 --- a/xt/type-graph.rakutest +++ b/xt/type-graph.rakutest @@ -2,7 +2,8 @@ use Test; use Doc::TypeGraph; -use Telemetry; + +use Telemetry; # pull in optional classes we can test my $t = Doc::TypeGraph.new-from-file('type-graph.txt');