# $Id: DEPRECATED.pod 44022 2010-02-16 14:10:51Z whiteknight $

=head1 Purpose

Provide a list of deprecated and experimental items in parrot.
All items in this list should have a corresponding Trac ticket[1].

=head1 Experimental Status

These features are not considered stable, even though they may
have shipped in a stable release of parrot[2]. Use them at your own
risk, as they can be removed or changed in any release. These
items are marked below with C<[experimental]>.

=head1 Deprecated Status

Please see F<docs/project/support_policy.pod> for the parrot
project's policy regarding deprecated features.

Each item shows the first release in which it is eligible for removal, e.g.
C<[eligible in 1.5]>.  If the release listed is one that has already
shipped, this feature may be removed in B<any> upcoming release, and
you should no longer rely on it.

Whenever deprecated items are removed, information
regarding how to cope with the removal should be added to
L<https://trac.parrot.org/parrot/wiki/Deprecation>.

When running parrot, you can receive warnings about deprecated opcodes.
Either run parrot with the C<-w> option to enable all warnings, or
specifically by including this C<PIR> code:

 .include 'warnings.pasm'
 warningson .PARROT_WARNINGS_DEPRECATED_FLAG

=head1 PMCS

=over 4

=item moved to dynpmc [eligible in 1.1]

AddrRegistry, CodeString, Env, Eval, File, OS, PCCMETHOD_Test, StringHandle,
and Timer.

L<https://trac.parrot.org/parrot/ticket/448>

=item multiple dispatch within core PMCs [eligible in 1.1]

L<https://trac.parrot.org/parrot/ticket/452>

=item Method stdhandle in ParrotInterpreter [experimental]

L<https://trac.parrot.org/parrot/ticket/264>

=item Use of undocumented variables in class_init [eligible in 2.1]

The current implementation allows the class_init vtable function body to
use local symbols from the generated part. For example, some PMC used
to use the pass counter. In the future, the class_init body from the PMC
file may not be inserted directly in the body of the generated one,
so this usage will not be allowed.

L<https://trac.parrot.org/parrot/ticket/918>

=item Overriding vtable invoke in PIR objects [experimental]

The VTABLE invoke in object.pmc puts SELF at the start of the
signature call arguments when there is no current object and is
not already here. This allows the usage of $P0() instead of $P0($P0).

L<https://trac.parrot.org/parrot/ticket/103>

=item CPointer PMC [eligible in 2.1]

And all uses in the Parrot calling conventions.

L<https://trac.parrot.org/parrot/ticket/1407>

=back

=head1 Opcodes

=over 4

=item moved to dynop [eligible in 1.1]

Parts or all of: bit.ops, debug.ops, io.ops, math.ops, set.ops
(the obscure and rarely used parts), sys.ops.

L<https://trac.parrot.org/parrot/ticket/449>

=item get_addr and set_addr [eligible in 1.5]

L<https://trac.parrot.org/parrot/ticket/218>

These opcodes are being repurposed. They will always return a unique memory
address of the PMC. Uses of get_addr and set_addr that would set label values
for Sub, Exception, and related PMC types will instead be handled by
get_label and set_label.

=item All bitwise ops [eligible in 2.1]

All bitwise ops (all ops containing C<bitwise> in their names) will be provided
by dynops.  B<NOTE>: Before removing the bitwise ops, make sure that the
equivalent dynops are available and that the major HLLs (Rakudo, Partcl, Lua,
etc) have switched to using them.

L<https://trac.parrot.org/parrot/ticket/1260>

=item get_results opcode order and features [eligible in 2.1]

Move get_results to follow invoke.

L<https://trac.parrot.org/parrot/ticket/1405>

get_results no longer used to fetch exception object.

L<https://trac.parrot.org/parrot/ticket/1406>

=item GC_SYS_NAME option to interpinfo_s_i [experimental]

Ability to get the string name of the current GC core from the interpinfo_s_i.
See r43900 and r43904 for details.

=back

=head1 Bytecode

=over 4

=item packfile structure [experimental]

L<https://trac.parrot.org/parrot/ticket/451>

=item opcode numbering [experimental]

L<https://trac.parrot.org/parrot/ticket/451>

=item PMC numbering [experimental]

L<https://trac.parrot.org/parrot/ticket/451>

=back

=head1 Debugger

Assigning to registers [experimental]

=head1 PIR syntax

=over 4

=item Assignment syntax with opcodes [eligible in 1.1]

L<https://trac.parrot.org/parrot/ticket/906>

=item named class/pmc lookup in pir syntax such as new, isa, subclass,
    get_class, etc [eligible in 1.1]

Class PMC name resolution will be the following.

if the arg is a STRING
  Relative to the current Namespace

if the arg is a Array (of any sort) or Key
  Relative to the current HLL Namespace

if the arg is a Namespace or Class PMC
  The passed in class or the class attached to the passed in namespace.

L<https://trac.parrot.org/parrot/ticket/159>

=item load or include paths prefixed with 'library/' or 'include/'
[eligible in 1.5]

L<https://trac.parrot.org/parrot/ticket/511>

=item continuation-based ExceptionHandlers [eligible in 2.1]

L<https://trac.parrot.org/parrot/ticket/1091>

=item implicit optional named parameters [eligible in 2.1]

L<https://trac.parrot.org/parrot/ticket/1103>

=back

=head1 Functions

=over 4

=item mmd_cvt_to_types [eligible in 1.1]

L<https://trac.parrot.org/parrot/ticket/907>

=item Subs marked with C<:vtable>/C<:method> aren't in namespace [eligible in 1.1]

Subs marked with C<:vtable> or C<:method> flags are no longer given a
namespace entry by default.  Use the C<:nsentry> flag to cause this
to happen.

