Merge branch 'master' into coke/levenshtein

doc/Language/control.pod6

@@ -678,7 +678,7 @@ All these forms may produce a return value the same way C<loop> does.
 
 =head1 X<return|control flow>
 
-The routine C<return> will stop execution of a subroutine or method, run all
+The sub C<return> will stop execution of a subroutine or method, run all
 relevant L<phasers|/language/phasers#Block_Phasers> and provide the given
 return value to the caller. The default return value is C<Nil>. If a return
 L<type constraint|/type/Signature#Constraining_Return_Types> is provided it
@@ -687,11 +687,18 @@ exception L<X::TypeCheck::Return|/type/X::TypeCheck::Return> is thrown. If it
 passes a control exception is raised and can be caught with
 L<CONTROL|/language/phasers#CONTROL>.
 
+Any C<return> in a block is tied to the first C<Routine> in the outer lexical scope of
+that block, no matter how deeply nested.  Please note that a C<return> in the
+root of a package will fail at runtime. A C<return> in a block that is
+evaluated lazily (e.g. inside C<map>) may find the outer lexical routine gone
+by the time the block is executed. In almost any case C<last> is the better
+alternative.
+
 =comment TODO add link to section in /language/function that shows how return values are produces/handled
 
 =head1 X<return-rw|control flow>
 
-The routine C<return> will return values, not containers. Those are immutable
+The sub C<return> will return values, not containers. Those are immutable
 and will lead to runtime errors when attempted to be mutated.
 
     sub s(){ my $a = 41; return $a };

doc/Language/functions.pod6

@@ -454,6 +454,7 @@ Here C<return> does not just leave the block inside which it was called, but
 the whole routine. In general, blocks are transparent to C<return>, they
 attach to the outer routine.
 
+X<|use soft (pragma)>
 Routines can be inlined and as such provide an obstacle for wrapping. Use the
 pragma C<use soft;> to prevent inlining to allow wrapping at runtime.
 

doc/Language/grammars.pod6

@@ -137,7 +137,7 @@ name of the alternation is attached with C<< :sym<> >> adverb.
 In the actions class, we now got rid of the ternary operator and simply take
 the C<.made> value from the C<< $<calc-op> >> match object. And the actions for
 individual alternations now follow the same naming pattern as in the grammar:
-C<< method calc-op:sym<add> >> and C<method calc-op:sym<sub> >>.
+C<< method calc-op:sym<add> >> and C<<method calc-op:sym<sub> >>.
 
 The real beauty of this method can be seen when you subclass that grammar
 and actions class. Let's say we want to add a multiplication feature to the

doc/Language/ipc.pod6

@@ -77,7 +77,7 @@ ability to send signals to that program.
     await $done;
 
 Here is a small program that uses the "tail" program to print out the contents
-of the log named F<system.log> for 10 seconds and then tells the program to stop
+of the log named C<system.log> for 10 seconds and then tells the program to stop
 with a QUIT signal.
 
 Whereas C<Proc> provides access to output using C<IO::Handle>s, C<Proc::Async>

doc/Language/operators.pod6

@@ -654,7 +654,7 @@ class or role, even after it has been redefined in the child class.
 
 =head1 Autoincrement Precedence
 
-=head2 prefix C«++»
+=head2 prefix X<C«++»|++>
 
 =begin code :skip-test
 multi sub prefix:<++>($x is rw) is assoc<non>
@@ -670,7 +670,7 @@ It works by calling the L<succ> method (for I<successor>) on its argument,
 which gives custom types the freedom to implement their own increment
 semantics.
 
-=head2 prefix C«--»
+=head2 prefix X<C«--»|-->
 
 =begin code :skip-test
 multi sub prefix:<-->($x is rw) is assoc<non>
@@ -687,7 +687,7 @@ which gives custom types the freedom to implement their own decrement
 semantics.
 
 
-=head2 postfix C«++»
+=head2 postfix X<C«++»|++>
 
 =begin code :skip-test
 multi sub postfix:<++>($x is rw) is assoc<non>

doc/Language/performance.pod6

@@ -47,7 +47,40 @@ To learn how to interpret the profile info, ask questions on channel.
 =head2 Profile locally
 
 When using the L<MoarVM|http://moarvm.org> backend the L<Rakudo|http://rakudo.org> compiler's C<--profile>
