=head1 NAME

core.ops

=head1 DESCRIPTION

Parrot's core library of ops.

=head2 Basic ops

These are the fundamental operations.

=over 4

=item B<end>()

Halts the interpreter.

=item B<noop>()

Does nothing other than waste an iota of time and 32 bits of bytecode space.

=back

=head2 System environment operations

These operations allow interaction between the Parrot program and the system
environment.

=over 4

=item B<close>(inout INT)

Close file opened on file descriptor $1.

=item B<err>(out INT)

Store the system error code in $1.

=item B<err>(out STR)

Store the system error message in $1.

=item B<open>(out INT, in STR)

Open file named $2 for reading and writing and save the file
descriptor into $1.

=item B<open>(out INT, in STR, in STR)

Open file named $2 with flags $3 and mode 0644 (rw-r--r--), and save the file
descriptor into $1.

=item B<readline>(out STR, in INT)

Temporary hack op to read in a line from the file opened on the FILE *
we've evilly put in the integer register $2. If $2 is 0, 1, or 2 we
use stdin, stdout, or stderr respectively.

BE AFRAID! THIS IS *EEEEEEEVIL* pure and simple. (From the 8th
dimension, no less)

If for some reason the line's longer than 64K you get only 64K

=item B<ord>(out INT, in STR)

Two-argument form returns the 0th character of string $2 in register $1.
If $2 is empty, throws an exception.

=item B<ord>(out INT, in STR, in INT)

Three-argument form returns character $3 of string $2 in register 1.
If $2 is empty, throws an exception.
If $3 is greater than the length of string $2, throws an exception
If $3 is less then zero but greater than the negative of the length, counts
backwards through the string, such that -1 is the last character, -2 is the
second-to-last character, and so on.
If $3 is less than the negative of the length, throws an exception.

=item B<print>(in INT)

=item B<print>(in NUM)

=item B<print>(in PMC)

=item B<print>(in STR)

Print $1 to standard output.

=item B<print>(in INT, in INT)

=item B<print>(in INT, in NUM)

=item B<print>(in INT, in PMC)

=item B<read>(out INT, in INT)

Read an INTVAL from file descriptor $2 into $1.

=item B<read>(out NUM, in INT)

Read a FLOATVAL from file descriptor $2 into $1.

=item B<read>(out STR, in INT, in INT)

Read $3 bytes from file descriptor $2 into string $1.

=item B<time>(out INT)

Puts the current system time (represented as a whole number of seconds)
in $1.

=item B<time>(out NUM)

Puts the current system time (represented as a number of seconds, with
microseconds) in $1.

=item B<write>(in INT, in INT)

=item B<write>(in INT, in NUM)

=item B<write>(in INT, in STR)

Write $2 to file descriptor $1.

=back

=head2 Register loading operations

These operations load registers from constants or other registers.

=over 4

=item B<set>(out INT, in INT)

=item B<set>(out INT, in NUM)

=item B<set>(out INT, in PMC)

=item B<set>(out INT, in STR)

=item B<set>(out NUM, in INT)

=item B<set>(out NUM, in NUM)

=item B<set>(out NUM, in PMC)

=item B<set>(out NUM, in STR)

=item B<set>(out PMC, in INT)

=item B<set>(out PMC, in NUM)

=item B<set>(out PMC, in PMC)

=item B<set>(out PMC, in STR)

=item B<set>(out STR, in INT)

=item B<set>(out STR, in NUM)

=item B<set>(out STR, in PMC)

=item B<set>(out STR, in STR)

Set $1 to $2.

=item B<set_keyed>(out PMC, out PMC, in PMC, in PMC)

    $1[$2] = $3[$4];

=item B<clone>(out PMC, in PMC)

Copies a PMC $1 to $2.

=back

=head2 Conditional branch operations

These operations perform a conditional relative branch. If the condition is
met, the branch happens, otherwise control falls to the next operation.

=over 4

=item B<eq>(in INT, in INT)

=item B<eq>(in NUM, in NUM)

=item B<eq>(in STR, in STR)

=item B<eq>(in INT, in INT, in INT)

