t/deprecated-syntax.pod

   1 =head1 NAME
   2
   3 Deprecated Syntax
   4
   5 =head1 SYNOPSIS
   6
   7 This document tries summarized common mistakes in the test suite. If you
   8 help refactoring the suite, or write new tests, read this document first.
   9
  10 =head1 DEPRECATED SYNTAX
  11
  12 =head2 Old POD
  13
  14 Old POD looks like this:
  15
  16     =head1 heading
  17     ...
  18     =cut
  19
  20 The new POD looks like this:
  21
  22     =begin stuff
  23     ...
  24     =end stuff
  25
  26 All new files, and all below C<t/spec/> should follow the new conventions.
  27
  28 =head2 Array indexes with negative numbers
  29
  30 The Perl 5 style negative array indexes C<@array[-1]> are spelled
  31 C<@array[*-1]> in Perl 6.
  32
  33 =head2 pos()
  34
  35 C<pos> is dead. C<$/.to> is the replacement.
  36
  37 =head2 length()
  38
  39 C<length> is gone. Hashes should use C<keys>, C<values>, or the hash in numeric
  40 context. For arrays, you want C<elems> or the array in numeric context. For
  41 strings, you want one of C<chars>, C<graphs>, C<codes>, or C<bytes>.
  42
  43 =head2 undef is dead
  44
  45 There is no C<undef> term anymore. For a scalar undef, use C<Any>, or C<Mu>
  46 if you know what you're doing and you think it's right. For an undefined value
  47 of a certain type just use its type object, so an undefined integer would just
  48 be C<Int>.
  49
  50 To test that something is not defined, use one of the alternations below,
  51 where the first three are preferred (because they use less advanced features):
  52
  53     ok !defined($something), 'description';
  54     ok !$something.defined,  'description';
  55     ok $somethiing.notdef,   'description';
  56     ok $something ~~ *.notdef,  'description';
  57
  58 =head2 Special Pugs variables
  59
  60 Some tests rely on C<$?PUGS_BACKEND> and similar variables. Since they are not
  61 specced, they cause failures on other implementations. Either remove these
  62 variables altogether, or fudge them by prepending C<#?pugs emit> on every
  63 such line.
  64
  65 =head2 eval_dies_ok for tests that can fail at compile time
  66
  67 C<dies_ok> should only be used for tests that have to fail at run time. For
  68 example non-existent subs are no such case. Always bare in mind that a clever
  69 compiler might do some type inference and prove that there always will be an
  70 error, and throw it at compile time.
  71
  72 If in doubt, use C<eval_dies_ok> instead. If you have a case where C<dies_ok>
  73 is fine, remember to pass a code ref to it.
  74
  75 =head2 .perl isn't canonical
  76
  77 The C<perl> method (which does roughly the same as perl 5's Data::Dumper)
  78 returns a string that, when evaluated, returns the same value as the original
  79 one (but put in item context).
  80
  81 However it's result isn't guaranteed to be of any canonical form, for example
  82 C<Str.perl> might return any legal quoting syntax. Testing for the exact value
  83 of C<$anything.perl> is most likely an error
  84
  85 =head2 Type constraints on containers
  86
  87 Use type constraints only where they are needed to test what you want to test.
  88 Especially be aware that C<my Int @a> declares an Array of Int values, and by
  89 the same token C<my Array @a> actually declares an Array of Arrays. Most of
  90 the time that's not what you want. The same goes for variables with the C<%>
  91 and C<&> sigil: an additional type constraint acts on the values (or the
  92 return value in case of C<&>).
  93
  94 =head2 Junction.values is deprecated
  95
  96 Calling C<.values> on a junction ordinarily autothreads, calling C<.values> on
  97 each eigenstate.
  98
  99 =head2 A note on :todo<bug> and similar
 100
 101 Some tests (mostly outside of t/spec) look like this:
 102
 103     is(foo(), bar(), 'testing whatever', :todo<bug>);
 104
 105 This form is a todo note for Pugs. Since this test suite is used by multiple
 106 implementations, this should be replaced with a fudge command:
 107
 108     #?pugs todo 'bug'
 109     is(foo(), bar(), 'testing whatever');
 110
 111 =cut
 112
 113 # vim: spell spelllang=en_us