-command line option writes profile information as an HTML file.
+command line option writes profile information as an HTML file. However, if the profile is too big it can
+be slow to open in a browser. In that case, if you use the C<--profile-filename=file.extension> option with
+an extension of C<.json>, you can use the L<Qt viewer|https://github.com/tadzik/p6profiler-qt> on the resulting
+JSON file.
+
+Another option (especially useful for profiles too big even for the Qt viewer) is to use an extension of C<.sql>.
+This will write the profile data as a series of SQL statements, suitable for opening in SQLite.
+
+    # create a profile
+    perl6 --profile --profile-filename=demo.sql -e 'say (^20).combinations(3).elems'
+
+    # create a SQLite database
+    sqlite3 demo.sql
+
+    # load the profile data
+    sqlite> .read demo.sql
+
+    # the query below is equivalent to the default view of the "Routines" tab in the HTML file
+    sqlite> select
+       ...>   case when r.name = "" then "<anon>" else r.name end,
+       ...>   r.file,
+       ...>   r.line,
+       ...>   sum(entries) as entries,
+       ...>   sum(case when rec_depth = 0 then inclusive_time else 0 end) as inclusive_time,
+       ...>   sum(exclusive_time) as exclusive_time
+       ...> from
+       ...>   callees c,
+       ...>   routines r
+       ...> where
+       ...>   c.id = r.id
+       ...> group by
+       ...>   c.id
+       ...> order by
+       ...>   inclusive_time desc;
 
 To learn how to interpret the profile info, use the C<prof-m: your code goes here> evalbot (explained
 above) and ask questions on channel.

doc/Language/pragmas.pod6

@@ -28,13 +28,13 @@ not yet rendered properly.
 
 =item X<B<MONKEY-GUTS>|MONKEY-GUTS> [NYI]
 
-=item X<B<MONKEY-SEE-NO-EVAL>|MONKEY-SEE-NO-EVAL> L<EVAL|https://docs.perl6.org/routine/EVAL>
+=item X<B<MONKEY-SEE-NO-EVAL>|MONKEY-SEE-NO-EVAL> L<EVAL|/routine/EVAL>
 
 =item X<B<MONKEY-SHINE>|MONKEY-SHINE> [NYI]
 
 =item X<B<MONKEY-TRAP>|MONKEY-TRAP> [NYI]
 
-=item X<B<MONKEY-TYPING>|MONKEY-TYPING> L<augment|https://docs.perl6.org/syntax/augment>
+=item X<B<MONKEY-TYPING>|MONKEY-TYPING> L<augment|/syntax/augment>
 
 =item X<B<MONKEY-WRENCH>|MONKEY-WRENCH> [NYI]
 
@@ -46,7 +46,7 @@ not yet rendered properly.
 
 =item X<B<invocant>|invocant> [NYI]
 
-=item X<B<lib>|lib> L<Finding Modules|https://docs.perl6.org/language/modules#Finding_Modules>
+=item X<B<lib>|lib> L<Finding Modules|/language/modules#Finding_Modules>
 
 =item X<B<newline>|newline> [TBD]
 
@@ -56,16 +56,16 @@ not yet rendered properly.
 
 =item X<B<precompilation>|precompilation> [TBD]
 
-=item X<B<soft>|soft> L<Re-dispatching|https://docs.perl6.org/language/functions#Re-dispatching>
+=item X<B<soft>|soft> L<Re-dispatching|/language/functions#Re-dispatching>, L<inlining|/language/functions#index-entry-use_soft_(pragma)>
 
 =item X<B<strict>|strict> [TBD]
 
 =item X<B<trace>|trace> [TBD]
 
-=item X<B<v6>|v6> L<Writing Tests|https://docs.perl6.org/language/testing#Writing_tests>
+=item X<B<v6>|v6> L<Writing Tests|/language/testing#Writing_tests>
 
 =item X<B<variables>|variables>
- L<Defined Variables Pragma|https://docs.perl6.org/language/variables#Default_Defined_Variables_Pragma>
+ L<Defined Variables Pragma|/language/variables#Default_Defined_Variables_Pragma>
 
 =item X<B<worries>|worries> [TBD]
 

doc/Language/regexes.pod6

@@ -74,7 +74,7 @@ otherwise it is L<Nil|/type/Nil>.
 
 =head1 Wildcards and character classes
 
-=head2 X<Dot to match any character|regex,.>
+=head2 X<Dot to match any character: C<.>|regex,.>
 
 An unescaped dot C<.> in a regex matches any single character.
 
@@ -195,18 +195,25 @@ Predefined subrules:
     <punct>            Punctuation and Symbols (only Punct beyond ASCII)
     <space>   \s       Whitespace
     <upper>   <:Lu>    Uppercase characters
-    <wb>               Word Boundary (zero-width assertion)
+    <|wb>               Word Boundary (zero-width assertion)
     <ww>               Within Word (zero-width assertion)
     <xdigit>           Hexadecimal digit [0-9A-Fa-f]
 
 =head2 X«Unicode properties|regex,<:property>»
 
 The character classes so far are mostly for convenience; a more systematic
 approach is the use of Unicode properties. They are called in the form C<<
