root/t/deprecated-syntax.pod

=head1 NAME

Deprecated Syntax

=head1 SYNOPSIS

This document tries summarized common mistakes in the test suite. If you
help refactoring the suite, or write new tests, read this document first.

=head1 DEPRECATED SYNTAX

=head2 Old POD

Old POD looks like this:

    =head1 heading
    ...
    =cut

The new POD looks like this:

    =begin stuff
    ...
    =end stuff

All new files, and all below C<t/spec/> should follow the new conventions.

=head2 Array indexes with negative numbers

The Perl 5 style negative array indexes C<@array[-1]> are spelled
C<@array[*-1]> in Perl 6.

=head2 pos()

C<pos> is dead. C<$/.to> is the replacement.

=head2 length()

C<length> is gone. Hashes should use C<keys>, C<values>, or the hash in numeric
context. For arrays, you want C<elems> or the array in numeric context. For
strings, you want one of C<chars>, C<graphs>, C<codes>, or C<bytes>.

=head2 try takes a statement

C<try> is followed by a statement, so

  is try { $operation }, 'foo', '$operation worked'

is parsed as
  
  is try( { $operation }, 'foo', '$operation worked')

which means only one argument to C<is()>, but three to C<try>. So don't use
this if it's not what you want. This is wrongly used in the test suite right
now in multiple places.

=head2 Interpolation in test descritions

    lives_ok({ $a := $b }, "can bind $b to $a";

is certainly not what you want; remeber that variables in double quoted
strings are interpolated, and use single quotes as string delimiters where
appropriate.

=head2 Special Pugs variables

Some tests rely on C<$?PUGS_BACKEND> and similar variables. Since they are not
specced, they cause failures on other implementations. Either remove these
variables alltogether, or fudge them by prepending C<#?pugs emit> on every
such line.

=head2 "my" in pointy block signatures

C<<for @list -> my $x >> is wrong, no need for a C<my> here. The current test
suite seems clear of that error.

=head2 dies_ok for tests that can fail at compile time

C<dies_ok> should only be used for tests that have to fail at run time. For
example non-existant subs are no such case. Always bare in mind that a clever
compiler might do some type inference and prove that there always will be an
error, and throw it at compile time.

If in doubt, use C<eval_dies_ok> instead. If you have a case where C<dies_ok>
is fine, remeber to pass a code ref to it.

=head2 .perl isn't canonical

The C<perl> method (which does roughly the same as perl 5's Data::Dumper)
returns a string that, when evaluated, returns the same value as the original
one.

However it's result isn't guarantued to be of any canonical form, for example
C<Str.perl> might return any legal quoting syntax. Testing for the exact value
of C<$anything.perl> is most likely an error

=head2 Junctions are unordered

Junctions are unordered assemblies, and C<Junction.values> returns these
values in an arbitrary order, just like C<keys %hash> and the like. Don't rely
on that order.

=head2 A note on :todo<bug> and similar

Some tests (mostly outside of t/spec) look like this:

    is(foo(), bar(), 'testing whatever', :todo<bug>);

This form is a todo note for Pugs. Since this test suite is used by multiple
implementations, this should be replaced with a fudge command:

    #?pugs todo 'bug'
    is(foo(), bar(), 'testing whatever');

=cut