=item B<eq>(in NUM, in NUM, in INT)

=item B<eq>(in STR, in STR, in INT)

Branch if $1 is equal to $2.

Return address is popped off the call stack if no address is supplied.

=item B<ne>(in INT, in INT)

=item B<ne>(in NUM, in NUM)

=item B<ne>(in STR, in STR)

=item B<ne>(in INT, in INT, in INT)

=item B<ne>(in NUM, in NUM, in INT)

=item B<ne>(in STR, in STR, in INT)

Branch if $1 is not equal to $2.

Return address is popped off the call stack if no address is supplied.

=item B<lt>(in INT, in INT, in INT)

=item B<lt>(in NUM, in NUM, in INT)

=item B<lt>(in PMC, in PMC, in INT)

=item B<lt>(in STR, in STR, in INT)

Branch if $1 is less than $2.

=item B<le>(in INT, in INT, in INT)

=item B<le>(in NUM, in NUM, in INT)

=item B<le>(in STR, in STR, in INT)

Branch if $1 is less than or equal to $2.

=item B<gt>(in INT, in INT, in INT)

=item B<gt>(in NUM, in NUM, in INT)

=item B<gt>(in STR, in STR, in INT)

Branch if $1 is greater than $2.

=item B<ge>(in INT, in INT, in INT)

=item B<ge>(in NUM, in NUM, in INT)

=item B<ge>(in STR, in STR, in INT)

Branch if $1 is greater than or equal to $2.

=item B<if>(in INT, in INT)

=item B<if>(in NUM, in INT)

=item B<if>(in PMC, in INT)

=item B<if>(in STR, in INT)

Check register $1. If true, branch by $2.

=item B<unless>(in INT, in INT)

=item B<unless>(in NUM, in INT)

=item B<unless>(in PMC, in INT)

=item B<unless>(in STR, in INT)

Check register $1. If false, branch by $2.

=back

=head2 Arithmetic operations

These operations store the results of arithmetic on other registers and
constants into their destination register, $1.

=over 4

=item B<abs>(out INT, in INT)

=item B<abs>(out INT, in NUM)

=item B<abs>(out NUM, in INT)

=item B<abs>(out NUM, in NUM)

Set $1 to absolute value of $2.

=item B<add>(out INT, in INT, in INT)

=item B<add>(out NUM, in NUM, in NUM)

Set $1 to the sum of $2 and $3.

=item B<cmod>(out INT, in INT, in INT)

NOTE: This "uncorrected mod" algorithm uses the C language's built-in
mod operator (x % y), which is

    ... the remainder when x is divided by y, and thus is zero
    when y divides x exactly.
    ...
    The direction of truncation for / and the sign of the result
    for % are machine-dependent for negative operands, as is the
    action taken on overflow or underflow.
                                                     -- [1], page 41

Also:

    ... if the second operand is 0, the result is undefined. 
    Otherwise, it is always true that (a/b)*b + a%b is equal to z. If
    both operands are non-negative, then the remainder is non-
    negative and smaller than the divisor; if not, it is guaranteed
    only that the absolute value of the remainder is smaller than
    the absolute value of the divisor.
                                                     -- [1], page 205

This op is provided for those who need it (such as speed-sensitive
applications with heavy use of mod, but using it only with positive
arguments), but a more mathematically useful mod based on ** floor(x/y)
and defined with y == 0 is provided by the mod_i op.

  [1] Brian W. Kernighan and Dennis M. Ritchie, *The C Programming
      Language*, Second Edition. Prentice Hall, 1988.

TODO: Doesn't the Parrot interpreter need to catch the exception?

=item B<cmod>(out NUM, in NUM, in NUM)

NOTE: This "uncorrected mod" algorithm uses the built-in C math library's
fmod() function, which computes

    ... the remainder of dividing x by y. The return value is
    x - n * y, where n is the quotient of x / y, rounded towards
    zero to an integer.
                                -- fmod() manpage on RedHat Linux 7.0

In addition, fmod() returns

    the remainder, unless y is zero, when the function fails and
    errno is set.

According to page 251 of [1], the result when y is zero is implementation-
defined.