-<:property> >>, where C<property> can be a short or long Unicode property
-name.
+<:property> >>, where C<property> can be a short or long Unicode General
+Category name. These use pair syntax.
 
-The following list is stolen from the Perl 5
+To match against a specific value for a Unicode Property:
+
+    "a".uniprop('Script') # Latin
+    "a" ~~ / <:Script<Latin>> /
+    "a".uniprop('Block') # Basic Latin
+    "a" ~~ / <:Block('Basic Latin')> /
+
+The following list of Unicode General Categories is stolen from the Perl 5
 L<perlunicode|http://perldoc.perl.org/perlunicode.html> documentation:
 
 =begin table
@@ -334,7 +341,7 @@ Quantifiers bind tighter than concatenation, so C<ab+> matches one C<a>
 followed by one or more C<b>s. This is different for quotes, so C<'ab'+>
 matches the strings C<ab>, C<abab>, C<ababab> etc.
 
-=head2 X<One or more: +|regex,+>
+=head2 X<One or more: C<+>|regex,+>
 
 The C<+> quantifier makes the preceding atom match one or more times, with
 no upper limit.
@@ -344,7 +351,7 @@ like this:
 
     / \w+ '=' \w+ /
 
-=head2 X<Zero or more: *|regex,*>
+=head2 X<Zero or more: C<*>|regex,*>
 
 The C<*> quantifier makes the preceding atom match zero or more times, with
 no upper limit.
@@ -353,11 +360,11 @@ For example to allow optional whitespace between C<a> and C<b> you can write
 
     / a \s* b /
 
-=head2 X<Zero or one match: ?|regex,?>
+=head2 X<Zero or one match: C<?>|regex,?>
 
 The C<?> quantifier makes the preceding atom match zero or once.
 
-=head2 X<General quantifier: ** min..max|regex quantifier,**>
+=head2 X<General quantifier: C<** min..max>|regex quantifier,**>
 
 To quantify an atom an arbitrary number of times, you can write e.g.
 C<a ** 2..5> to match the character C<a> at least twice and at most 5 times.
@@ -393,15 +400,15 @@ or a Whatever operator for an infinite range with a non inclusive minimum:
 say so 'aaaa' ~~ /a ** 1^..*/;    # True
 =end code
 
-=head2 X<Modified quantifier: %|regex,%;regex,%%>
+=head2 X<Modified quantifier: C<%>|regex,%;regex,%%>
 
 To more easily match things like comma separated values, you can tack on a
 C<%> modifier to any of the above quantifiers to specify a separator that must
 occur between each of the matches.  So, for example C<a+ % ','> will match
 C<a> or C<a,a> or C<a,a,a> or so on, but it will not match C<a,> or C<a,a,>.
 To match those as well, you may use C<%%> instead of C<%>.
 
-=head2 X<Greedy versus frugal quantifiers: ?|regex,?>
+=head2 X<Greedy versus frugal quantifiers: C<?>|regex,?>
 
 By default, quantifiers request a greedy match:
 
@@ -418,7 +425,7 @@ matching:
 
 You can also explicitly request greedy matching with the C<!> modifier.
 
-=head2 X<Preventing backtracking: :|regex,:>
+=head2 X<Preventing backtracking: C<:>|regex,:>
 
 You can prevent backtracking in regexes by attaching a C<:> modifier
 to the quantifier:
@@ -428,7 +435,7 @@ say so 'abababa' ~~ /a .* aba/;   # True
 say so 'abababa' ~~ /a .*: aba/;  # False
 =end code
 
-=head1 X<Alternation|regex,||>
+=head1 X<Alternation: C<||>|regex,||>
 
 To match one of several possible alternatives, separate them by C<||>; the
 first matching alternative wins.
@@ -449,7 +456,7 @@ non-whitespace characters, followed by zero or more spaces, followed by the
 equals sign C<=>, followed again by optional whitespace, followed by another
 string of non-whitespace characters.
 
-=head1 X<Longest Alternation|regex,|>
+=head1 X<Longest Alternation: C<|>|regex,|>
 
 In regexes branches separated by C<|>, the longest match wins, independent of
 the lexical ordering in the regexes.
@@ -539,6 +546,14 @@ say so $str ~~ / scan $$/;        # False (there is a . between "scan"
 say so $str ~~ / '."' $$/;        # True  (at the last line)
 =end code
 
