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 The visit_info structure and associated VTABLEs. [eligible in 2.1]
  79
  80 The current freeze/thaw implementation makes heavy use of the visit_info
  81 structure and the VTABLE interface attached to it. This structure will
  82 be replaced with a PMC of equivalent functionality and with a possibly
  83 similar interface. The freeze, thaw, and visit vtables of all PMCs should be
  84 updated to the provided interim API before this change is made.
  85
  86 L<https://trac.parrot.org/parrot/ticket/1305>
  87
  88 =item Overriding vtable invoke in PIR objects [experimental]
  89
  90 The VTABLE invoke in object.pmc puts SELF at the start of the
  91 signature call arguments when there is no current object and is
  92 not already here. This allows the usage of $P0() instead of $P0($P0).
  93
  94 L<https://trac.parrot.org/parrot/ticket/103>
  95
  96 =item All bitwise VTABLE functions [eligible in 2.1]
  97
  98 All bitwise VTABLE functions (all VTABLE functions containing C<bitwise> in
  99 their names) will be removed.  Equivalent functionality will by supplied by
 100 bitwise dynops.
 101
 102 L<https://trac.parrot.org/parrot/ticket/1260>
 103
 104 =item Array PMC [eligible in 2.1]
 105
 106 This PMC is old, ill-used and is superseded by other array-like PMCs.  Any code
 107 using this PMC should migrate to ResizablePMCArray or something more suitable.
 108
 109 L<https://trac.parrot.org/parrot/ticket/1303>
 110
 111 =item OrderedHash PMC [eligible in 2.1]
 112
 113 This PMC is old, haskish and will be reimplemented with some backward incompatible
 114 changes in semantic of handling removed elements.
 115
 116 L<https://trac.parrot.org/parrot/ticket/1403>
 117
 118 =item CPointer PMC [eligible in 2.1]
 119
 120 And all uses in the Parrot calling conventions.
 121
 122 L<https://trac.parrot.org/parrot/ticket/1407>
 123
 124 =back
 125
 126 =head1 Opcodes
 127
 128 =over 4
 129
 130 =item moved to dynop [eligible in 1.1]
 131
 132 Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
 133 (the obscure and rarely used parts), sys.ops.
 134
 135 L<https://trac.parrot.org/parrot/ticket/449>
 136
 137 =item get_addr and set_addr [eligible in 1.5]
 138
 139 L<https://trac.parrot.org/parrot/ticket/218>
 140
 141 These opcodes are being repurposed. They will always return a unique memory
 142 address of the PMC. Uses of get_addr and set_addr that would set label values
 143 for Sub, Exception, and related PMC types will instead be handled by
 144 get_label and set_label.
 145
 146 =item All bitwise ops [eligible in 2.1]
 147
 148 All bitwise ops (all ops containing C<bitwise> in their names) will be provided
 149 by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
 150 equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
 151 etc) have switched to using them.
 152
 153 L<https://trac.parrot.org/parrot/ticket/1260>
 154
 155 =item get_results opcode order and features [eligible in 2.1]
 156
 157 Move get_results to follow invoke.
 158
 159 L<https://trac.parrot.org/parrot/ticket/1405>
 160
 161 get_results no longer used to fetch exception object.
 162
 163 L<https://trac.parrot.org/parrot/ticket/1406>
 164
 165 =item dlfunc signatures [eligible in 2.1]
 166
 167 C<xv>-style signatures will no longer work. See PDD16 for details.
 168
 169 F<pdds/draft/pdd16_native_call.pod>
 170
 171 L<https://trac.parrot.org/parrot/ticket/1410>
 172
 173 =back
 174
 175 =head1 Bytecode
 176
 177 =over 4
 178
 179 =item packfile structure [eligible in 1.1]
 180
 181 L<https://trac.parrot.org/parrot/ticket/451>
 182
 183 =item opcode numbering [eligible in 1.1]
 184
 185 L<https://trac.parrot.org/parrot/ticket/451>
 186
 187 =item PMC numbering [eligible in 1.1]
 188
 189 L<https://trac.parrot.org/parrot/ticket/451>
 190
 191 =back
 192
 193 =head1 Class Features
 194
 195 [Nothing at this time.]
 196
 197 =head1 Debugger
 198
 199 Assigning to registers [experimental]
 200
 201 =head1 PIR syntax
 202
 203 =over 4
 204
 205 =item Assignment syntax with opcodes [eligible in 1.1]
 206
 207 L<https://trac.parrot.org/parrot/ticket/906>
 208
 209 =item named class/pmc lookup in pir syntax such as new, isa, subclass,
 210     get_class, etc [eligible in 1.1]
 211
 212 Class PMC name resolution will be the following.
 213
 214 if the arg is a STRING
 215   Relative to the current Namespace
 216
 217 if the arg is a Array (of any sort) or Key
 218   Relative to the current HLL Namespace
 219
 220 if the arg is a Namespace or Class PMC
 221   The passed in class or the class attached to the passed in namespace.
 222
 223 L<https://trac.parrot.org/parrot/ticket/159>
 224
 225 =item load or include paths prefixed with 'library/' or 'include/'
 226 [eligible in 1.5]
 227
 228 L<https://trac.parrot.org/parrot/ticket/511>
 229
 230 =item continuation-based ExceptionHandlers [eligible in 2.1]
 231
 232 L<https://trac.parrot.org/parrot/ticket/1091>
 233
 234 =item implicit optional named parameters [eligible in 2.1]
 235
 236 L<https://trac.parrot.org/parrot/ticket/1103>
 237
 238 =back
 239
 240 =head1 Functions
 241
 242 =over 4
 243
 244 =item mmd_cvt_to_types [eligible in 1.1]
 245
 246 L<https://trac.parrot.org/parrot/ticket/907>
 247
 248 =item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]
 249
 250 Subs marked with C<:vtable> or C<:method> flags are no longer given a
 251 namespace entry by default.  Use the C<:nsentry> flag to cause this
 252 to happen.
 253
 254 L<https://trac.parrot.org/parrot/ticket/389>
 255
 256 =item C API coding standards cleanup [eligible in 1.1]
 257
 258 All C API functions that aren't currently named according to the
 259 'Parrot_<system>_*' scheme will be renamed. If you depend on these
 260 functions in an extending/embedding interface or C-level custom PMCs,
 261 check in 1.4 or 2.0 for the new names.
 262
 263 L<https://trac.parrot.org/parrot/ticket/443>
 264
 265 =item Sub/method invocation functions [eligible in 2.1]
 266
 267 The old 'Parrot_call_*' functions for invoking a sub/method object from C are
 268 deprecated, replaced by 'Parrot_ext_call'.
 269
 270 L<https://trac.parrot.org/parrot/ticket/1145>
 271
 272 =item PMC Attributes Allocation Functions [experimental]
 273
 274  Parrot_gc_allocate_pmc_attributes
 275  Parrot_gc_free_pmc_attributes
 276
 277 These items and related helper functions are added as experimental support
 278 for TT #895
 279
 280 =item PDB_compile and PDB_eval [eligible in 2.1]
 281
 282 The function PDB_compile doesn't work since some time, and his implementation
 283 was a hack. His functionality may be reimplemented in another way. Until the
 284 end of deprecation cycle it just throws an exception.
 285
 286 The PDB_eval function, that used in the debugger to support the eval
 287 command, was using PDB_compile. His functionality must be reimplemented
 288 in another way and with a name that follows current conventions, in the
 289 meantime and until the end of the deprecation cycle it just shows a
 290 diagnostic message.
 291
 292 L<https://trac.parrot.org/parrot/ticket/872>
 293
 294 =item Parrot_oo_get_namespace [eligible in 2.1]
 295
 296 L<https://trac.parrot.org/parrot/ticket/1069>
 297
 298 =item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]
 299
 300 All STRING modification functions will return a STRING pointer; capture and use
 301 this rather than relying on in-place modification of an existing pointer.
 302
 303 =back
 304
 305 =head1 Compiler tools
 306
 307 =head2 PASM1 compiler
 308
 309 =over 4
 310
 311 =item C<PASM1 compiler> [eligible in 2.1]
 312
 313 See PDB_compile. Note that the current version of the C<PASM1> compiler
 314 issues a warning and is not functional. (However, it used to segfault.)
 315
 316 =back
 317
 318 =head2 Parrot Grammar Engine (PGE)
 319
 320 =over 4
 321
 322 =item Action methods in rules
 323
 324 Per Synopsis 5, all regexes will have an implied {*} token at the
 325 end which cause invocation of an action method if a C<:action>
 326 object is supplied.
 327
 328 L<https://trac.parrot.org/parrot/ticket/843>
 329
 330 =back
 331
 332 =head2 Parrot Compiler Toolkit
 333
 334 =over 4
 335
 336 =item PCT::HLLCompiler stages [eligible in 1.1]
 337
 338 The interface of various methods for adding, removing, and modifying
 339 the list stages in a PCT::HLLCompiler object is subject to change.
 340 The existing actual stages will remain; only the mechanism for specifying
 341 the order of individual stages is likely to change.
 342
 343 L<https://trac.parrot.org/parrot/ticket/462>
 344
 345 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 346
 347 In order to facilitate using PCT::HLLCompiler with test harnesses,
 348 the C<command_line> method of PCT::HLLCompiler object exits silently
 349 if it detects that it is being run in a sample run from Perl's
 350 Test::Harness.  Currently this detection is done by checking the
 351 second command line argument for "@INC"; future releases may
 352 use a different detection mechanism or eliminate it altogether.
 353
 354 L<https://trac.parrot.org/parrot/ticket/463>
 355
 356 =item PAST::Val node generation [eligible in 1.5]
 357
 358 The PAST::Compiler may generate the code for PAST::Val nodes
 359 (i.e., constants) at the beginning of the block (Parrot sub) instead
 360 of the location where they occur in the PAST tree.
 361
 362 L<https://trac.parrot.org/parrot/ticket/868>
 363
 364 =back
 365
 366 =head2 Not Quite Perl (NQP)
 367
 368 =over 4
 369
 370 =item C< $(...) > syntax  [eligible in 1.5]
 371
 372 The C< $(...) > syntax for obtaining a result object from a Match
 373 object will no longer work.  The new syntax is to invoke the
 374 C<.ast> method on the Match object.
 375
 376 L<https://trac.parrot.org/parrot/ticket/459>
 377
 378 =item Quoted items [eligible in 1.5]
 379
 380 Double-quoted strings will interpret unescaped $-names
 381 as interpolated variables in the string.  Bare slashes
 382 will introduce regular expressions.  The C<< <foo bar> >>
 383 syntax will produce an array of strings instead of a single
 384 string.
 385
 386 L<https://trac.parrot.org/parrot/ticket/837>
 387
 388 =item C<< PIR q:to:<xyz> >> inline PIR [eligible in 1.5]
 389
 390 The C<< PIR q:to:<xyz> >> form of inline PIR in NQP scripts is
 391 deprecated.  Use C< Q:PIR { ... } >  or C< Q:PIR {{ ... }} >
 392 instead.
 393
 394 L<https://trac.parrot.org/parrot/ticket/842>
 395
 396 =back
 397
 398 =head1 build tools
 399
 400 =over 4
 401
 402 =item tools/build/dynoplibs.pl and tools/build/dynpmc.pl [eligible in 1.1]
 403
 404 Replaced with makefiles.
 405
 406 L<https://trac.parrot.org/parrot/ticket/338>
 407
 408 =back
 409
 410 =head1 Parrot library
 411
 412 =over 4
 413
 414 =item MT19937 [eligible in 2.1]
 415
 416 L<https://trac.parrot.org/parrot/ticket/1278> - latest version now hosted
 417 at L<http://github.com/fperrad/parrot-MT19937>. After 2.0, users will have
 418 to install via C<plumage>.
 419
 420 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 421
 422 L<https://trac.parrot.org/parrot/ticket/508>
 423
 424 =item Cross-HLL library loading [experimental]
 425
 426 L<https://trac.parrot.org/parrot/ticket/754>
 427
 428 =item OpenGL bindings and libraries [experimental]
 429
 430 L<https://trac.parrot.org/parrot/ticket/852>
 431
 432 =item Library name changes [eligible in 2.1]
 433
 434 The use of C<::> a namespace separator is deprecated.  Core libraries will
 435 change to use multi-level keys instead.  For example, C<Getopt::Obj> will
 436 change to C<Getopt; Obj>.  Affected libraries include C<Data::Dumper>,
 437 C<Getopt::Obj>, C<Parrot::Coroutine>, C<SDL>, C<Test::Builder>,
 438 C<YAML::Dumper>, and C<PCRE::NCI>.
 439
 440 As well, anything under F<examples/> is subject to this change.
 441
 442 =back
 443
 444 =head1 Footnotes
 445
 446 =over 4
 447
 448 =item 1
 449
 450 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 451
 452 =item 2
 453
 454 For an item to be considered experimental, it can B<never> have shipped in
 455 a stable release without the C<[experimental]> tag; otherwise, it must be
 456 deprecated normally before removal or incompatible change.
 457
 458 =back
 459
 460 =cut