Merge pull request #1181 from perl6/language-section-examples2

Unify Language/ examples output style

Author: Altai-man

doc/Language/classtut.pod6

@@ -30,7 +30,7 @@ A default constructor allows the setting of attributes for the created object:
     # Create a new Rectangle from two Points
     my $r = Rectangle.new(lower => Point.new(x => 0, y => 0), upper => Point.new(x => 10, y => 10));
 
-    say $r.area(); # -> 100
+    say $r.area(); # OUTPUT: «100␤»
     =end code
 
 You can also provide your own construction and build
@@ -114,19 +114,19 @@ method.
 You can use C<.DEFINITE> method to find out if what you have is an instance
 or a type object:
 
-    say Int.DEFINITE; # False (type object)
-    say 426.DEFINITE; # True  (instance)
+    say Int.DEFINITE; # OUTPUT: «False␤» (type object)
+    say 426.DEFINITE; # OUTPUT: «True␤»  (instance)
 
     class Foo {};
-    say Foo.DEFINITE;     # False (type object)
-    say Foo.new.DEFINITE; # True  (instance)
+    say Foo.DEFINITE;     # OUTPUT: «False␤» (type object)
+    say Foo.new.DEFINITE; # OUTPUT: «True␤»  (instance)
 
 You can also use type smileys to only accept instances or type objects:
 
     multi foo (Int:U) { "It's a type object!" }
     multi foo (Int:D) { "It's an instance!"   }
-    say foo Int; # It's a type object!
-    say foo 42;  # It's an instance!
+    say foo Int; # OUTPUT: «It's a type object!␤»
+    say foo 42;  # OUTPUT: «It's an instance!␤»
 
 =head1 State
 
@@ -537,14 +537,14 @@ class overriding the C<Cook>'s C<cook> method.
         cookbooks => 'The Joy of Cooking',
         salary => 40000);
 
-    $cook.cook( 'pizza' ); # Cooking pizza
+    $cook.cook( 'pizza' ); # OUTPUT: «Cooking pizza␤»
 
     my $baker = Baker.new(
         utensils => 'self cleaning oven',
         cookbooks => "The Baker's Apprentice",
         salary => 50000);
 
-    $baker.cook('brioche'); # Baking a tasty brioche
+    $baker.cook('brioche'); # OUTPUT: «Baking a tasty brioche␤»
     =end code
 
 Because the dispatcher will see the C<cook> method on C<Baker> before it

doc/Language/concurrency.pod6

@@ -45,16 +45,18 @@ in a concurrent or asynchronous manner.
 
 =begin code
 my $p1 = Promise.new;
-say $p1.status;         # Planned;
+say $p1.status;         # OUTPUT: «Planned␤»
 $p1.keep('result');
-say $p1.status;         # Kept
-say $p1.result;         # result
+say $p1.status;         # OUTPUT: «Kept␤»
+say $p1.result;         # OUTPUT: «result␤»
                         # (since it has been kept, a result is available!)
 
 my $p2 = Promise.new;
 $p2.break('oh no');
-say $p2.status;         # Broken
-say $p2.result;         # dies with "oh no", because the promise has been broken
+say $p2.status;         # OUTPUT: «Broken␤»
+say $p2.result;         # dies, because the promise has been broken
+CATCH { default { say .^name, ': ', .Str } };
+# OUTPUT: «X::AdHoc+{X::Promise::Broken}: oh no␤»
 =end code
 
 Promises gain much of their power by being composable, for example by
@@ -65,7 +67,7 @@ chaining, usually by the L<then|/type/Promise#method_then> method:
         -> $v { say $v.result; "Second Result" }
     );
     $promise1.keep("First Result");
-    say $promise2.result;   # First Result \n Second Result
+    say $promise2.result;   # OUTPUT: «First Result␤Second Result␤»
 
 Here the L<then|/type/Promise#method_then> method schedules code to be
 executed when the first L<Promise> is kept or broken, itself returning
@@ -82,7 +84,7 @@ is illustrated with:
     my $promise2 = $promise1.then(-> $v { say "Handled but : "; say $v.result});
     $promise1.break("First Result");
     try $promise2.result;
-    say $promise2.cause;        # Handled but : \n First Result
+    say $promise2.cause;        # OUTPUT: «Handled but : ␤First Result␤»
 
 Here the C<break> will cause the code block of the C<then> to throw an
 exception when it calls the C<result> method on the original promise
@@ -110,7 +112,7 @@ for that:
     my $promise = Promise.start(
         { my $i = 0; for 1 .. 10 { $i += $_ }; $i}
     );
-    say $promise.result;    # 55
+    say $promise.result;    # OUTPUT: «55␤»
 
 Here the C<result> of the promise returned is the value returned from
 the code.  Similarly if the code fails (and the promise is thus broken),
@@ -152,7 +154,7 @@ the result of each:
         $i
     };
     my @result = await $p1, $p2;
-    say @result;            # 55 -55
+    say @result;            # OUTPUT: «[55 -55]␤»
 
 In addition to C<await>, two class methods combine several
 L<Promise> objects into a new promise: C<allof> returns a promise that