L<https://trac.parrot.org/parrot/ticket/389>

=item C API coding standards cleanup [eligible in 1.1]

All C API functions that aren't currently named according to the
'Parrot_<system>_*' scheme will be renamed. If you depend on these
functions in an extending/embedding interface or C-level custom PMCs,
check in 1.4 or 2.0 for the new names.

L<https://trac.parrot.org/parrot/ticket/443>

=item Sub/method invocation functions [eligible in 2.1]

The old 'Parrot_call_*' functions for invoking a sub/method object from C are
deprecated, replaced by 'Parrot_ext_call'.

L<https://trac.parrot.org/parrot/ticket/1145>

=item PMC Attributes Allocation Functions [experimental]

 Parrot_gc_allocate_pmc_attributes
 Parrot_gc_free_pmc_attributes

These items and related helper functions are added as experimental support
for TT #895

=item PDB_compile and PDB_eval [eligible in 2.1]

The function PDB_compile doesn't work since some time, and his implementation
was a hack. His functionality may be reimplemented in another way. Until the
end of deprecation cycle it just throws an exception.

The PDB_eval function, that used in the debugger to support the eval
command, was using PDB_compile. His functionality must be reimplemented
in another way and with a name that follows current conventions, in the
meantime and until the end of the deprecation cycle it just shows a
diagnostic message.

L<https://trac.parrot.org/parrot/ticket/872>

=item Parrot_oo_get_namespace [eligible in 2.1]

L<https://trac.parrot.org/parrot/ticket/1069>

=item STRING Out parameters in Parrot_str_* functions [eligible in 2.1]

All STRING modification functions will return a STRING pointer; capture and use
this rather than relying on in-place modification of an existing pointer.

=back

=head1 Compiler tools

=head2 PASM1 compiler

=over 4

=item C<PASM1 compiler> [eligible in 2.1]

See PDB_compile. Note that the current version of the C<PASM1> compiler
issues a warning and is not functional. (However, it used to segfault.)

=back

=head2 Parrot Grammar Engine (PGE)

=over 4

=item Action methods in rules

Per Synopsis 5, all regexes will have an implied {*} token at the
end which cause invocation of an action method if a C<:action>
object is supplied.

L<https://trac.parrot.org/parrot/ticket/843>

=back

=head2 Parrot Compiler Toolkit

=over 4

=item PCT::HLLCompiler stages [eligible in 1.1]

The interface of various methods for adding, removing, and modifying
the list stages in a PCT::HLLCompiler object is subject to change.
The existing actual stages will remain; only the mechanism for specifying
the order of individual stages is likely to change.

L<https://trac.parrot.org/parrot/ticket/462>

=item PCT::HLLCompiler from Perl 5's Test::Harness [eligible in 1.1]

In order to facilitate using PCT::HLLCompiler with test harnesses,
the C<command_line> method of PCT::HLLCompiler object exits silently
if it detects that it is being run in a sample run from Perl's
Test::Harness.  Currently this detection is done by checking the
second command line argument for "@INC"; future releases may
use a different detection mechanism or eliminate it altogether.

L<https://trac.parrot.org/parrot/ticket/463>

=item PAST::Val node generation [eligible in 1.5]

The PAST::Compiler may generate the code for PAST::Val nodes
(i.e., constants) at the beginning of the block (Parrot sub) instead
of the location where they occur in the PAST tree.

L<https://trac.parrot.org/parrot/ticket/868>

=back

=head2 Not Quite Perl (NQP)

=over 4

=item C< $(...) > syntax  [eligible in 1.5]

The C< $(...) > syntax for obtaining a result object from a Match
object will no longer work.  The new syntax is to invoke the
C<.ast> method on the Match object.

L<https://trac.parrot.org/parrot/ticket/459>

=item Quoted items [eligible in 1.5]

Double-quoted strings will interpret unescaped $-names
as interpolated variables in the string.  Bare slashes
will introduce regular expressions.  The C<< <foo bar> >>
syntax will produce an array of strings instead of a single
string.

L<https://trac.parrot.org/parrot/ticket/837>

=item C<< PIR q:to:<xyz> >> inline PIR [eligible in 1.5]

The C<< PIR q:to:<xyz> >> form of inline PIR in NQP scripts is
deprecated.  Use C< Q:PIR { ... } >  or C< Q:PIR {{ ... }} >
instead.

L<https://trac.parrot.org/parrot/ticket/842>

=back

=head1 Parrot library

=over 4

=item MT19937 [eligible in 2.1]

L<https://trac.parrot.org/parrot/ticket/1278> - latest version now hosted
at L<http://github.com/fperrad/parrot-MT19937>. After 2.0, users will have
to install via C<plumage>.

=item JSON, JSON, and Config;JSON [eligible in 1.5]

L<https://trac.parrot.org/parrot/ticket/508>

=item Cross-HLL library loading [experimental]

L<https://trac.parrot.org/parrot/ticket/754>

=item OpenGL bindings and libraries [experimental]

L<https://trac.parrot.org/parrot/ticket/852>

=item Library name changes [eligible in 2.1]

The use of C<::> a namespace separator is deprecated.  Core libraries will
change to use multi-level keys instead.  For example, C<Data::Dumper> will
change to C<Data; Dumper>.  Affected libraries also include:
C<Parrot::Coroutine>, C<SDL>, C<Test::Builder>, C<YAML::Dumper>, and
C<PCRE::NCI>.

=back

=head1 Footnotes

=over 4

=item 1

L<Trac|http://trac.parrot.org/> is parrot's primary issue tracking system.

=item 2

For an item to be considered experimental, it can B<never> have shipped in
a stable release without the C<[experimental]> tag; otherwise, it must be
deprecated normally before removal or incompatible change.

=back

=cut
