Reflow, de-indentation and some corrections

Raku · Dec 4, 2018 · 931a2d2 · 931a2d2
1 parent c671af1
commit 931a2d2
Show file tree

Hide file tree

Showing 5 changed files with 99 additions and 81 deletions.
diff --git a/doc/Language/grammars.pod6 b/doc/Language/grammars.pod6
@@ -353,88 +353,95 @@ Here, text such as "use rules for significant whitespace by default" will only
 match if the state assigned by whether rules, tokens, or regexes are mentioned
 matches with the correct guard:
 
-    =begin code :preamble<grammar GrammarAdvice{};>
-    say GrammarAdvice.subparse("use rules for significant whitespace by default");
-    # OUTPUT: «use rules for significant whitespace by default»
+=begin code :preamble<grammar GrammarAdvice{};>
+say GrammarAdvice.subparse("use rules for significant whitespace by default");
+# OUTPUT: «use rules for significant whitespace by default»
 
-    say GrammarAdvice.subparse("use tokens for insignificant whitespace by default");
-    # OUTPUT: «use tokens for insignificant whitespace by default»
+say GrammarAdvice.subparse("use tokens for insignificant whitespace by default");
+# OUTPUT: «use tokens for insignificant whitespace by default»
 
-    say GrammarAdvice.subparse("use regexes for insignificant whitespace by default");
-    # OUTPUT: «use regexes for insignificant whitespace by default»
+say GrammarAdvice.subparse("use regexes for insignificant whitespace by default");
+# OUTPUT: «use regexes for insignificant whitespace by default»
 
-    say GrammarAdvice.subparse("use regexes for significant whitespace by default")
-    # OUTPUT: #<failed match>
-    =end code
+say GrammarAdvice.subparse("use regexes for significant whitespace by default")
+# OUTPUT: #<failed match>
+=end code
 
 =head2 Attributes in grammars
 
 Attributes may be defined in grammars. However, they can only be accessed by
-methods. Attempting to use them from within a token will throw an exception
-because tokens are methods of L<Cursor|/type/Cursor>, not of the grammar
-itself. Note that mutating an attribute from within a method called in a token
-will I<only modify the attribute for that token's own match object>! Grammar
-attributes can be accessed in the match returned after parsing if made public:
+methods; in effect, grammars are classes, so these attributes behave in much the
+same way as object attributes. Attempting to use them from within a token will
+throw an exception because tokens are methods of L<Cursor|/type/Cursor>, not of
+the grammar itself; C<Cursor>s, in effect, behave as instances of the class that
+is the grammar. Note that mutating an attribute from within a method called in a
+token will I<only modify the attribute for that token's own match object>!
+Grammar attributes can be accessed in the match returned after parsing if made
+public:
 
 =begin code
