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