Basic ops
System environment operations
Register loading operations
Conditional branch operations
Arithmetic operations
String operations
Transcendental mathematical operations
Bitwise logical operations
Interpreter flag modification operations
Register operations
Register stack operations
Control flow
Symbol table ops
Miscellaneous

NAME

core.ops

DESCRIPTION

Parrot's core library of ops.

Basic ops

These are the fundamental operations.

end(): Halts the interpreter.
noop(): Does nothing other than waste an iota of time and 32 bits of bytecode space.

System environment operations

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

close(inout INT)

Close file opened on file descriptor $1.

err(out INT)

Store the system error code in $1.

err(out STR)

Store the system error message in $1.

open(out INT, in STR)

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

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.

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

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.

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.

print(in INT)

print(in NUM)

print(in PMC)

print(in STR)

Print $1 to standard output.

print(in INT, in INT)

print(in INT, in NUM)

print(in INT, in PMC)

read(out INT, in INT)

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

read(out NUM, in INT)

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

read(out STR, in INT, in INT)

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

time(out INT)

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

time(out NUM)

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

write(in INT, in INT)

write(in INT, in NUM)

write(in INT, in STR)

Write $2 to file descriptor $1.

Register loading operations

These operations load registers from constants or other registers.

set(out INT, in INT)

set(out INT, in NUM)

set(out INT, in PMC)

set(out INT, in STR)

set(out NUM, in INT)

set(out NUM, in NUM)

set(out NUM, in PMC)

set(out NUM, in STR)

set(out PMC, in INT)

set(out PMC, in NUM)

set(out PMC, in PMC)

set(out PMC, in STR)

set(out STR, in INT)

set(out STR, in NUM)

set(out STR, in PMC)

set(out STR, in STR)

Set $1 to $2.

set_keyed(out PMC, out PMC, in PMC, in PMC)

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

clone(out PMC, in PMC)

Copies a PMC $1 to $2.

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.

eq(in INT, in INT)

eq(in NUM, in NUM)

eq(in STR, in STR)

eq(in INT, in INT, in INT)

eq(in NUM, in NUM, in INT)

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.

ne(in INT, in INT)

ne(in NUM, in NUM)

ne(in STR, in STR)

ne(in INT, in INT, in INT)

ne(in NUM, in NUM, in INT)

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.

lt(in INT, in INT, in INT)

lt(in NUM, in NUM, in INT)

lt(in PMC, in PMC, in INT)

lt(in STR, in STR, in INT)

Branch if $1 is less than $2.

le(in INT, in INT, in INT)

le(in NUM, in NUM, in INT)

le(in STR, in STR, in INT)

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

gt(in INT, in INT, in INT)

gt(in NUM, in NUM, in INT)

gt(in STR, in STR, in INT)

Branch if $1 is greater than $2.

ge(in INT, in INT, in INT)

ge(in NUM, in NUM, in INT)

ge(in STR, in STR, in INT)

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

if(in INT, in INT)

if(in NUM, in INT)

if(in PMC, in INT)

if(in STR, in INT)

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

unless(in INT, in INT)

unless(in NUM, in INT)

unless(in PMC, in INT)

unless(in STR, in INT)

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

Arithmetic operations

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

abs(out INT, in INT)

abs(out INT, in NUM)

abs(out NUM, in INT)

abs(out NUM, in NUM)

Set $1 to absolute value of $2.

add(out INT, in INT, in INT)

add(out NUM, in NUM, in NUM)

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

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?

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?

dec(inout INT)

dec(inout NUM)

Decrease $1 by one.

dec(inout INT, in INT)

dec(inout NUM, in NUM)

Decrease $1 by the amount in $2.

div(out INT, in INT, in INT)

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

inc(inout INT)

inc(inout NUM)

Increase $1 by one.

inc(inout INT, in INT)

inc(inout NUM, in NUM)

Increase $1 by the amount in $2.

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.

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.

mul(out INT, in INT, in INT)

mul(out NUM, in NUM, in NUM)

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

neg(out INT, in INT)

neg(out NUM, in NUM)

Set $1 to the negative of $2.

pow(out NUM, in INT, in INT)