@@ -217,6 +219,8 @@ as the vow object is kept private, the status of the promise is safe:
     # Will throw an exception
     # "Access denied to keep/break this Promise; already vowed"
     $promise.keep;
+    CATCH { default { say .^name, ': ', .Str } };
+    # OUTPUT: «X::Promise::Vowed: Access denied to keep/break this Promise; already vowed␤»
 
 The methods that return a promise that will be kept or broken
 automatically such as C<in> or C<start> will do this, so it is not
@@ -421,7 +425,7 @@ and returns it, blocking until a new item is sent if the queue is empty:
 
     my $channel = Channel.new;
     $channel.send('Channel One');
-    say $channel.receive;  # 'Channel One'
+    say $channel.receive;  # OUTPUT: «Channel One␤»
 
 If the channel has been closed with the L<method
 close|/type/Channel#method_close> then any C<send> will cause the
@@ -758,7 +762,7 @@ at a time:
         }
     }
 
-    say $a; # 10
+    say $a; # OUTPUT: «10␤»
 
 C<protect> returns whatever the code block returns.
 

doc/Language/containers.pod6

@@ -52,7 +52,7 @@ Note that subroutine signatures allow passing around of containers:
     }
     my $x = 42;
     f($x);
-    say $x;         # 23
+    say $x;         # OUTPUT: «23␤»
 
 Inside the subroutine, the lexpad entry for C<$a> points to the same
 container that C<$x> points to outside the subroutine. Which is why
@@ -63,7 +63,7 @@ Likewise a routine can return a container if it is marked as C<is rw>:
     my $x = 23;
     sub f() is rw { $x };
     f() = 42;
-    say $x;         # 42
+    say $x;         # OUTPUT: «42␤»
 
 For explicit returns, C<return-rw> instead of C<return> must be used.
 
@@ -84,16 +84,16 @@ Scalar containers are transparent to type checks and most kinds of read-only
 accesses. A C<.VAR> makes them visible:
 
     my $x = 42;
-    say $x.^name;       # Int
-    say $x.VAR.^name;   # Scalar
+    say $x.^name;       # OUTPUT: «Int␤»
+    say $x.VAR.^name;   # OUTPUT: «Scalar␤»
 
 And C<is rw> on a parameter requires the presence of a writable Scalar
 container:
 
     sub f($x is rw) { say $x };
     f 42;
     CATCH { default { say .^name, ': ', .Str } };
-    # OUTPUT«X::Parameter::RW: Parameter '$x' expected a writable container, but got Int value␤»
+    # OUTPUT: «X::Parameter::RW: Parameter '$x' expected a writable container, but got Int value␤»
 
 =head1 Binding
 
@@ -109,15 +109,15 @@ means that you cannot assign to it anymore:
     my $x := 42;
     $x = 23;
     CATCH { default { say .^name, ': ', .Str } };
-    # OUTPUT«X::AdHoc: Cannot assign to an immutable value␤»
+    # OUTPUT: «X::AdHoc: Cannot assign to an immutable value␤»
 
 You can also bind variables to other variables:
 
     my $a = 0;
     my $b = 0;
     $a := $b;
     $b = 42;
-    say $a;         # 42
+    say $a;         # OUTPUT: «42␤»
 
 Here, after the initial binding, the lexpad entries for C<$a> and C<$b> both
 point to the same scalar container, so assigning to one variable also
@@ -132,32 +132,30 @@ Sigilless variables also bind by default and so do parameters with the trait C<i
     my $a = 42;
     my \b = $a;
     b++;
-    say $a;         # 43
+    say $a;         # OUTPUT: «43␤»
 
     sub f($c is raw) { $c++ }
     f($a);
-    say $a;         # 44
+    say $a;         # OUTPUT: «44␤»
 
 =head1 Scalar containers and listy things
 
 There are a number of positional container types with slightly different
 semantics in Perl 6. The most basic one is L<List|/type/List>
 It is created by the comma operator.
 
-    say (1, 2, 3).^name;    # List
+    say (1, 2, 3).^name;    # OUTPUT: «List␤»
 
 A list is immutable, which means you cannot change the number of elements
 in a list. But if one of the elements happens to be a scalar container,
 you can still assign to it:
 
     my $x = 42;
     ($x, 1, 2)[0] = 23;
-    say $x;                 # 23
-    ($x, 1, 2)[1] = 23;     # Error: Cannot modify an immutable value
+    say $x;                 # OUTPUT: «23␤»
+    ($x, 1, 2)[1] = 23;     # Cannot modify an immutable value
     CATCH { default { say .^name, ': ', .Str } };
-    # OUTPUT:
-    # 23
-    # X::Assignment::RO: Cannot modify an immutable Int
+    # OUTPUT: «X::Assignment::RO: Cannot modify an immutable Int␤»
 
 So the list doesn't care about whether its elements are values or
 containers, they just store and retrieve whatever was given to them.
@@ -170,7 +168,7 @@ be containers, which means that you can always assign to elements:
 
     my @a = 1, 2, 3;
     @a[0] = 42;
-    say @a;         # 42 2 3
+    say @a;         # OUTPUT: «[42 2 3]␤»
 
 C<@a> actually stores three scalar containers. C<@a[0]> returns one of
 them, and the assignment operator replaces the integer value stored in that
@@ -186,8 +184,8 @@ the same thing: discard the old value(s), and enter some new value(s).
 
 Nevertheless, it's easy to observe how different they are:
 
-    my $x = 42; say $x.^name;   # Int
-    my @a = 42; say @a.^name;   # Array
+    my $x = 42; say $x.^name;   # OUTPUT: «Int␤»
+    my @a = 42; say @a.^name;   # OUTPUT: «Array␤»
 
 This is because the C<Scalar> container type hides itself well, but C<Array>
 makes no such effort. Also assignment to an array variable is coercive, so
@@ -196,7 +194,7 @@ you can assign a non-array value to an array variable.
 To place a non-C<Array> into an array variable, binding works:
 
     my @a := (1, 2, 3);
-    say @a.WHAT;                # (List)
+    say @a.WHAT;                # OUTPUT: «(List)␤»
 
 =head1 Binding to array elements
 
@@ -205,7 +203,7 @@ As a curious side note, Perl 6 supports binding to array elements:
     my @a = (1, 2, 3);
     @a[0] := my $x;
     $x = 42;
-    say @a;                     # 42 2 3
+    say @a;                     # OUTPUT: «[42 2 3]␤»
 
 If you've read and understood the previous explanations, it is now time to
 wonder how this can possibly work. After all, binding to a variable requires
@@ -229,7 +227,7 @@ counter-intuitive results when the array is used later.
     @a[2] = $b;          # ...but this is fine.
     @a[1, 2] := 1, 2;    # runtime error: X::Bind::Slice
     CATCH { default { say .^name, ': ', .Str } };
-    # OUTPUT«X::Bind::Slice: Cannot bind to Array slice␤»
+    # OUTPUT: «X::Bind::Slice: Cannot bind to Array slice␤»
 
 Operations that mix Lists and Arrays generally protect against such
 a thing happening accidentally.
@@ -249,23 +247,23 @@ do not flatten in list context:
 
     my @a = 1, 2, 3;
     my @b = @a, 4, 5;
-    say @b.elems;               # 3
+    say @b.elems;               # OUTPUT: «3␤»
 
 There are operations that flatten out sublists that are not inside a scalar
 container: slurpy parameters (C<*@a>) and explicit calls to C<flat>:
 
 
     my @a = 1, 2, 3;
-    say (flat @a, 4, 5).elems;  # 5
+    say (flat @a, 4, 5).elems;  # OUTPUT: «5␤»
 
     sub f(*@x) { @x.elems };
-    say f @a, 4, 5;             # 5
+    say f @a, 4, 5;             # OUTPUT: «5␤»
 
 As hinted above, scalar containers prevent that flattening:
 
     sub f(*@x) { @x.elems };
     my @a = 1, 2, 3;
-    say f $@a, 4, 5;            # 3
+    say f $@a, 4, 5;            # OUTPUT: «3␤»
 
 The C<@> character can also be used as a prefix to remove a scalar container:
 
@@ -289,15 +287,15 @@ user to L<handle|/type/Promise#method_in> timeouts.
     my @a;
     @a[0] = @a;
     put @a.perl;
-    # OUTPUT«(my \Array_54878224 = [Array_54878224,])␤»
+    # OUTPUT: «(my \Array_54878224 = [Array_54878224,])»
 
 =head1 Type Constraints
 
 Any container can have a type constraint in form of a L<type object|/language/typesystem#Type_objects> or a L<subset|/language/typesystem#subset>. Both can be place between a declarator and the variable name or after the trait L<of|/type/Variable#trait_is_dynamic>. The constraint is a property of the container, not the variable. Any (re-)binding may change the type constraint or remove the constraint altogether if bound to a value instead of a container. Introspection of type constraints on containers is provided by C<.VAR.of>.
 
     EVAL ‚my $i = 42; say $i.VAR.of; $i := "forty plus two"; say $i.VAR.of;‘;
     CATCH { default { say .^name, ' ', .Str } }
-    # OUTPUT«(Mu)␤X::Method::NotFound No such method 'of' for invocant of type 'Str'␤»
+    # OUTPUT: «(Mu)␤X::Method::NotFound No such method 'of' for invocant of type 'Str'␤»
 
 
 =head1 Custom containers
@@ -322,9 +320,9 @@ work with types in Perl 6.
     }
 
     my Int $a := lucky(Int);
-    say $a = 12;
+    say $a = 12;    # OUTPUT: «12␤»
     say $a = 'FOO'; # X::TypeCheck::Binding
-    say $a = 13; # X::OutOfRange
-    CATCH { default { say .^name, ': ', .Str; .resume } };
+    say $a = 13;    # X::OutOfRange
+    CATCH { default { say .^name, ': ', .Str } };
 
 =end pod