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 various VTABLE functions [eligible in 1.5]
  62
  63 The get_bigint, set_bigint_*, pow, i_pow and nextkey_keyed VTABLE functions are
  64 deprecated and will be removed.
  65
  66 L<https://trac.parrot.org/parrot/ticket/866>
  67
  68 =item Use of undocumented variables in class_init [eligible in 2.1]
  69
  70 The current implementation allows the class_init vtable function body to
  71 use local symbols from the generated part. For example, some PMC used
  72 to use the pass counter. In the future, the class_init body from the PMC
  73 file may not be inserted directly in the body of the generated one,
  74 so this usage will not be allowed.
  75
  76 L<https://trac.parrot.org/parrot/ticket/918>
  77
  78 =item Overriding vtable invoke in PIR objects [experimental]
  79
  80 The VTABLE invoke in object.pmc puts SELF at the start of the
  81 signature call arguments when there is no current object and is
  82 not already here. This allows the usage of $P0() instead of $P0($P0).
  83
  84 L<https://trac.parrot.org/parrot/ticket/103>
  85
  86 =item All bitwise VTABLE functions [eligible in 2.1]
  87
  88 All bitwise VTABLE functions (all VTABLE functions containing C<bitwise> in
  89 their names) will be removed.  Equivalent functionality will by supplied by
  90 bitwise dynops.
  91
  92 L<https://trac.parrot.org/parrot/ticket/1260>
  93
  94 =back
  95
  96 =head1 Opcodes
  97
  98 =over 4
  99
 100 =item moved to dynop [eligible in 1.1]
 101
 102 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
 103 (the obscure and rarely used parts), sys.ops.
 104
 105 L<https://trac.parrot.org/parrot/ticket/449>
 106
 107 =item get_addr and set_addr [eligible in 1.5]
 108
 109 L<https://trac.parrot.org/parrot/ticket/218>
 110
 111 These opcodes are being repurposed. They will always return a unique memory
 112 address of the PMC. Uses of get_addr and set_addr that would set label values
 113 for Sub, Exception, and related PMC types will instead be handled by
 114 get_label and set_label.
 115
 116 =item All bitwise ops [eligible in 2.1]
 117
 118 All bitwise ops (all ops containing C<bitwise> in their names) will be provided
 119 by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
 120 equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
 121 etc) have switched to using them.
 122
 123 L<https://trac.parrot.org/parrot/ticket/1260>
 124
 125 =back
 126
 127 =head1 Bytecode
 128
 129 =over 4
 130
 131 =item packfile structure [eligible in 1.1]
 132
 133 L<https://trac.parrot.org/parrot/ticket/451>
 134
 135 =item opcode numbering [eligible in 1.1]
 136
 137 L<https://trac.parrot.org/parrot/ticket/451>
 138
 139 =item PMC numbering [eligible in 1.1]
 140
 141 L<https://trac.parrot.org/parrot/ticket/451>
 142
 143 =back
 144
 145 =head1 Class Features
 146
 147 [Nothing at this time.]
 148
 149 =head1 Debugger
 150
 151 Assigning to registers [experimental]
 152
 153 =head1 PIR syntax
 154
 155 =over 4
 156
 157 =item Assignment syntax with opcodes [eligible in 1.1]
 158
 159 L<https://trac.parrot.org/parrot/ticket/906>
 160
 161 =item named class/pmc lookup in pir syntax such as new, isa, subclass,
 162     get_class, etc [eligible in 1.1]
 163
 164 Class PMC name resolution will be the following.
 165
 166 if the arg is a STRING
 167   Relative to the current Namespace
 168
 169 if the arg is a Array (of any sort) or Key
 170   Relative to the current HLL Namespace
 171
 172 if the arg is a Namespace or Class PMC
 173   The passed in class or the class attatched to the passed in namespace.
 174
 175 L<https://trac.parrot.org/parrot/ticket/159>
 176
 177 =item load or include paths prefixed with 'library/' or 'include/'
 178 [eligible in 1.5]
 179
 180 L<https://trac.parrot.org/parrot/ticket/511>
 181
 182 =item continuation-based ExceptionHandlers [eligible in 2.1]
 183
 184 L<https://trac.parrot.org/parrot/ticket/1091>
 185
 186 =item implicit optional named parameters [eligible in 2.1]
 187
 188 L<https://trac.parrot.org/parrot/ticket/1103>
 189
 190 =back
 191
 192 =head1 Functions
 193
 194 =over 4
 195
 196 =item mmd_cvt_to_types [eligible in 1.1]
 197
 198 L<https://trac.parrot.org/parrot/ticket/907>
 199
 200 =item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]
 201
 202 Subs marked with C<:vtable> or C<:method> flags are no longer given a
 203 namespace entry by default.  Use the C<:nsentry> flag to cause this
 204 to happen.
 205
 206 L<http://rt.perl.org/rt3/Ticket/Display.html?id=53302>
 207
 208 =item C API coding standards cleanup [eligible in 1.1]
 209
 210 All C API functions that aren't currently named according to the
 211 'Parrot_<system>_*' scheme will be renamed. If you depend on these
 212 functions in an extending/embedding interface or C-level custom PMCs,
 213 check in 1.4 or 2.0 for the new names.
 214
 215 L<https://trac.parrot.org/parrot/ticket/443>
 216
 217 =item Sub/method invocation functions [eligible in 2.1]
 218
 219 The old 'Parrot_call_*' functions for invoking a sub/method object from C are
 220 deprecated, replaced by 'Parrot_ext_call'.
 221
 222 L<https://trac.parrot.org/parrot/ticket/1145>
 223
 224 =item PMC Attributes Allocation Functions [experimental]
 225
 226  Parrot_gc_allocate_pmc_attributes
 227  Parrot_gc_free_pmc_attributes
 228
 229 These items and related helper functions are added as experimental support
 230 for TT #895
 231
 232 =item PDB_compile and PDB_eval [eligible in 2.1]
 233
 234 The function PDB_compile doesn't work since some time, and his implementation
 235 was a hack. His functionality may be reimplemented in another way. Until the
 236 end of deprecation cycle it just throws an excpetion.
 237
 238 The PDB_eval function, that used in the debugger to support the eval
 239 command, was using PDB_compile. His functionality must be reimplemented
 240 in another way and with a name that follows current conventions, in the
 241 meantime and until the end of the deprecation cycle it just shows a
 242 diagnostic message.
 243
 244 L<https://trac.parrot.org/parrot/ticket/872>
 245
 246 =item Parrot_oo_get_namespace [eligible in 2.1]
 247
 248 L<https://trac.parrot.org/parrot/ticket/1069>
 249
 250 =back
 251
 252 =head1 Compiler tools
 253
 254 =head2 PASM1 compiler
 255
 256 =over 4
 257
 258 =item C<PASM1 compiler> [eligible in 2.1]
 259
 260 See PDB_compile. Note that the current version of the C<PASM1> compiler
 261 issues a warning and is not functional. (However, it used to segfault.)
 262
 263 =back
 264
 265 =head2 Parrot Grammar Engine (PGE)
 266
 267 =over 4
 268
 269 =item Action methods in rules
 270
 271 Per Synopsis 5, all regexes will have an implied {*} token at the
 272 end which cause invocation of an action method if a C<:action>
 273 object is supplied.
 274
 275 L<https://trac.parrot.org/parrot/ticket/843>
 276
 277 =back
 278
 279 =head2 Parrot Compiler Toolkit
 280
 281 =over 4
 282
 283 =item PCT::HLLCompiler stages [eligible in 1.1]
 284
 285 The interface of various methods for adding, removing, and modifying
 286 the list stages in a PCT::HLLCompiler object is subject to change.
 287 The existing actual stages will remain; only the mechanism for specifying
 288 the order of individual stages is likely to change.
 289
 290 L<https://trac.parrot.org/parrot/ticket/462>
 291
 292 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 293
 294 In order to facilitate using PCT::HLLCompiler with test harnesses,
 295 the C<command_line> method of PCT::HLLCompiler object exits silently
 296 if it detects that it is being run in a sample run from Perl's
 297 Test::Harness.  Currently this detection is done by checking the
 298 second command line argument for "@INC"; future releases may
 299 use a different detection mechanism or eliminate it altogether.
 300
 301 L<https://trac.parrot.org/parrot/ticket/463>
 302
 303 =item PAST::Val node generation [eligible in 1.5]
 304
 305 The PAST::Compiler may generate the code for PAST::Val nodes
 306 (i.e., constants) at the beginning of the block (Parrot sub) instead
 307 of the location where they occur in the PAST tree.
 308
 309 L<https://trac.parrot.org/parrot/ticket/868>
 310
 311 =back
 312
 313 =head2 Not Quite Perl (NQP)
 314
 315 =over 4
 316
 317 =item C< $(...) > syntax  [eligible in 1.5]
 318
 319 The C< $(...) > syntax for obtaining a result object from a Match
 320 object will no longer work.  The new syntax is to invoke the
 321 C<.ast> method on the Match object.
 322
 323 L<https://trac.parrot.org/parrot/ticket/459>
 324
 325 =item Quoted items [eligible in 1.5]
 326
 327 Double-quoted strings will interpret unescaped $-names
 328 as interpolated variables in the string.  Bare slashes
 329 will introduce regular expressions.  The C<< <foo bar> >>
 330 syntax will produce an array of strings instead of a single
 331 string.
 332
 333 L<https://trac.parrot.org/parrot/ticket/837>
 334
 335 =item C<< PIR q:to:<xyz> >> inline PIR [eligible in 1.5]
 336
 337 The C<< PIR q:to:<xyz> >> form of inline PIR in NQP scripts is
 338 deprecated.  Use C< Q:PIR { ... } >  or C< Q:PIR {{ ... }} >
 339 instead.
 340
 341 L<https://trac.parrot.org/parrot/ticket/842>
 342
 343 =back
 344
 345 =head1 build tools
 346
 347 =over 4
 348
 349 =item tools/build/dynoplibs.pl and tools/build/dynpmc.pl [eligible in 1.1]
 350
 351 Replaced with makefiles.
 352
 353 L<https://trac.parrot.org/parrot/ticket/338>
 354
 355 =back
 356
 357 =head1 Parrot library
 358
 359 =over 4
 360
 361 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 362
 363 L<https://trac.parrot.org/parrot/ticket/508>
 364
 365 =item Cross-HLL library loading [experimental]
 366
 367 L<https://trac.parrot.org/parrot/ticket/754>
 368
 369 =item OpenGL bindings and libraries [experimental]
 370
 371 L<https://trac.parrot.org/parrot/ticket/852>
 372
 373 =back
 374
 375 =head1 Footnotes
 376
 377 =over 4
 378
 379 =item 1
 380
 381 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 382
 383 Older tickets may be listed at L<RT|https://rt.perl.org/rt3>.
 384
 385 =item 2
 386
 387 For an item to be considered experimental, it can B<never> have shipped in
 388 a stable release without the C<[experimental]> tag; otherwise, it must be
 389 deprecated normally before removal or incompatible change.
 390
 391 =back
 392
 393 =cut