This op is provided for those who need it, but a more mathematically
useful numeric mod based on floor(x/y) instead of truncate(x/y) and
defined with y == 0 is provided by the mod_n op.

  [1] Brian W. Kernighan and Dennis M. Ritchie, *The C Programming
      Language*, Second Edition. Prentice Hall, 1988.

TODO: Doesn't the Parrot interpreter need to catch the exception?

=item B<dec>(inout INT)

=item B<dec>(inout NUM)

Decrease $1 by one.

=item B<dec>(inout INT, in INT)

=item B<dec>(inout NUM, in NUM)

Decrease $1 by the amount in $2.

=item B<div>(out INT, in INT, in INT)

=item B<div>(out NUM, in NUM, in NUM)

Set $1 to the quotient of $2 divided by $3. In the case of INTVAL division, the
result is truncated (NOT rounded or floored).

=item B<inc>(inout INT)

=item B<inc>(inout NUM)

Increase $1 by one.

=item B<inc>(inout INT, in INT)

=item B<inc>(inout NUM, in NUM)

Increase $1 by the amount in $2.

=item B<mod>(out INT, in INT, in INT)

NOTE: This "corrected mod" algorithm is based on the C code on page 70
of [1]. Assuming correct behavior of the built-in mod operator (%) with
positive arguments, this algorithm implements a mathematically convenient
version of mod, defined thus:

  x mod y = x - y * floor(x / y)

For more information on this definition of mod, see section 3.4 of [2],
pages 81-85.

References:

  [1] Donald E. Knuth, *MMIXware: A RISC Computer for the Third
      Millennium* Springer, 1999.

  [2] Ronald L. Graham, Donald E. Knuth and Oren Patashnik, *Concrete
      Mathematics*, Second Edition. Addison-Wesley, 1994.

=item B<mod>(out NUM, in NUM, in NUM)

NOTE: This "corrected mod" algorithm is based on the formula of [1]:

  x mod y = x - y * floor(x / y)

For more information on this definition of mod, see section 3.4 of [1],
pages 81-85.

References:

  [1] Ronald L. Graham, Donald E. Knuth and Oren Patashnik, *Concrete
      Mathematics*, Second Edition. Addison-Wesley, 1994.

=item B<mul>(out INT, in INT, in INT)

=item B<mul>(out NUM, in NUM, in NUM)

Set $1 to the product of $2 and $3.

=item B<neg>(out INT, in INT)

=item B<neg>(out NUM, in NUM)

Set $1 to the negative of $2.

=item B<pow>(out NUM, in INT, in INT)

=item B<pow>(out NUM, in INT, in NUM)

=item B<pow>(out NUM, in NUM, in INT)

=item B<pow>(out NUM, in NUM, in NUM)

Set $1 to $2 raised to the power $3.

=item B<sub>(out INT, in INT, in INT)

=item B<sub>(out NUM, in NUM, in NUM)

Set $1 to $2 minus $3.

=back

=head2 String operations

These operations operate on STRINGs.

=over 4

=item B<chopn>(inout STR, in INT)

Remove $2 characters from the end of the string in $1.

TODO: Create a three-argument version of this? Don't force in-place modification.'

=item B<concat>(inout STR, in STR)

=item B<concat>(out STR, in STR, in STR)

Append the string in $2 to the string in $1.

The three argument version appends the string $3 to $2 and places the result
into $1.

=item B<repeat>(out STR, in STR, in INT)

Repeats string $2 $3 times and stores result in $1.

=item B<length>(out INT, in STR)

Set $1 to the length (in characters) of the string in $2.

=item B<substr>(out STR, in STR, in INT, in INT)

Set $1 to the portion of $2 starting at (zero-based) character position $3 and having
length $4.

=back

=head2 Transcendental mathematical operations

These operations perform various transcendental operations such as logarithmics
and trigonometrics.

=over 4

=item B<acos>(out NUM, in INT)

=item B<acos>(out NUM, in NUM)

Set $1 to the arc cosine (in radians) of $2.

=item B<asec>(out NUM, in INT)

=item B<asec>(out NUM, in NUM)

