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