+
+=head2 X«C«<|w>» and C«<!|w>», word boundary|regex, <|w>;regex, <!|w>»
+
+If you want to match any word boundary you can use C«<|w>». This is similar to other
+languages’ X«C<\b>|regex deprecated,\b».
+To match not a word boundary, use <!|w>, similar to other languages X<C<\B>|regex deprecated, \B >.
+These are both zero width assertions.
+
 =head2 X<<<<C<<< << >>> and C<<< >> >>>, left and right word boundary|regex,<<;regex,>>;regex,«;regex,»>>>>
 
 C<<< << >>> matches a left word boundary: it matches positions where there
@@ -707,6 +722,11 @@ all named captures:
 
 There is a more convenient way to get named captures which is discussed in
 the section on Subrules.
+=head2 X«Capture markers: C«<( )>»|regex,<( )>»
+
+A C«<(» token indicates the start of the match's overall capture, while the corresponding C«)>»
+token indicates its endpoint. The C«<(» is similar to other languages X<\K|regex deprecated,\K> to discard any matches
+found before the C<\K>.
 
 =head1 Substitution
 

doc/Language/testing.pod6

@@ -361,10 +361,10 @@ tested independently, and the C<is-approx> test will succeed only if both pass.
 
 =item X<is-deeply($value, $expected, $description?)|is-deeply>
 
-Marks a test as passed if C<$value> and C<$expected> compare positively with
-the L<eqv operator|/routine/eqv>. This is the best way to check for equality of
-(deep) data structures. The function accepts an optional C<$description> of
-the test.
+Marks a test as passed if C<$value> and C<$expected> are equivalent, using the
+same semantics as the L<eqv operator|/routine/eqv>. This is the best way to
+check for equality of (deep) data structures. The function accepts an optional
+C<$description> of the test.
 
 =begin code
 use v6;

doc/Language/typesystem.pod6

@@ -611,7 +611,8 @@ All keys have to be of the same type.
     dd Mass.enums; # OUTPUT«{:g(1.0), :kg(1000.0), :mg(0.001)}␤»
 
 If no value is given C<Int> will be assumed as the values type and incremented
-by one per key starting at zero.
+by one per key starting at zero. As enum key types C<Int>, C<Num>, C<Rat> and
+C<Str> are supported.
 
     enum Numbers <one two three four>;
     dd Numbers.enums; # OUTPUT«{:four(3), :one(0), :three(2), :two(1)}␤»

doc/Language/unicode_texas.pod6

@@ -83,9 +83,9 @@ equivalents] that have a special meaning in Perl 6.
   ⁻      |  U+207B   | -          | v6.c  | (must use explicit number) as part of exponentiation
   ¯      |  U+00AF   | -          | v6.c  | (must use explicit number) as part of exponentiation (macron is an alternative way of writing a minus)
   ⁰      |  U+2070   | **0        | v6.c  | can be combined with ⁰..⁹
-  ¹      |  U+2071   | **1        | v6.c  | can be combined with ⁰..⁹
-  ²      |  U+2072   | **2        | v6.c  | can be combined with ⁰..⁹
-  ³      |  U+2073   | **3        | v6.c  | can be combined with ⁰..⁹
+  ¹      |  U+00B9   | **1        | v6.c  | can be combined with ⁰..⁹
+  ²      |  U+00B2   | **2        | v6.c  | can be combined with ⁰..⁹
+  ³      |  U+00B3   | **3        | v6.c  | can be combined with ⁰..⁹
   ⁴      |  U+2074   | **4        | v6.c  | can be combined with ⁰..⁹
   ⁵      |  U+2075   | **5        | v6.c  | can be combined with ⁰..⁹
   ⁶      |  U+2076   | **6        | v6.c  | can be combined with ⁰..⁹

doc/Type/Cool.pod6

@@ -941,9 +941,9 @@ Checks if the given integer codepoint or the first letter of the string given ha
 equal to the value you give. If you supply the Unicode property to be checked it will only return True
 if that property matches the given value.
 
-    say unimatch 'A', 'Latin' # True
-    say unimatch 'A', 'Latin', 'Script' # True
-    say unimatch 'A', 'Ll' #True
+    say unimatch 'A', 'Latin'; # True
+    say unimatch 'A', 'Latin', 'Script'; # True
+    say unimatch 'A', 'Ll'; # True
 
 =head2 routine chop
 

doc/Type/IO/Path.pod6

@@ -252,9 +252,13 @@ Returns C<Bool::True> if the invocant is a path and the file exists.
 
 =head2 method s
 
-    method s(--> Bool)
+    method s(--> Int)
 
-Returns C<Bool::True> if the invocant is a path and the size is bigger then 0.
+If the path is valid and points to a regular file the size of that file
+in bytes is returned. If the path is valid but pointing to something which
+is not a file, e.g. a directory, a L<X::IO::NotAFile> exception is thrown.
+An exception is also thrown if the path is invalid, in that case the exception
+type is L<X::IO::DoesNotExist>.
 
 =head2 method l