Set $1 to the arc secant (in radians) of $2.

=item B<asin>(out NUM, in INT)

=item B<asin>(out NUM, in NUM)

Set $1 to the arc sine (in radians) of $2.

=item B<atan>(out NUM, in INT)

=item B<atan>(out NUM, in NUM)

=item B<atan>(out NUM, in INT, in INT)

=item B<atan>(out NUM, in INT, in NUM)

=item B<atan>(out NUM, in NUM, in INT)

=item B<atan>(out NUM, in NUM, in NUM)

The two-argument versions set $1 to the arc tangent (in radians) of $2.

The three-argument versions set $1 to the arc tangent (in radians) of
$2 / $3, taking account of the signs of the arguments in determining the
quadrant of the result.

=item B<cos>(out NUM, in INT)

=item B<cos>(out NUM, in NUM)

Set $1 to the cosine of $2 (given in radians).

=item B<cosh>(out NUM, in INT)

=item B<cosh>(out NUM, in NUM)

Set $1 to the hyperbolic cosine of $2 (given in radians).

=item B<exp>(out NUM, in INT)

=item B<exp>(out NUM, in NUM)

Set $1 to I<e> raised to the power $2. I<e> is the base of the natural logarithm.

=item B<ln>(out NUM, in INT)

=item B<ln>(out NUM, in NUM)

Set $1 to the natural (base I<e>) logarithm of $2.

=item B<log10>(out NUM, in INT)

=item B<log10>(out NUM, in NUM)

Set $1 to the base 10 logarithm of $2.

=item B<log2>(out NUM, in INT)

=item B<log2>(out NUM, in NUM)

Set $1 to the base 2 logarithm of $2.

=item B<sec>(out NUM, in INT)

=item B<sec>(out NUM, in NUM)

Set $1 to the secant of $2 (given in radians).

=item B<sech>(out NUM, in INT)

=item B<sech>(out NUM, in NUM)

Set $1 to the hyperbolic secant of $2 (given in radians).

=item B<sin>(out NUM, in INT)

=item B<sin>(out NUM, in NUM)

Set $1 to the sine of $2 (given in radians).

=item B<sinh>(out NUM, in INT)

=item B<sinh>(out NUM, in NUM)

Set $1 to the hyperbolic sine of $2 (given in radians).

=item B<tan>(out NUM, in INT)

=item B<tan>(out NUM, in NUM)

Set $1 to the tangent of $2 (given in radians).

=item B<tanh>(out NUM, in INT)

=item B<tanh>(out NUM, in NUM)

Set $1 to the hyperbolic tangent of $2 (given in radians).

=back

=head2 Bitwise logical operations

These operations apply  bitwise logical functions to their arguments.

=over 4

=item B<and>(out INT, in INT, in INT)

Set the bits of $1 according to the B<and> of the corresponding bits from $2 and $3.

=item B<not>(out INT, in INT)

Set the bits of $1 to the B<not> of the corresponding bits from $2.

=item B<or>(out INT, in INT, in INT)

Set the bits of $1 according to the B<or> of the corresponding bits from $2 and $3.

=item B<shl>(out INT, in INT, in INT)

Set $1 to the value of $2 shifted left by $3 bits.

=item B<shr>(out INT, in INT, in INT)

Set $1 to the value of $2 shifted right by $3 bits.

=item B<xor>(out INT, in INT, in INT)

Set the bits of $1 according to the B<xor> of the corresponding bits from $2 and $3.

=back

=head2 Interpreter flag modification operations

These operations modify the internal interpreter flags, affecting its
subsequent operation.

=over 4

=item B<debug>(in INT)

If $1 is zero, turn off debugging. Otherwise turn it on.

=item B<bounds>(in INT)

If $1 is zero, turn off byte code bounds checking. Otherwise turn it on.

=item B<profile>(in INT)

If $1 is zero, turn off profiling. Otherwise turn it on.

=item B<trace>(in INT)

If $1 is zero, turn off tracing. Otherwise turn it on.

=back

=head2 Register operations

These operations effect entire sets of registers.

=over 4

=item B<cleari>()

=item B<clearn>()

=item B<clearp>()

=item B<clears>()

Clear all the registers of the type indicated in the name of the operation.

INTVAL ('i') and FLOATVAL ('n') registers clear to zero.

PMC ('p') and STRING ('s') registers clear to NULL.

=item B<popi>()

=item B<popn>()

=item B<popp>()

=item B<pops>()

Restore all the registers of the type indicated in the name of the operation
from the most recently B<push>ed copies.

=item B<pushi>()

=item B<pushn>()

=item B<pushp>()

=item B<pushs>()

Save all the registers of the type indicated in the name of the operation.

=back

=head2 Register stack operations

These operations effect individual registers.

=over 4

=item B<entrytype>(out INT, in INT)

Gets the type of entry $2 of the stack and puts in in $1

=item B<save>(in INT)

=item B<save>(in NUM)

=item B<save>(in STR)

=item B<save>(in PMC)

Save register or constant $1 onto the stack.

=item B<restore>(out INT)

=item B<restore>(out NUM)

=item B<restore>(out PMC)

=item B<restore>(out STR)

Restore register $1 from the appropriate register stack.

=item B<rotate_up>(in INT)

Rotate the top $1 entries in the user stack so that the top entry
becomes the bottom entry in that range.

=back

=head2 Control flow

The control flow opcodes check conditions and manage program flow.

=over 4

=item B<branch>(in INT)

Branch forward or backward by the amount in $1.

=item B<bsr>(in INT)

Branch to the location specified by $1. Push the current location onto the call
stack for later returning.

=item B<jsr>()

Jump to the location specified by register X. Push the current
location onto the call stack for later returning.

TODO: Implement this, or delete the entry.

=item B<jump>(out INT)

Jump to the address held in register $1.

=back

=head2 Symbol table ops

Ops to manipulate the symbol table

=over 4

=item B<find_global>(out PMC, in STR)

Find the global named $2 and store it in $1

=back

=head2 Miscellaneous

Opcodes which need to be sorted into better categories.

=over 4

=item B<sweep>()

Trigger a dead object detection sweep

=item B<collect>()

Trigger a GC collection

=item B<interpinfo>(out INT, in INT)

Fetch some piece of information about the interpreter and put it in $1

=item B<newinterp>(out PMC, in INT)

Create a new interpreter and store it in a PMC

=item B<runinterp>(inout PMC, in INT)

Take a built interpreter and run the code starting at offset $2

=item B<new>(out PMC, in INT)

=item B<new>(out PMC, in INT, in INT)

Create a new PMC of class $2; look in F<pmc.h> for the base
vtable types. The assembler allows you to specify PMCs by type
name as well as by integer - you should do this for compatibility,
to avoid problems if the base types get reassigned. For example:

  new P0, PerlScalar

Optionally a size may be passed to the constructor which may or
may not be used by the particular class. For example:

  new P0, PerlStruct, 64

=item B<find_type>(out INT, in STR)

Find the PMC type by name

=item B<ret>()

Pop the location off the top of the stack and go there.

=item B<sleep>(in INT)

Sleep for $1 seconds

=item B<setline>(in INT)

Set the current line number we're executing code for

=item B<getline>(out INT)

Get the current line number

=item B<setfile>(in STR)

Sets the current file we're executing code for

=item B<getfile>(out STR)

Gets the current file we're executing code for

=item B<setpackage>(in STR)

Sets the current package we're executing code for

=item B<getpackage>(out STR)

Gets the current package we're executing code for

=item B<warningson>(in INT)

Turns on warnings categories.  Categories already turned on will 
stay on.  Current categories and the numbers they map to are:

=over 4

=item 1: undef

=item 2: IO

=item -1: all

=back

To turn on multiple categories, OR the category numbers together.

=item B<warningsoff>(in INT)

Turns off warnings categories.  Categories already turned off will 
stay off.  See the documentation for B<warningson> for category 
numbers.

=back

=head1 COPYRIGHT

Copyright (C) 2001 Yet Another Society. All rights reserved.

=head1 LICENSE

This program is free software. It is subject to the same license
as the Parrot interpreter itself.