add svn:ignore (*.str)

[parrot.git] / DEPRECATED.pod

# $Id$

=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 supported, even though they may
have shipped in a supported 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.

If you find a feature you once used was removed after a deprecation
cycle, L<https://trac.parrot.org/parrot/wiki/Deprecation>. Otherwise
please open a documentation ticket via Trac[1].

=head1 Are you using any Deprecated Features?

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

=begin PIR_FRAGMENT

 .include 'warnings.pasm'
 warningson .PARROT_WARNINGS_DEPRECATED_FLAG

=end PIR_FRAGMENT

=head1 PMCS

=over 4

=item GzipHandle [experimental]

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

=item PackfileDebug [experimental]

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

=item CodeString [eligible in 2.7]

L<http://trac.parrot.org/parrot/ticket/1633>

=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 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 UnManagedStruct handling nested structure [eligible in 2.4]

UnManagedStruct will be simplified to only support flat structures. This means
that elements which themselves have structure - struct pointers and function
pointers will be stored as C<void *> and C<void (*)(void)> respectively. To use
these, they will need to be cast to the appropriate signature on access.

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

=item UnManagedStruct initializer structure [eligible in 2.4]

The initializer structure will cease to be an array of triples. In stead, an
array of flags (no counts or offsets), or a string representation of the same
information may be used.

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

=item UnManagedStruct get_integer, set_integer_native [eligible in 2.4]

These will no longer refer to the byte length of the buffer, but to the number
of times the struct is repeated; emulating an array of structs.

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

=item ManagedStruct reallocations based on shape changes [eligible in 2.4]

Since shape changes may simply be used for re-interpreting data, and may also
occur in several steps, re-allocating after any one shape change may be
undesirable. In stead, an explicit allocate/reallocate method will be provided.

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

=item Auto-vivification of nested aggregates [eligible in 2.4]

E.g.

  $P0 = new ['Hash']
  $S1 = $P0['foo';'bar';'baz']

will not auto-vivify nested hashes and return PMCNULL early.

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

=item Method lower on String [eligible in 2.7]

Use the downcase opcode or subclass with a method name consistent with your
HLL.

L<http://trac.parrot.org/parrot/ticket/1606>

=item Method unescape on String [experimental]

This is a helper method for testing of Parrot_str_unescape_string.

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

=item logical_* vtables [eligiblie in 2.7]

These can be replaced by C<get_bool> and intval ops unless you're using them for
things that aren't really logical ops (don't do that!).

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

=item Method getpid on ParrotInterpreter [experimental]

Used to test the experimental function Parrot_getpid

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

=item Duplicated VTABLE functions [eligible in 2.10]

In F<src/pmc/oplib.pmc>, C<INTVAL get_integer()> is declared twice.

In F<src/pmc/resizablestringarray.pmc>, C<PMC *shift_pmc()> is declared twice.

L<http://trac.parrot.org/parrot/ticket/1785>

=back

=head1 Opcodes

=over 4

=item charset, charsetname, find_charset, trans_charset [eligible in 2.10]

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

These opcodes will be removed. The corresponding encoding opcodes should be
used instead.

=item open and close opcodes will be removed [eligible in 2.7]

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

These opcodes will be removed. The open/close methods on File or
the FileHandle PMC should be used instead.

=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 get_results opcode order and features [eligible in 2.1]

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.

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

=item NCI_FB_CB and NCI_FB_UD in iglobals [experimental]

Hooks allowing a runtime-loadable dynamic frame builder.

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

=item loadlib_p_s_p [experimental]

Ability to use non-default dynamic loading behaviour.

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

=item new_callback_p_p_p_s [eligible in 2.4]

To be replaced with new_callback_p_p_p_p_s.

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

=item dlfunc and new_callback signature string format [eligible in 2.4]

These will be changed to allow more flexibility in types.

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

=item find_lex [eligible in 2.4]

find_lex will not throw exception for non-existing lexicals.

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

=item inplace string updates. [eligible in 2.4]

All "inplace" string update ops are deprecated. E.g. "chopn_s", etc.
Part of COW removal.

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

=item find_codepoint [experimental]

Intended to replace the CodeString charname_to_ord method.

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

=item All opcodes that modify non-argument registers. [eligible in 2.7]

E.g. "cleari", etc.

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

=item exchange [eligible in 2.7]

This op is too low level for Parrot in its current form.

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

=item finalize [experimental]

Finalize exception handler, unrolling inner runloops if needed.

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

=item logical PMC ops [eligible in 2.7]

These fall out from the logical vtables deprecation.

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

=item errorson, errorsoff operations [eligible in 2.10]

The C<.PARROT_ERRORS_GLOBAL_FLAG> flag will be eliminated. It is not used by Parrot.

=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 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>

=item :unique_reg flag [eligible in 2.7]

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

=item .nci_call [eligible in 2.7]

As of the latest PCC changes, there is nothing special about calling an NCI sub.

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

=item .meth_call [eligible in 2.7]

As of the latest PCC changes, this does nothing different from '.call'.

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

=item :main Sub behaviour and selection. [eligible in 2.7]

Currently, if no :main sub is found, the first .sub in a file is used as
main. Also, arguments are passed to the main sub regardless of the .param
declarations in that sub.

After this change, if no sub is marked with :main, an exception will be
raised. Multiple :main declarations will be still be allowed, and all but the
first will be ignored.

This change will also force all subs, including :main, to have their
arguments checked - to allow an arbitrary number of arguments, have
this be the only .param declaration in the sub.

 .param pmc args :slurpy


L<https://trac.parrot.org/parrot/ticket/1033>
L<https://trac.parrot.org/parrot/ticket/1704>
L<https://trac.parrot.org/parrot/ticket/1705>

=back

=head1 Functions

=over 4

=item mmd_cvt_to_types [eligible in 1.1]

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

=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. A list of renamed
functions will be kept in the ticket at:

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

=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 L<https://trac.parrot.org/parrot/ticket/1506>

=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.

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

=item STRING COW [eligible in 2.4]

COW strings are to be removed. All "inplace" string modification
functions and all "inplace" string ops are deprecated.

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

=item Parrot_str_unescape_string [experimental]

This function is an experimental addition to enhance and maybe replace
Parrot_str_unescape

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

=item Parrot_getpid [experimental]

Get process id, experimental.

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

=back

=head1 Compiler tools

=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> 

=item Meta-model implementation used by PCT [eligible in 2.7]

PCT is set to switch to a new meta-model implementation for its classes
and objects. This will most likely only affect those who rely on the
interface of what is returned from .HOW, or rely on PCT objects exhibiting
various other peculiarities of the P6object implementation. (Even when that
is the case, the HOW API will not be changing too drastically, so for most
PCT users there should be little to no upheavel.)

=back

=head1 Parrot library

=over 4

=item PARROT_LIBRARY and PARROT_INCLUDE environment variables [experimental]

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

A way to provide an equivalent of -L and -I parrot command line options
to language that doesn't support it.

=item Protoobject [eligible in 2.7]

Use P6Object instead.

L<http://trac.parrot.org/parrot/ticket/1337>

=item Archive::Tar & Archive::Zip [experimental]

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

=item LWP, HTTP::Message, URI & URI::Escape [experimental]

L<http://trac.parrot.org/parrot/ticket/1637>

=item 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>

=back

=head1 Experimental

=over 4

=item Threads and Parallelism [experimental]

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

=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 supported release without the C<[experimental]> tag; otherwise, it must be
deprecated normally before removal or incompatible change.

=back

=cut