pow(out NUM, in INT, in NUM)

pow(out NUM, in NUM, in INT)

pow(out NUM, in NUM, in NUM)

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

sub(out INT, in INT, in INT)

sub(out NUM, in NUM, in NUM)

Set $1 to $2 minus $3.

String operations

These operations operate on STRINGs.

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

concat(inout STR, in STR)

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.

repeat(out STR, in STR, in INT)

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

length(out INT, in STR)

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

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.

Transcendental mathematical operations

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

acos(out NUM, in INT)

acos(out NUM, in NUM)

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

asec(out NUM, in INT)

asec(out NUM, in NUM)

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

asin(out NUM, in INT)

asin(out NUM, in NUM)

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

atan(out NUM, in INT)

atan(out NUM, in NUM)

atan(out NUM, in INT, in INT)

atan(out NUM, in INT, in NUM)

atan(out NUM, in NUM, in INT)

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.

cos(out NUM, in INT)

cos(out NUM, in NUM)

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

cosh(out NUM, in INT)

cosh(out NUM, in NUM)

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

exp(out NUM, in INT)

exp(out NUM, in NUM)

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

ln(out NUM, in INT)

ln(out NUM, in NUM)

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

log10(out NUM, in INT)

log10(out NUM, in NUM)

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

log2(out NUM, in INT)

log2(out NUM, in NUM)

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

sec(out NUM, in INT)

sec(out NUM, in NUM)

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

sech(out NUM, in INT)

sech(out NUM, in NUM)

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

sin(out NUM, in INT)

sin(out NUM, in NUM)

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

sinh(out NUM, in INT)

sinh(out NUM, in NUM)

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

tan(out NUM, in INT)

tan(out NUM, in NUM)

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

tanh(out NUM, in INT)

tanh(out NUM, in NUM)

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

Bitwise logical operations

These operations apply bitwise logical functions to their arguments.

and(out INT, in INT, in INT): Set the bits of $1 according to the and of the corresponding bits from $2 and $3.
not(out INT, in INT): Set the bits of $1 to the not of the corresponding bits from $2.
or(out INT, in INT, in INT): Set the bits of $1 according to the or of the corresponding bits from $2 and $3.
shl(out INT, in INT, in INT): Set $1 to the value of $2 shifted left by $3 bits.
shr(out INT, in INT, in INT): Set $1 to the value of $2 shifted right by $3 bits.
xor(out INT, in INT, in INT): Set the bits of $1 according to the xor of the corresponding bits from $2 and $3.

Interpreter flag modification operations

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

debug(in INT): If $1 is zero, turn off debugging. Otherwise turn it on.
bounds(in INT): If $1 is zero, turn off byte code bounds checking. Otherwise turn it on.
profile(in INT): If $1 is zero, turn off profiling. Otherwise turn it on.
trace(in INT): If $1 is zero, turn off tracing. Otherwise turn it on.

Register operations

These operations effect entire sets of registers.

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.

Restore all the registers of the type indicated in the name of the operation from the most recently pushed copies.

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

Register stack operations

These operations effect individual registers.

entrytype(out INT, in INT): Gets the type of entry $2 of the stack and puts in in $1
save(in INT)
save(in NUM)
save(in STR)
save(in PMC): Save register or constant $1 onto the stack.
restore(out INT)
restore(out NUM)
restore(out PMC)
restore(out STR): Restore register $1 from the appropriate register stack.
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.

Control flow

The control flow opcodes check conditions and manage program flow.

branch(in INT)

Branch forward or backward by the amount in $1.

bsr(in INT)

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

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.

jump(out INT)

Jump to the address held in register $1.

Symbol table ops

Ops to manipulate the symbol table

find_global(out PMC, in STR): Find the global named $2 and store it in $1

Miscellaneous

Opcodes which need to be sorted into better categories.

sweep()

Trigger a dead object detection sweep

collect()

Trigger a GC collection

interpinfo(out INT, in INT)

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

newinterp(out PMC, in INT)

Create a new interpreter and store it in a PMC

runinterp(inout PMC, in INT)

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

new(out PMC, in INT)

new(out PMC, in INT, in INT)

Create a new PMC of class $2; look in 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: