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 =back
 157
 158 =head1 Functions
 159
 160 =over 4
 161
 162 =item mmd_cvt_to_types [eligible in 1.1]
 163
 164 L<https://trac.parrot.org/parrot/ticket/907>
 165
 166 =item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]
 167
 168 Subs marked with C<:vtable> or C<:method> flags are no longer given a
 169 namespace entry by default.  Use the C<:nsentry> flag to cause this
 170 to happen.
 171
 172 L<http://rt.perl.org/rt3/Ticket/Display.html?id=53302>
 173
 174 =item C API coding standards cleanup [eligible in 1.1]
 175
 176 All C API functions that aren't currently named according to the
 177 'Parrot_<system>_*' scheme will be renamed. If you depend on these
 178 functions in an extending/embedding interface or C-level custom PMCs,
 179 check in 1.4 or 2.0 for the new names.
 180
 181 L<https://trac.parrot.org/parrot/ticket/443>
 182
 183 =item PMC Attributes Allocation Functions [experimental]
 184
 185  Parrot_gc_allocate_pmc_attributes
 186  Parrot_gc_free_pmc_attributes
 187
 188 These items and related helper functions are added as experimental support
 189 for TT #895
 190
 191 =item PDB_compile and PDB_eval [eligible in 2.1]
 192
 193 The function PDB_compile doesn't work since some time, and his implementation
 194 was a hack. His functionality may be reimplemented in another way. Until the
 195 end of deprecation cycle it just throws an excpetion.
 196
 197 The PDB_eval function, that used in the debugger to support the eval
 198 command, was using PDB_compile. His functionality must be reimplemented
 199 in another way and with a name that follows current conventions, in the
 200 meantime and until the end of the deprecation cycle it just shows a
 201 diagnostic message.
 202
 203 L<https://trac.parrot.org/parrot/ticket/872>
 204
 205 =item Parrot_oo_get_namespace [eligible in 2.1]
 206
 207 L<https://trac.parrot.org/parrot/ticket/1069>
 208
 209 =back
 210
 211 =head1 Compiler tools
 212
 213 =head2 PASM1 compiler
 214
 215 =over 4
 216
 217 =item C<PASM1 compiler> [eligible in 2.1]
 218
 219 See PDB_compile. Note that the current version of the C<PASM1> compiler
 220 issues a warning and is not functional. (However, it used to segfault.)
 221
 222 =back
 223
 224 =head2 Parrot Grammar Engine (PGE)
 225
 226 =over 4
 227
 228 =item Action methods in rules
 229
 230 Per Synopsis 5, all regexes will have an implied {*} token at the
 231 end which cause invocation of an action method if a C<:action>
 232 object is supplied.
 233
 234 L<https://trac.parrot.org/parrot/ticket/843>
 235
 236 =back
 237
 238 =head2 Parrot Compiler Toolkit
 239
 240 =over 4
 241
 242 =item PCT::HLLCompiler stages [eligible in 1.1]
 243
 244 The interface of various methods for adding, removing, and modifying
 245 the list stages in a PCT::HLLCompiler object is subject to change.
 246 The existing actual stages will remain; only the mechanism for specifying
 247 the order of individual stages is likely to change.
 248
 249 L<https://trac.parrot.org/parrot/ticket/462>
 250
 251 =item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]
 252
 253 In order to facilitate using PCT::HLLCompiler with test harnesses,
 254 the C<command_line> method of PCT::HLLCompiler object exits silently
 255 if it detects that it is being run in a sample run from Perl's
 256 Test::Harness.  Currently this detection is done by checking the
 257 second command line argument for "@INC"; future releases may
 258 use a different detection mechanism or eliminate it altogether.
 259
 260 L<https://trac.parrot.org/parrot/ticket/463>
 261
 262 =item PAST::Val node generation [eligible in 1.5]
 263
 264 The PAST::Compiler may generate the code for PAST::Val nodes
 265 (i.e., constants) at the beginning of the block (Parrot sub) instead
 266 of the location where they occur in the PAST tree.
 267
 268 L<https://trac.parrot.org/parrot/ticket/868>
 269
 270 =back
 271
 272 =head2 Not Quite Perl (NQP)
 273
 274 =over 4
 275
 276 =item C< $(...) > syntax  [eligible in 1.5]
 277
 278 The C< $(...) > syntax for obtaining a result object from a Match
 279 object will no longer work.  The new syntax is to invoke the
 280 C<.ast> method on the Match object.
 281
 282 L<https://trac.parrot.org/parrot/ticket/459>
 283
 284 =item Quoted items [eligible in 1.5]
 285
 286 Double-quoted strings will interpret unescaped $-names
 287 as interpolated variables in the string.  Bare slashes
 288 will introduce regular expressions.  The C<< <foo bar> >>
 289 syntax will produce an array of strings instead of a single
 290 string.
 291
 292 L<https://trac.parrot.org/parrot/ticket/837>
 293
 294 =item C<< PIR q:to:<xyz> >> inline PIR [eligible in 1.5]
 295
 296 The C<< PIR q:to:<xyz> >> form of inline PIR in NQP scripts is
 297 deprecated.  Use C< Q:PIR { ... } >  or C< Q:PIR {{ ... }} >
 298 instead.
 299
 300 L<https://trac.parrot.org/parrot/ticket/842>
 301
 302 =back
 303
 304 =head1 build tools
 305
 306 =over 4
 307
 308 =item tools/build/dynoplibs.pl and tools/build/dynpmc.pl [eligible in 1.1]
 309
 310 Replaced with makefiles.
 311
 312 L<https://trac.parrot.org/parrot/ticket/338>
 313
 314 =back
 315
 316 =head1 Parrot library
 317
 318 =over 4
 319
 320 =item JSON, JSON, and Config;JSON [eligible in 1.5]
 321
 322 L<https://trac.parrot.org/parrot/ticket/508>
 323
 324 =item Cross-HLL library loading [experimental]
 325
 326 L<https://trac.parrot.org/parrot/ticket/754>
 327
 328 =item OpenGL bindings and libraries [experimental]
 329
 330 L<https://trac.parrot.org/parrot/ticket/852>
 331
 332 =back
 333
 334 =head1 Footnotes
 335
 336 =over 4
 337
 338 =item 1
 339
 340 L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.
 341
 342 Older tickets may be listed at L<RT|https://rt.perl.org/rt3>.
 343
 344 =item 2
 345
 346 For an item to be considered experimental, it can B<never> have shipped in
 347 a stable release without the C<[experimental]> tag; otherwise, it must be
 348 deprecated normally before removal or incompatible change.
 349
 350 =back
 351
 352 =cut