DEPRECATED.pod

   1 # $Id$
   2
   3 =head1 Purpose
   4
   5 Provide a list of deprecated and experimental items in parrot.
   6 All items in this list should have a corresponding Trac ticket[1].
   7
   8 =head1 Experimental Status
   9
  10 These features are not considered stable, even though they may
  11 have shipped in a stable release of parrot[2]. Use them at your own
  12 risk, as they can be removed or changed in any release. These
  13 items are marked below with C<[experimental]>.
  14
  15 =head1 Deprecated Status
  16
  17 Please see F<docs/project/support_policy.pod> for the parrot
  18 project's policy regarding deprecated features.
  19
  20 Each item shows the first release in which it is eligible for removal, e.g.
  21 C<[eligible in 1.5]>.  If the release listed is one that has already
  22 shipped, this feature may be removed in B<any> upcoming release, and
  23 you should no longer rely on it.
  24
  25 Whenever deprecated items are removed, information
  26 regarding how to cope with the removal will be added to
  27 L<https://trac.parrot.org/parrot/wiki/Deprecation>.
  28
  29 When running parrot, you can receive warnings about deprecated opcodes.
  30 Either run parrot with the C<-w> option to enable all warnings, or
  31 specifically by including this C<PIR> code:
  32
  33  .include 'warnings.pasm'
  34  warningson .PARROT_WARNINGS_DEPRECATED_FLAG
  35
  36 =head1 PMCS
  37
  38 =over 4
  39
  40 =item moved to dynpmc [eligible in 1.1]
  41
  42 AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
  43 and Timer.
  44
  45 L<https://trac.parrot.org/parrot/ticket/448>
  46
  47 =item multiple dispatch within core PMCs [eligible in 1.1]
  48
  49 L<https://trac.parrot.org/parrot/ticket/452>
  50
  51 =item Hash changes to AssociativePMCArray [eligible in 1.5]
  52
  53 Also OrderedHash to OrderedAssociativePMCArray.
  54
  55 L<https://trac.parrot.org/parrot/ticket/679>
  56
  57 =item Method stdhandle in ParrotInterpreter [experimental]
  58
  59 L<https://trac.parrot.org/parrot/ticket/264>
  60
  61 =item VTABLE nomenclature. [eligible in 1.5]
  62
  63 Current list of VTABLE functions will be reviewed and cleaned.
  64
  65 L<https://trac.parrot.org/parrot/ticket/866>
  66
  67 =back
  68
  69 =head1 Opcodes
  70
  71 =over 4
  72
  73 =item moved to dynop [eligible in 1.1]
  74
  75 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
  76 (the obscure and rarely used parts), sys.ops.
  77
  78 L<https://trac.parrot.org/parrot/ticket/449>
  79
  80 =item get_addr and set_addr [eligible in 1.5]
  81
  82 L<https://trac.parrot.org/parrot/ticket/218>
  83
  84 These opcodes are being repurposed. They will always return a unique memory
  85 address of the PMC. Uses of get_addr and set_addr that would set label values
  86 for Sub, Exception, and related PMC types will instead be handled by
  87 get_label and set_label.
  88
  89 =back
  90
  91 =head1 Bytecode
  92
  93 =over 4
  94
  95 =item packfile structure [eligible in 1.1]
  96
  97 L<https://trac.parrot.org/parrot/ticket/451>
  98
  99 =item opcode numbering [eligible in 1.1]
 100
 101 L<https://trac.parrot.org/parrot/ticket/451>
 102
 103 =item PMC numbering [eligible in 1.1]
 104
 105 L<https://trac.parrot.org/parrot/ticket/451>
 106
 107 =back
 108
 109 =head1 Class Features
 110
 111 [Nothing at this time.]
 112
 113 =head1 Debugger
 114
 115 Assigning to registers [experimental]
 116
 117 =head1 PIR syntax
 118
 119 =over 4
 120
 121 =item Assignment syntax with opcodes [eligible in 1.1]
 122
 123 L<https://trac.parrot.org/parrot/ticket/906>
 124
 125 =item named class/pmc lookup in pir syntax such as new, isa, subclass,
 126     get_class, etc [eligible in 1.1]
 127
 128 Class PMC name resolution will be the following.
 129
 130 if the arg is a STRING
 131   Relative to the current Namespace
 132
 133 if the arg is a Array (of any sort) or Key
 134   Relative to the current HLL Namespace
 135
 136 if the arg is a Namespace or Class PMC
 137   The passed in class or the class attatched to the passed in namespace.
 138
 139 L<https://trac.parrot.org/parrot/ticket/159>
 140
 141 =item load or include paths prefixed with 'library/' or 'include/'
 142 [eligible in 1.5]
 143
 144 L<https://trac.parrot.org/parrot/ticket/511>
 145
 146 =back
 147
 148 =head1 Functions
 149
 150 =over 4
 151
 152 =item mmd_cvt_to_types [eligible in 1.1]
 153
 154 L<http://rt.perl.org/rt3/Ticket/Display.html?id=60626>
 155
 156 =item src/pic.c and src/pic_jit.c [eligible in 1.1]
 157
 158 These two files were a thin prototype implementation of Polymorphic Inline
 159 Caching that only ever applied to 4 opcodes, one of which has now been removed.
 160 The files (and all functions in them) are deprecated, and will be removed.
 161
 162 L<http://rt.perl.org/rt3/Ticket/Display.html?id=60048>
 163
 164 =item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]
 165
 166 Subs marked with C<:vtable> or C<:method> flags are no longer given a
 167 namespace entry by default.  Use the C<:nsentry> flag to cause this
 168 to happen.
 169
 170 L<http://rt.perl.org/rt3/Ticket/Display.html?id=53302>
 171
 172 =item C API coding standards cleanup [eligible in 1.1]
 173
 174 All C API functions that aren't currently named according to the
 175 'Parrot_<system>_*' scheme will be renamed. If you depend on these
 176 functions in an extending/embedding interface or C-level custom PMCs,
 177 check in 1.4 or 2.0 for the new names.
 178
 179 L<https://trac.parrot.org/parrot/ticket/443>
 180
 181 =item PMC Attributes Allocation Functions [experimental]
 182
 183  Parrot_gc_allocate_pmc_attributes
 184  Parrot_gc_free_pmc_attributes
 185
 186 These items and related helper functions are added as experimental support
 187 for TT #895
 188
 189 =item PDB_compile and PDB_eval [eligible in 2.1]
 190
 191 The function PDB_compile doesn't work since some time, and his implementation
 192 was a hack. His functionality may be reimplemented in another way. Until the
 193 end of deprecation cycle it just throws an excpetion.
 194
 195 The PDB_eval function, that used in the debugger to support the eval
 196 command, was using PDB_compile. His functionality must be reimplemented
 197 in another way and with a name that follows current conventions, in the
 198 meantime and until the end of the deprecation cycle it just shows a
 199 diagnostic message.
 200
 201 L<https://trac.parrot.org/parrot/ticket/872>
 202
 203 =back
 204
 205 =head1 Compiler tools
 206
 207 =head2 PASM1 compiler
 208
 209 =over 4
 210
 211 =item C<PASM1 compiler> [eligible in 2.1]
 212
 213 See PDB_compile. Note that the current version of the C<PASM1> compiler
 214 issues a warning and is not functional. (However, it used to segfault.)
 215
 216 =back
 217
 218 =head2 Parrot Grammar Engine (PGE)
 219
 220 =over 4
 221
 222 =item Action methods in rules
 223
 224 Per Synopsis 5, all regexes will have an implied {*} token at the
 225 end which cause invocation of an action method if a C<:action>
 226 object is supplied.
 227
 228 L<https://trac.parrot.org/parrot/ticket/843>
 229
 230 =back
 231
 232 =head2 Parrot Compiler Toolkit
 233
 234 =over 4
 235
 236 =item PCT::HLLCompiler stages [eligible in 1.1]
 237
 238 The interface of various methods for adding, removing, and modifying
 239 the list stages in a PCT::HLLCompiler object is subject to change.
 240 The existing actual stages will remain; only the mechanism for specifying
 241 the order of individual stages is likely to change.
 242
 243 L<https://trac.parrot.org/parrot/ticket/462>
 244
 245 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 246
 247 In order to facilitate using PCT::HLLCompiler with test harnesses,
 248 the C<command_line> method of PCT::HLLCompiler object exits silently
 249 if it detects that it is being run in a sample run from Perl's
 250 Test::Harness.  Currently this detection is done by checking the
 251 second command line argument for "@INC"; future releases may
 252 use a different detection mechanism or eliminate it altogether.
 253
 254 L<https://trac.parrot.org/parrot/ticket/463>
 255
 256 =item PAST::Val node generation [eligible in 1.5]
 257
 258 The PAST::Compiler may generate the code for PAST::Val nodes
 259 (i.e., constants) at the beginning of the block (Parrot sub) instead
 260 of the location where they occur in the PAST tree.
 261
 262 L<https://trac.parrot.org/parrot/ticket/868>
 263
 264 =back
 265
 266 =head2 Not Quite Perl (NQP)
 267
 268 =over 4
 269
 270 =item C< $(...) > syntax  [eligible in 1.5]
 271
 272 The C< $(...) > syntax for obtaining a result object from a Match
 273 object will no longer work.  The new syntax is to invoke the
 274 C<.ast> method on the Match object.
 275
 276 L<https://trac.parrot.org/parrot/ticket/459>
 277
 278 =item Quoted items [eligible in 1.5]
 279
 280 Double-quoted strings will interpret unescaped $-names
 281 as interpolated variables in the string.  Bare slashes
 282 will introduce regular expressions.  The C<< <foo bar> >>
 283 syntax will produce an array of strings instead of a single
 284 string.
 285
 286 L<https://trac.parrot.org/parrot/ticket/837>
 287
 288 =item C<< PIR q:to:<xyz> >> inline PIR [eligible in 1.5]
 289
 290 The C<< PIR q:to:<xyz> >> form of inline PIR in NQP scripts is
 291 deprecated.  Use C< Q:PIR { ... } >  or C< Q:PIR {{ ... }} >
 292 instead.
 293
 294 L<https://trac.parrot.org/parrot/ticket/842>
 295
 296 =back
 297
 298 =head1 build tools
 299
 300 =over 4
 301
 302 =item tools/build/dynoplibs.pl and tools/build/dynpmc.pl [eligible in 1.1]
 303
 304 Replaced with makefiles.
 305
 306 L<https://trac.parrot.org/parrot/ticket/338>
 307
 308 =back
 309
 310 =head1 pmc2c syntax
 311
 312 =over 4
 313
 314 =item "pmclass" with name not matching file's basename [eligible in 1.5]
 315
 316 When foo.pmc contains a the line "pmclass bar", pmc2c generates a pmc_foo.h
 317 but tries to include pmc_bar.h.  This is a bug, but it's possible someone out
 318 there is using it.  This usage will result in a warning for now; after
 319 the 1.4 release, this warning will be upgraded to an error.
 320
 321 L<https://trac.parrot.org/parrot/ticket/665>
 322
 323 =back
 324
 325 =head1 Parrot library
 326
 327 =over 4
 328
 329 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 330
 331 L<https://trac.parrot.org/parrot/ticket/508>
 332
 333 =item Cross-HLL library loading [experimental]
 334
 335 L<https://trac.parrot.org/parrot/ticket/754>
 336
 337 =item OpenGL bindings and libraries [experimental]
 338
 339 L<https://trac.parrot.org/parrot/ticket/852>
 340
 341 =back
 342
 343 =head1 Footnotes
 344
 345 =over 4
 346
 347 =item 1
 348
 349 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 350
 351 Older tickets may be listed at L<RT|https://rt.perl.org/rt3>.
 352
 353 =item 2
 354
 355 For an item to be considered experimental, it can B<never> have shipped in
 356 a stable release without the C<[experimental]> tag; otherwise, it must be
 357 deprecated normally before removal or incompatible change.
 358
 359 =back
 360
 361 =cut