Author: jkeenan
Date: Thu Aug 14 19:22:56 2008
New Revision: 30241
Modified:
branches/opsrenum/lib/Parrot/OpsRenumber.pm
branches/opsrenum/tools/dev/opsrenumber.pl
Log:
Improve inline comments and POD.
Modified: branches/opsrenum/lib/Parrot/OpsRenumber.pm
==============================================================================
--- branches/opsrenum/lib/Parrot/OpsRenumber.pm (original)
+++ branches/opsrenum/lib/Parrot/OpsRenumber.pm Thu Aug 14 19:22:56 2008
@@ -13,6 +13,7 @@
=head1 SYNOPSIS
+ use Parrot::Config qw( %PConfig );
use Parrot::OpsRenumber;
$self = Parrot::OpsRenumber->new( {
@@ -26,7 +27,7 @@
} );
$self->prepare_ops();
- $self->renum_op_map_file();
+ $self->renum_op_map_file( $PConfig{MAJOR} );
=cut
@@ -57,9 +58,10 @@
=item * Arguments
-String holding name of an F<.ops> file; defaults to
-F<src/ops/ops.num>. (Implicitly requires that the C<argv> and
-C<script> elements were provided to the constructor.)
+Two scalars. First is Parrot major version number. Second is optional:
+string holding name of an F<.ops> file; defaults to F<src/ops/ops.num>.
+(Implicitly requires that the C<argv> and C<script> elements were provided to
+the constructor.)
=item * Return Value
@@ -76,6 +78,8 @@
my $file = scalar(@_) ? shift : $self->{num_file};
if ($major_version == 0) {
+ # Pre-Parrot 1.0 case
+
# We open up the currently existing ops.num and file and read it
# line-by-line. That file is basically divided into two halves
# separated by the ###DYNAMIC### line. Above that line are found (a)
@@ -83,8 +87,8 @@
# Below that line are all the remaining opcodes. All opcode lines
# match the pattern /^(\w+)\s+(\d+)$/. Everything above the line gets
# pushed into @lines and, if it's an opcode line, get's split and
- # pushed into %fixed as well. Essentially nothing happens to the
- # (opcode) lines below the DYNAMIC line.
+ # pushed into %fixed as well. Nothing happens to the (opcode) lines
+ # below the DYNAMIC line.
my ( $name, $number, @lines, %fixed, $fix );
$fix = 1;
@@ -104,7 +108,7 @@
close $OP;
# Now we re-open the very same file we just read -- this time for
- # writing. We directly print all the lines n @lines, i.e., those
+ # writing. We directly print all the lines in @lines, i.e., those
# above the DYNAMIC line. For the purpose of renumbering, we create
# an index $n.
@@ -113,28 +117,23 @@
print $OP @lines;
my ($n);
- #
- # we can't use all autogenerated ops from oplib/core
+ # We can't use all autogenerated ops from oplib/core
# there are unwanted permutations like 'add_i_ic_ic
- # which aren't opcodes but calced at compile-time
- #
+ # which aren't opcodes but calculated at compile-time.
# The ops element is set by prepare_ops(), which is inherited from
# Parrot::Ops2pm::Base. prepare_ops(), in turn, works off
# Parrot::OpsFile.
# So whether a particular opcode will appear in the *new* ops.num
- # depends entirely on whether or not it's found in @{
- # $self->{ops}->{OPS} }. If a particular opcode has been deleted or
+ # depends entirely on whether or not it's found in
+ # @{ $self->{ops}->{OPS} }. If a particular opcode has been deleted or
# gone missing from that array, then it won't appear in the new
# ops.num. That's acceptable pre-version 1.0, but not afterwards (per
# http://rt.perl.org/rt3/Ticket/Display.html?id=53976). At and after
# 1.0, the opcodes in ops.num will be non-deletable. New opcodes may
# be added to the end of the list and numbered accordingly, but no
- # opcodes may be deleted. When we get to that point and need to
- # renumber due to addition of opcodes, we'll simply determine which
- # opcodes are brand new and append them to the end of the list in some
- # order yet to be determined.
+ # opcodes may be deleted.
for ( @{ $self->{ops}->{OPS} } ) {
@@ -171,9 +170,9 @@
close $OP;
# Now we re-open the very same file we just read -- this time for
- # writing. We directly print all the lines n @lines, i.e., those
+ # writing. We directly print all the lines in @lines, i.e., those
# above the DYNAMIC line. For the purpose of renumbering, we create
- # an index $n.
+ # an index $n and initialize it at the highest opcode number yet seen.
open $OP, '>', $file
or die "Can't open $file, error $!";
@@ -191,15 +190,6 @@
return 1;
}
-=head1 AUTHOR
-
-See F<tools/build/ops2pm.pl> for a list of the Parrot hackers who, over a
-period of several years, developed the functionality now found in the methods
-of Parrot::Ops2pm and Parrot::OpsRenumber. Jim Keenan extracted that
-functionality and placed it in this package's methods.
-
-=cut
-
1;
# Local Variables:
Modified: branches/opsrenum/tools/dev/opsrenumber.pl
==============================================================================
--- branches/opsrenum/tools/dev/opsrenumber.pl (original)
+++ branches/opsrenum/tools/dev/opsrenumber.pl Thu Aug 14 19:22:56 2008
@@ -39,17 +39,20 @@
This program should be used when adding or removing opcodes.
+This program will behave differently depending on whether Parrot has reached
+major version 1 or not. In the current period (major version 0), all the
+opcodes except the first seven are potentially deletable and the opcodes'
+order may be rearranged. Once a production version of Parrot has been
+released, all then existing opcodes and their numbers will be deemed
+immutable, though new opcodes may be added at the end of the list.
+
=head1 SEE ALSO
=over 4
-=item F<tools/build/ops2c.pl>.
-
-=item F<lib/Parrot/Ops2pm.pm>.
-
-=item F<lib/Parrot/Ops2pm/Auxiliary.pm>.
+=item F<lib/Parrot/Ops2pm/Base.pm>.
-=item F<tools/dev/ops_renum.mak>.
+=item F<lib/Parrot/OpsRenumber.pm>.
=back