-    grammar HTTPRequest {
-        has Bool $.invalid;
-
-        token TOP {
-            <type> <path> 'HTTP/1.1' \r\n
-            [<field> \r\n]+
-            \r\n
-            $<body>=.*
-        }
-
-        token type {
-            | GET | POST | OPTIONS | HEAD | PUT | DELETE | TRACE | CONNECT
-            | \S+ <.error>
-        }
+grammar HTTPRequest {
+    has Bool $.invalid;
+
+    token TOP {
+        <type> <path> 'HTTP/1.1' \r\n
+        [<field> \r\n]+
+        \r\n
+        $<body>=.*
+    }
 
-        token path {
-            | '/' [[\w+]+ % \/] [\.\w+]?
-            | '*'
-            | \S+ <.error>
-        }
+    token type {
+        | GET | POST | OPTIONS | HEAD | PUT | DELETE | TRACE | CONNECT
+        | \S+ <.error>
+    }
 
-        token field {
-            | $<name>=\w+ : $<value>=<-[\r\n]>*
-            | <-[\r\n]>+ <.error>
-        }
+    token path {
+        | '/' [[\w+]+ % \/] [\.\w+]?
+        | '*'
+        | \S+ <.error>
+    }
 
-        method error(--> ::?CLASS:D) {
-            $!invalid = True;
-            self;
-        }
+    token field {
+        | $<name>=\w+ : $<value>=<-[\r\n]>*
+        | <-[\r\n]>+ <.error>
     }
 
-    my $header = "MEOWS / HTTP/1.1\r\nHost: docs.perl6.org\r\nsup lol\r\n\r\n";
-    my $/ = HTTPRequest.parse($header);
-    say $<type>.invalid;
-    # OUTPUT: True
-    say $<path>.invalid;
-    # OUTPUT: (Bool)
-    say $<field>».invalid;
-    # OUTPUT: [(Bool) True]
+    method error(--> ::?CLASS:D) {
+        $!invalid = True;
+        self;
+    }
+}
+
+my $header = "MEOWS / HTTP/1.1\r\nHost: docs.perl6.org\r\nsup lol\r\n\r\n";
+my $/ = HTTPRequest.parse($header);
+say $<type>.invalid;
+# OUTPUT: True
+say $<path>.invalid;
+# OUTPUT: (Bool)
+say $<field>».invalid;
+# OUTPUT: [(Bool) True]
 =end code
 
 =head2 Passing arguments into grammars
 
-To pass arguments into a grammar, you can use the named argument of C<:args> on any of the parsing methods of grammar. The arguments passed should be in a C<list>.
+To pass arguments into a grammar, you can use the named argument of C<:args> on
+any of the parsing methods of grammar. The arguments passed should be in a
+C<list>.
 
 =begin code
-    grammar demonstrate-arguments {
-        rule TOP ($word) {
-        "I like" $word
-        }
+grammar demonstrate-arguments {
+    rule TOP ($word) {
+    "I like" $word
     }
+}
 
-    # Notice the comma after "sweets" when passed to :args to coerce it to a list
-    say demonstrate-arguments.parse("I like sweets", :args(("sweets",))); # OUTPUT: «｢I like sweets｣␤»
+# Notice the comma after "sweets" when passed to :args to coerce it to a list
+say demonstrate-arguments.parse("I like sweets", :args(("sweets",)));
+# OUTPUT: «｢I like sweets｣␤»
 =end code
 
-Once the arguments are passed in, they can be used in a call to a named regex inside the grammar.
+Once the arguments are passed in, they can be used in a call to a named regex
+inside the grammar.
 
 =begin code
     grammar demonstrate-arguments-again {

diff --git a/doc/Type/Attribute.pod6 b/doc/Type/Attribute.pod6
@@ -24,7 +24,8 @@ The usual way to obtain an object of type C<Attribute> is by introspection:
     say $a.package;         # OUTPUT: «(Useless)␤»
     say $a.has_accessor;    # OUTPUT: «False␤»
 
-Modifying a private attribute from the outside is usually not possible, but since Attribute is at the level of the meta class, all is fair game
+Modifying a private attribute from the outside is usually not possible, but
+since Attribute is at the level of the meta class, all is fair game
 
 =begin code :preamble<class Useless { has @!things }; my $a>
 my $instance = Useless.new;

diff --git a/doc/Type/Cool.pod6 b/doc/Type/Cool.pod6
@@ -1478,7 +1478,7 @@ Furthermore, the C<EVAL> is evaluated in the current package:
     }
     say $M::answer;         # OUTPUT: «42␤»
 
-And also the current language, meaning any added syntax is available:
+And also in the current language, meaning any added syntax is available:
 
     sub infix:<mean>(*@a) is assoc<list> {
         @a.sum / @a.elems

diff --git a/doc/Type/Hash.pod6 b/doc/Type/Hash.pod6
@@ -35,10 +35,9 @@ Defined as:
     multi method classify-list(%mapper, *@list, :&as --> Hash:D)
     multi method classify-list(@mapper, *@list, :&as --> Hash:D)
 
-Populates a L«C<Hash>|/type/Hash» by classifying the
-possibly-empty C<@list> of values using the given C<mapper>, optionally
-altering the values using the C<:&as> L«C<Callable>|/type/Callable». The
-C<@list> cannot be lazy.
+Populates a L«C<Hash>|/type/Hash» by classifying the possibly-empty C<@list> of
+values using the given C<mapper>, optionally altering the values using the
+C<:&as> L«C<Callable>|/type/Callable». The C<@list> cannot be lazy.
 
 The mapper can be a L«C<Callable>|/type/Callable» that takes a single argument,
 an L«C<Associative>|/type/Associative», or an L«C<Iterable>|/type/Iterable».
@@ -50,16 +49,18 @@ return value will be used as the mapper's value.
 
 =head3 Simple classification
 
-In simple classification mode, each mapper's value is any non-Iterable and
+In simple classification mode, each mapper's value is any non-C<Iterable> and
 represents a key to classify C<@list>'s item under:
 
-    say % .classify-list: { $_ %% 2 ?? 'even' !! 'odd' }, ^10;
-    # OUTPUT: «{even => [0 2 4 6 8], odd => [1 3 5 7 9]}␤»
+=begin code
+say % .classify-list: { $_ %% 2 ?? 'even' !! 'odd' }, ^10;
+# OUTPUT: «{even => [0 2 4 6 8], odd => [1 3 5 7 9]}␤»
 
-    my @mapper = <zero one two three four five>;
-    my %hash = foo => 'bar';
-    say %hash.classify-list: @mapper, 1, 2, 3, 4, 4;
-    # OUTPUT: «{foo => bar, four => [4 4], one => [1], three => [3], two => [2]}␤»
+my @mapper = <zero one two three four five>;
+my %hash = foo => 'bar';
+say %hash.classify-list: @mapper, 1, 2, 3, 4, 4;
+# OUTPUT: «{foo => bar, four => [4 4], one => [1], three => [3], two => [2]}␤»
+=end code
 
 The mapper's value is used as the key of the L«C<Hash>|/type/Hash» to
 which the C<@list>'s item will be L«C<push>ed|/routine/push». See
@@ -90,10 +91,10 @@ C<@list>'s item under:
     #     }
     # }
 
-B<NOTE:> each of those L«C<Iterables>|/type/Iterable»
-must have the same number of elements, or the method will throw an exception.
-This restriction exists to avoid conflicts when the same key is a
-leaf of one value's classification but a node of another value's classification.
+B<NOTE:> each of those L«C<Iterables>|/type/Iterable»s must have the same number
+of elements, or the method will throw an exception. This restriction exists to
+avoid conflicts when the same key is a leaf of one value's classification but a
+node of another value's classification.
 
 =head3 C<:&as> value modifier
 

diff --git a/doc/Type/Test.pod6 b/doc/Type/Test.pod6
@@ -193,9 +193,18 @@ Defined as:
 
     multi sub is-approx(Numeric $got, Numeric $expected, $desc = '')
     multi sub is-approx(Numeric $got, Numeric $expected, Numeric $abs-tol,$desc = '')
-    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '', Numeric :$rel-tol is required)
-    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '', Numeric :$abs-tol is required)
-    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',Numeric :$rel-tol is required, Numeric :$abs-tol is required)
+    =for code
+    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
+                        Numeric :$rel-tol is required)
+
+    =for code
+    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
+                        Numeric :$abs-tol is required)
+
+    =for code
+    multi sub is-approx(Numeric $got, Numeric $expected, $desc = '',
+                        Numeric :$rel-tol is required,
+                        Numeric :$abs-tol is required)
 
 Marks a test as passed if the C<$value> and C<$expected> numerical values
 are approximately equal to each other. The subroutine can be called in numerous
@@ -240,9 +249,9 @@ than C<2>.
 
 =head3 Relative tolerance
 
-When a relative tolerance is set, the test checks the relative difference between
-values. Given the same tolerance, the larger the numbers given, the larger the
-value they can differ by can be.
+When a relative tolerance is set, the test checks the relative difference
+between values. Given the same tolerance, the larger the numbers given, the
+larger the value they can differ by can be.
 
 For example: