Test doc/Language/haskell-to-p6.pod6 examples

Closes #1199

Author: coke

doc/Language/haskell-to-p6.pod6

@@ -20,64 +20,81 @@ Haskell background.
 
 In Haskell, you have type level programming and then value level programming.
 
+    =begin code :skip-test
     plusTwo :: Integer -> Integer   -- Types
     plusTwo x = x + 2               -- Values
+    =end code
 
 You do not mix types and values in Haskell like the below
 
+    =begin code :skip-test
     plusTwo 2          -- This is valid
     plusTwo Integer    -- This is not valid
+    =end code
 
 In Perl6, types (AKA type objects) live on the same level as values
 
+    =begin code
     sub plus-two(Int $x --> Int) { $x + 2 }
 
-    plus-two(2)    # This is valid
-    plus-two(Int)  # This is valid
+    plus-two(2);    # This is valid
+    plus-two(Int);  # This is valid
+    =end code
 
 I will illustrate this unique aspect of Perl6 with one more example:
 
+    =begin code
     multi sub is-string(Str $ --> True) {}
     multi sub is-string(Any $ --> False) {}
 
-    is-string('hello')    #True
-    is-string(4)          #False
+    is-string('hello');    #True
+    is-string(4);          #False
+    =end code
 
 =head2 Maybe
 
 In Haskell, you have a Maybe type that allows you to forgo the worry of null types.
 Let's say you have a hypothetical function that parses a String to an Integer:
 
+    =begin code :skip-test
     parseInt :: String -> Maybe Integer
 
     case parseInt myString of
       Just x  -> x
       Nothing -> 0
+    =end code
 
 In Perl6, since type objects coexist with regular objects, we have the concept of Defined
 and Undefined objects. Plain type objects are undefined while instantiated objects are defined.
 
+    =begin code
     sub parse-int(Str $s --> Int) { ... }
 
+    my $string = {...};
     given parse-int($string) {
       when Int:D { $_ }
       when Int:U { 0 }
     }
+    =end code
 
 So in Perl6 we have type constraints that indicate the definedness of a type. These are
 
-    Int:D # This is a defined Int.
-    Int:U # This is an undefined Int, AKA a type object
-    Int:_ # This is either defined or undefined.
+    =begin code
+    Int:D; # This is a defined Int.
+    Int:U; # This is an undefined Int, AKA a type object
+    Int:_; # This is either defined or undefined.
+    =end code
 
 If we wanted to be explicit in the above example (probably a good idea), we could add
 the C<:_> constraint on the return type. This would let the user know that they should account
 for both defined and undefined return values. We could also use other methods and constructs
 that specifically test for definedness.
 
+    =begin code
     sub parse-int(Str $s --> Int:_) { ... }
 
     # One way to do it
+    my $string = {...};
     given parse-int($string) {
       when Int:D { $_ }
       when Int:U { 0 }
@@ -93,17 +110,23 @@ that specifically test for definedness.
 
     # With the defined-or operator
     parse-int($string) // 0
+    =end code
 
 The C<with> operator that you see above is like C<if>, except it explicitly tests for definedness and then
 passes the result to the following block. Similarly, C<without> tests that the object is undefined and also
 passes the result to the following block.
 
 For more natural control flow with undefined and defined types, Perl6 introduces C<andthen> and C<orelse>.
 
+    =begin code
+    sub parse-int(Str $s --> Int:_) { ... }
+
+    my $string = {...};
     my $result = parse-int($string) orelse 0;
 
     sub hello() { say 'hi' }
     hello() andthen say 'bye';
+    =end code
 
 TODO: include a better example for andthen that makes sense. Maybe using promise objects?
 
@@ -117,32 +140,39 @@ object and return a new object, you can certainly do so.
 
 Here is a Haskell code example:
 
+    =begin code :skip-test
     data Point = Point x y
 
     moveUp :: Point -> Point
     moveUp (Point x y) = Point x (y + 1)
+    =end code
 
 And an equivalent Perl6 example:
 
+    =begin code
     class Point { has $.x; has $.y; }
 
     sub move-up(Point $p --> Point) {
       Point.new(x => $p.x, y => $p.y + 1)
     }
+    =end code
 
 The code I illustrated above is an example of a Product Type. If instead you'd like to
 write a Sum Type, there is not an exact equivalent in Perl6. The closest thing would be
 an Enum.
 
+    =begin code :skip-test
     data Animal = Dog | Cat | Bird | Horse
 
     testAnimal :: Animal -> String
     testAnimal Dog   = "Woof"
     testAnimal Horse = "Neigh"
+    =end code
 
 A Perl6 Enum does not fit the same exact use cases, but it can be used in putting
 constraints on types.
 
+    =begin code
     enum Animal < Dog Cat Bird Horse >;
 
     proto sub test-animal( Animal        ) {*}
@@ -151,25 +181,31 @@ constraints on types.
 
     say test-animal Animal::Dog; # more explicit
     say test-animal Horse;
+    =end code
 
 =head2 Type Aliases and Subsets
 
 In Haskell, you can alias an existing type to simply increase clarity of intent and re-use
 existing types.
 
+    =begin code :skip-test
     type Name = String
 
     fullName :: Name -> Name -> Name
     fullName first last = first ++ last
+    =end code
 
 The equivalent in Perl6 is the following.
 
+    =begin code
     my constant Name = Str;
 
     sub full-name ( Name \first, Name \last --> Name ) { first ~ last }
+    =end code
 
 It should be noted that in Perl6, one can also create a subset of an existing type.
 
+    =begin code :skip-test
     subset Name of Str where *.chars < 20;
 
     sub full-name(Name $first, Name $last) {
@@ -178,6 +214,7 @@ It should be noted that in Perl6, one can also create a subset of an existing ty
 
     full-name("12345678901234567890111", "Smith") # This does not compile, as the first parameter
                                                   # doesn't fit the Name type
+    =end code
 
 =head2 Typeclasses
 
@@ -193,26 +230,32 @@ explain how Perl6 roles compare to Haskell typeclasses
 
 Haskell makes heavy use of pattern matching in function definitions.
 
+    =begin code :skip-test
     greeting :: String -> String
     greeting  ""   = "Hello, World!"
     greeting "bub" = "Hey bub."
     greeting  name = "Hello, " ++ name ++ "!"
+    =end code
 
 Perl6 does this as well! You just use the C<multi> keyword to signify that it is a multiple dispatch
 function.
 
+    =begin code
     proto greeting ( Str   --> Str ) {*}
     multi greeting ( ""    --> "Hello, World!" ) {}
     multi greeting ( "bub" --> "Hey bub." ) {}
     multi greeting ( \name ) { "Hello, " ~ name ~ "!" }
+    =end code
 
 The C<proto> declarator is not necessary, but can sometimes aid in making sure that all multis
 follow your business rules. Using a variable name in the signature of the proto would provide
 more information in error messages, and for introspection.
 
+    =begin code
     proto greeting ( Str \name --> Str ) {*}
 
     say &greeting.signature;                  # (Str \name --> Str)
+    =end code
 
 An interesting thing to note in the Perl6 code above is that passing values like C<'bub'> as a
 function parameter is just syntax sugar for a C<where> guard.
@@ -222,6 +265,7 @@ function parameter is just syntax sugar for a C<where> guard.
 Using the example from the "Pattern Matching" section of this page, you can see the guards that are
 used behind the scenes to constrain our function arguments.
 
+    =begin code
     multi greeting ( ""    --> "Hello, World!" ) {}
     multi greeting ( "bub" --> "Hey bub." ) {}
 
@@ -234,6 +278,7 @@ used behind the scenes to constrain our function arguments.
 
     multi greeting(Str \name where $_ ~~ ''   ) {'Hello, World!'}
     multi greeting(Str \name where $_ ~~ 'bub') {'Hey bub.'}
+    =end code
 
 C<$_> is known as the topic variable. It assumes the form of whatever is appropriate. The smart match
 operator C<~~> figures out the best way to determine if the left matches the right, be it number ranges,
@@ -242,25 +287,29 @@ strings, etc. Our three examples above go from most sugared (top), to least suga
 The bottom examples above could be wrapped in curly braces, making it more obvious that it is a code
 block. Note that a where clause may also take an explicit Callable.
 
+    =begin code :skip-test
     multi greeting(Str \name where { $_ ~~ '' } ) {'Hello, World!'}
 
     multi greeting(Str \name where -> $thing { $thing ~~ '' } ) {'Hello, World!'}
 
     multi greeting ( Str \name where { Bool.pick } --> 'True' ){}
 
     multi greeting ( Str \name where &some-subroutine ){…}
+    =end code
 
 If you read the section in this page on subsets, you'll notice that "where" is used in the making of
 subsets as well as here. The usage of "where" in both areas is exactly the same.
 
 When using C<where>, note that the order of definition is important, just like in Haskell.
 
+    =begin code
     multi greeting ( Str \name where '' --> 'Hello, World!' ){}
     multi greeting ( Str \name where { Bool.pick } --> 'True' ){}
     multi greeting ( Str \name where 'bub' --> 'Hey, bub.' ){}
 
     say greeting ''   ; # will never say True
     say greeting 'bub'; # about 50% of the time it will say True
+    =end code
 
 =Argument Deconstruction
 
@@ -284,20 +333,25 @@ show function composition operator. Maybe explain a more perl6ish way to do this
 
 Haskell makes heavy use of case matching like the below:
 
+    =begin code :skip-test
     case number of
       2 -> "two"
       4 -> "four"
       8 -> "eight"
       _ -> "don't care"
+    =end code
 
 In Perl6 you can achieve this same thing with the given/when structure:
 
+    =begin code
+    my $number = {...};
     given $number {
       when 2  { "two" }
       when 4  { "four" }
       when 8  { "eight" }
       default { "don't care" }
     }
+    =end code
 
 Note that the order of the C<when>'s is also significant, just like with the C<where>'s in the
 guard section of this page.
@@ -319,22 +373,31 @@ TODO compare haskell list comprehensions to Perl6 gather/take
 
 Fold in Haskell is called Reduce in Perl6.
 
+    =begin code :skip-test
     mySum = foldl `+` 0 numList
+    =end code
 
+    =begin code
+    my @numbers = {...};
     reduce { $^a + $^b }, 0, |@numbers;
     @numbers.reduce({$^a + $^b}, with => 0)
+    =end code
 
 However, in Perl6, if you want to use an infix operator (+ - / % etc) there is a nice little
 helper called the Reduction Metaoperator.
 
+    =begin code
+    my @numbers = {...};
     [+] @numbers    # This is the same
     [+] 0, @numbers # as this
+    =end code
 
 It inserts the operator in between all values in the list and produces a result, just like Fold.
 
 In Haskell you, you have foldl and foldr. In Perl6, this difference is determined by the
 associativity attached to the operator/subroutine.
 
+    =begin code
     sub two-elem-list ( \a, \b ) { ( a, b ) }
 
     # you can use a subroutine as an infix operator
@@ -355,6 +418,7 @@ associativity attached to the operator/subroutine.
     # chaining
     say [<] 1..5;            # True
     say (1..5).reduce: &[<]; # True
+    =end code
 
 =head2 Map
 
@@ -364,28 +428,36 @@ TODO
 
 Haskell and Perl6 both allow you to specify ranges of values.
 
+    =begin code :skip-test
     myRange1 = 10..100
     myRange2 = 1..        -- Infinite
     myRange3 = 'a'..'h'   -- Letters work too
+    =end code
 
-    my $range1 = 10..100
-    my $range2 = 1..*      # Infinite
-    my $range3 = 'a'..'h'  # Letters work too
+    =begin code
+    my $range1 = 10..100;
+    my $range2 = 1..*;      # Infinite
+    my $range3 = 'a'..'h';  # Letters work too
+    =end code
 
 =head2 Laziness vs Eagerness
 
 In the examples above, you have the concept of laziness displayed very plainly. Perl6 has laziness
 only where it makes the most sense. For example, in the range 10..100, this is eager because it has
 a definite end. If a list does not have a definite end, then the list should clearly be lazy.
 
+    =begin code
     (1 .. 100).is-lazy; # False
     (1 .. Inf).is-lazy; # True
+    =end code
 
 These are the "sane defaults" that Perl6 takes pride in. But they are still defaults and can be
 changed into one or the other.
 
+    =begin code
     (1 .. 100).lazy.is-lazy;       # True
     (1 .. 100).lazy.eager.is-lazy; # False
+    =end code
 
 =head1 Contexts (let-in / where)
 

xt/examples-compilation.t

@@ -23,7 +23,6 @@ if @*ARGS {
             | 'Language/5to6-perlop.p6'
             | 'Language/5to6-perlsyn.p6'
             | 'Language/5to6-perlvar.p6'
-            | 'Language/haskell-to-p6.p6'
             | 'Language/modules.p6'
             | 'Language/nativecall.p6'
             | 'Language/packages.p6'