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