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