This chapter contains a condensed list of PASM opcodes, PIR directives and instructions, and Parrot command-line options, sorted alphabetically for easy reference. Any PASM opcode is valid in PIR code, so if you're looking up PIR syntax you should check CHP-11-SECT-1"PASM Opcodes", CHP-11-SECT-2"PIR Directives", and CHP-11-SECT-3"PIR Instructions".
For complete details on each opcode and the latest changes, read the documentation in docs/ops/, or look at all the .ops files in the ops/ directory.
.ops
We've followed a few conventions. DEST is always the register where the result of the operation is stored. Sometimes the original value of DEST is one of the source values. VAL indicates that the actual value might be a literal integer, float, or string, or a register containing an integer, float, string, or PMC. See the .ops files for the combinations allowed with a particular operation.
DEST
VAL
abs R<DEST> abs R<DEST>, R<VAL>
Return the absolute value of a number. If VAL is left out, DEST gets the absolute value of itself.
Arguments: IR or NR or IR, I or IR, N or NR, I or NR, N
acos R<DEST>, R<VAL>
The arc cosine of VAL in radians.
Arguments: NR, N or NR, I
add R<DEST>, R<VAL> add R<DEST>, R<VAL>, R<VAL>
Add two values and return the sum. If only one VAL, add VAL to DEST.
Arguments: IR, I or NR, I or NR, N or P, I or P, N or P, P or IR, I, I or NR, N, I or NR, N, N or P, P, I or P, P, N or P, P, P
addattribute R<CLASS>, R<ATTR>
Add the attribute name ATTR to class CLASS.
Arguments: P, S
addparent R<CLASS1>, R<CLASS2>
Add class CLASS2 to the list of parent classes for CLASS1.
Arguments: P, P
and R<DEST>, R<VAL1>, R<VAL2>
Logical AND. Return VAL1 if it's false; otherwise, return VAL2.
Arguments: IR, I, I or P, P, P
asec R<DEST>, R<VAL>
The arc secant of VAL in radians.
Arguments: NR, I or NR, N
asin R<DEST>, R<VAL>
The arc sine of VAL in radians.
assign R<DEST>, R<VAL>
Assign a value to a PMC.
Arguments: SR, S or P, I or P, N or P, S or P, P
atan R<DEST>, R<VAL> atan R<DEST>, R<VAL1>, R<VAL2>
The arc tangent of VAL1 / VAL2 in radians (sign significant). If VAL2 is omitted, then just the arc tangent of VAL.
Arguments: NR, I or NR, N or NR, I, I or NR, I, N or NR, N, I or NR, N, N
band R<DEST>, R<VAL> band R<DEST>, R<VAL>, R<VAL>
Bitwise AND on two values. If only one VAL, bitwise AND on DEST and VAL.
Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P
bands R<DEST>, R<VAL> bands R<DEST>, R<VAL>, R<VAL>
Bitwise AND on two strings. If only one VAL, bitwise AND on DEST and VAL.
Arguments: SR, S or P, S or P, P or SR, S, S or P, P, S or P, P, P
bnot R<DEST>, R<VAL>
Bitwise NOT on VAL.
Arguments: IR, I or P, P
bnots R<DEST>, R<VAL>
Bitwise NOT on string VAL.
Arguments: SR, S or P, P
bor R<DEST>, R<VAL>, R<VAL>
Bitwise OR on two values. If only one VAL, bitwise OR on DEST and VAL.
Bitwise OR on two strings. If only one VAL, bitwise OR on DEST and VAL.
bounds R<INT>
Toggle bytecode bounds checking in the interpreter (0 for off, any other value for on).
Arguments: I
branch R<LABEL>
Branch to a label. The label is calculated as a relative offset.
branch_cs R<FIXUP_ENTRY>
Intersegment branch to the location of the given fixup table entry.
Arguments: S
bsr R<LABEL>
Branch to a label, like branch, but also push the current location onto the call stack so ret can return to it.
branch
ret
bxor R<DEST>, R<VAL> bxor R<DEST>, R<VAL>, R<VAL>
Bitwise XOR on two values. If only one VAL, bitwise XOR on DEST and VAL.
bxors R<DEST>, R<VAL> bxors R<DEST>, R<VAL>, R<VAL>
Bitwise XOR on two strings. If only one VAL, bitwise XOR on DEST and VAL.
callmethod callmethod R<METHODNAME>
Call the method named METHODNAME on the object stored in P2 according to the Parrot Calling Conventions. If no method name, pull the name from S0.
P2
S0
callmethodcc callmethodcc R<METHODNAME>
Call the method named METHODNAME on the object stored in P2 according to the Parrot Calling Conventions. If no method name, pull the name from S0. Also create a return continuation and store it in P1.
P1
can R<DEST>, R<OBJECT>, R<METHODNAME>
Return a true value if OBJECT can do the METHODNAME method, otherwise return a false value.
Arguments: IR, P, S
ceil R<DEST> ceil R<DEST>, R<VAL>
Set DEST to the smallest integral value less than or equal to VAL (if present) or itself (if not).
Arguments: NR or IR, N or NR, N
checkevents
Check the interpreter's task queue for unhandled events and run the associated event handlers.
chopn R<DEST>, R<VAL1> chopn R<DEST>, R<VAL1>, R<VAL2>
Remove VAL2 number of characters from string VAL1. If no VAL2, remove VAL number of characters from string DEST.
Arguments: SR, I or SR, S, I
chr R<DEST>, R<INT>
Return the character represented by the given number.
Arguments: SR, I
class R<CLASS>, R<OBJECT>
Return the CLASS of the given OBJECT.
classname R<NAME>, R<CLASS>
Set NAME to the classname of CLASS.
Arguments: SR, P
classoffset R<OFFSET>, R<OBJECT>, R<CLASS>
Return the offset OFFSET of the first attribute of class CLASS in object OBJECT.
clear_eh
Clear the most recent exception handler.
See also: set_eh, throw.
set_eh
throw
cleari clearn clearp clears
Clear all registers of the given type ("i" = integer, "n" = float, "p" = PMC, "s" = string). Integer and float registers clear to zero; string and PMC registers clear to NULL.
clone R<DEST>, R<VAL>
Clone (deep copy) a string or PMC and return the result.
close R<DEST>
Close the filehandle in the given register.
Arguments: P
cmod R<DEST>, R<VAL1>, R<VAL2>
C's built-in mod operator.
See also mod.
mod
Arguments: IR, I, I or NR, N, N or P, P, I or P, P, N or P, P, P
cmp R<DEST>, R<VAL1>, R<VAL2>
Set DEST to 1 if VAL1 is greater then VAL2, to -1 if it's less then VAL2 or to zero if both are equal. If VAL1 and VAL2 are both PMCs, then the type of comparison depends on VAL1.
Arguments: IR, I, I or IR, N, N or IR, S, S or IR, P, I or IR, P, N IR, P, S or IR, P, P
cmp_num R<DEST>, R<VAL1>, R<VAL2>
Like cmp, but forces numeric comparison.
cmp
Arguments: IR, P, P
cmp_str R<DEST>, R<VAL1>, R<VAL2>
Like cmp, but forces string comparison.
collect
Trigger a garbage collection (GC) run.
collectoff
Disable garbage collection runs (nestable).
collecton
Re-enable garbage collection runs.
compile R<DEST>, R<COMPILER>, R<SOURCE>
Compile a string of source code with a given compiler PMC and store the result.
Arguments: P, P, S
compreg R<DEST>, R<TYPE>
Return a compiler PMC for a particular type of source code.
compreg R<TYPE>, R<SUB>
Register SUB as a compiler for language TYPE.
Arguments: S, P
concat R<DEST>, R<VAL> concat R<DEST>, R<VAL>, R<VAL>
Concatenate two strings. If only one VAL, concatenate VAL onto DEST.
Arguments: SR, S or SR, S, S or P, P, S or P, P, P
conv_i1 R<DEST>, R<VAL> conv_i1_ovf R<DEST>, R<VAL>
Convert value to integer or number of given type i1, i2, i4, i8, u1, u2, u4, r4, r8. i corresponds to a signed integer, u to an unsigned integer and r to a float; the number indicates the size (in bytes) of the type. The variants with _ovf throw an exception if the conversion would overflow.
i1
i2
i4
i8
u1
u2
u4
r4
r8
i
u
r
_ovf
cos R<DEST>, R<VAL>
The cosine of VAL in radians.
cosh R<DEST>, R<VAL>
The hyperbolic cosine of VAL in radians.
debug R<FLAG>
Toggle debugging in the interpreter (0 for off, any other value for on).
dec R<DEST>
Decrement a value by 1.
Arguments: I or N or P
decodelocaltime R<DEST>, R<VAL>
Set DEST to a new array which represents the decoded time of the given epoch-seconds value shifted to local time.
Arguments: P, I
decodetime R<DEST>, R<VAL>
Set DEST to a new array which represents the decoded time of the given epoch-seconds value.
defined R<DEST>, R<PMC> defined R<DEST>, R<PMC>[R<KEY>]
Test a keyed PMC value for definedness. If no KEY, test a PMC for definedness.
Arguments: IR, P
delete R<DEST>[R<KEY>]
Delete a keyed value from an aggregate PMC.
delprop R<PMC>, R<NAME>
Delete a named property from a PMC.
See also: setprop and getprop.
setprop
getprop
depth R<DEST>
Return the depth of the user stack.
deref R<DEST>, R<REF>
Set DEST to the PMC that REF refers to.
die_hard R<LEVEL>, R<ERROR>
Die at a given level of severity, and with the given error code.
Arguments: I, I
See also: exit.
exit
div R<DEST>, R<VAL> div R<DEST>, R<VAL1>, R<VAL2>
Divide VAL1 by VAL2. If VAL2 is left out, divide DEST by VAL.
dlfunc R<DEST>, R<LIBRARY>, R<SYMBOL>, R<SIGNATURE>
Look up a symbol in a dynamic link library PMC and create a subroutine PMC for that symbol with the given signature.
Arguments: P, P, S, S
dlvar R<DEST>, R<LIBRARY>, R<SYMBOL>
Look up a symbol in a dynamic link library PMC and create a PMC for that symbol.
does R<DEST>, R<OBJECT>, R<VAL>
Return a true value if OBJECT does provide the interface VAL, otherwise return a false value.
Arguments: I, P, S
downcase R<DEST> downcase R<DEST>, R<VAL>
Create a copy of the string in VAL with all characters converted to lower case, and store it in DEST. If VAL is omitted, convert and replace the string in DEST.
Arguments: S or S, S
See also: upcase, titlecase.
upcase
titlecase
end
End execution within the current code segment or halt the interpreter if in the main code segment.
enternative
Run the run_native C function.
run_native
entrytype R<DEST>, R<INT>
Return the type of an entry on the user stack. INT specifies the position on the stack.
eq R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two values are equal.
Arguments: I, I, IC or N, N, IC or S, S, IC or P, I, IC or P, N, IC or P, S, IC or P, P, IC
eq_addr R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 and VAL2 point to the same string or PMC. Note that this op compares the addresses of the two strings or PMCs, not simply their values.
Arguments: S, S, IC or P, P, IC
eq_num R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two values are numerically equal.
Arguments: P, P, IC
eq_str R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two strings are equal.
err R<DEST> err R<DEST>, R<CODE>
Return the system error code to an integer destination or the system error message to a string destination. The two-argument version returns the system error message for a given code.
Arguments: IR or SR or SR, I
errorsoff R<VAL>
Turn off errors of type VAL.
errorson R<VAL>
Turn on errors of type VAL.
exchange R<REG>, R<REG>
Exchange the contents of two registers.
Arguments: IR, IR or NR, NR or SR, SR or P, P
exists R<DEST>, R<PMC>[R<KEY>]
Test a PMC key for existence.
exit R<STATUS>
Exit the interpreter with a given STATUS. (For extended exit status, throw an exception with severity EXCEPT_exit.)
EXCEPT_exit
See also: throw, die_hard.
die_hard
exp R<DEST>, R<VAL>
Base of the natural logarithm, e, to the power of VAL.
exsec R<DEST>, R<VAL>
The exsecant of VAL in radians.
Arguments: NR, N
fact R<DEST>, R<INT>
Return the factorial of INT.
Arguments: IR, I or NR, I
fdopen R<DEST>, R<INT>, R<MODE>
Get a ParrotIO object for handle INT with open mode MODE.
Arguments: P, I, S
find_chartype R<DEST>, R<NAME>
Find the chartype named NAME and return its number in DEST.
Arguments: IR, S
find_encoding R<DEST>, R<NAME>
Find the encoding named NAME and return its number in DEST.
find_global R<DEST>, R<NAME>
Return a global variable with the given name.
find_global R<DEST>, R<NAMESPACE>, R<NAME>
Return a global variable with the given name from the given namespace.
Arguments: P, S, S or P, P, S
See also: store_global.
store_global
find_lex R<DEST>, R<NAME> find_lex R<DEST>, R<DEPTH>, R<NAME> find_lex R<DEST>, R<DEPTH>, R<POSITION>
Return the lexical variable of the given name from a lexical scratchpad. If DEPTH is provided, only return a variable from the scratchpad at that depth. A find by position returns the variable at a particular position in the scratchpad.
Arguments: P, S or P, I, S or P, I, I
See also: store_lex.
store_lex
find_method R<DEST>, R<PMC>, R<NAME>
Look up a method by name in a PMC's vtable. Return a method PMC.
find_type R<DEST>, R<NAME>
Find the integer identifier for a PMC type or native Parrot datatype by name.
See also: typeof.
typeof
findclass R<DEST>, R<NAME>
Return 1 if the class NAME exists, and 0 otherwise.
floor R<DEST> floor R<DEST>, R<VAL>
Return the largest integral value less than or equal to VAL (if present) or itself (if not).
foldup R<DEST> foldup R<DEST>, R<SKIP>
Return a new array holding all passed subroutine parameters. SKIP defines an optional offset.
Arguments: P or P, I
freeze R<DEST>, R<VAL>
Create a frozen image DEST from PMC VAL.
See also: thaw.
thaw
gc_debug R<INT>
Toggle garbage collection debugging in the interpreter (0 for off, any other value for on).
gcd R<DEST>, R<VAL>, R<VAL>
Return the greatest common divisor of two values.
Arguments: IR, I, I or IR, N, N
ge R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is greater than or equal to VAL2.
ge_num R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is numerically greater than or equal to VAL2.
ge_str R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is stringwise greater than or equal to VAL2.
get_addr R<DEST>, R<SUB>
Get the absolute address of a subroutine PMC.
See also: set_addr.
set_addr
getattribute R<DEST>, R<OBJECT>, R<OFFS>
Get a reference to attribute number OFFS from object OBJECT.
Arguments: P, P, I
See also: setattribute, classoffset.
setattribute
classoffset
getclass R<DEST>, R<NAME>
Return the class PMC of the given name.
getfd R<DEST>, R<PIO>
Return the file the descriptor for the given ParrotIO object.
getfile R<DEST>
Return the name of the current file.
Arguments: SR
getinterp R<DEST>
Get a PMC representing the current interpreter.
getline R<DEST>
Return the current line number.
Arguments: IR
getpackage R<DEST>
Return the current package name.
getprop R<DEST>, R<NAME>, R<PMC>
Return the value of a named property on a PMC.
Arguments: P, S, P
See also: setprop and prophash.
prophash
getstderr R<DEST> getstdin R<DEST> getstdout R<DEST>
Get a ParrotIO object for the given standard handle.
gmtime R<DEST>, R<VAL>
Take the integer, which represents GMT epoch-seconds, and turn it into a formatted string.
See also: localtime.
localtime
gt R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is greater than VAL2.
gt_num R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is numerically greater than VAL2.
gt_str R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is stringwise greater than VAL2.
hav R<DEST>, R<VAL>
The haversine of VAL in radians.
if R<CONDITION>, R<LABEL>
Jump to a label if the condition is a true value.
Arguments: I, IC or N, IC or S, IC or P, IC
inc R<DEST>
Increment a value by one.
Arguments: IR or NR or P
index R<DEST>, R<STRING>, R<SEARCH> index R<DEST>, R<STRING>, R<SEARCH>, R<POS>
Return the position of the first occurrence of the string SEARCH in the string STRING, starting at the position POS. If the starting position is unspecified, start at the beginning of the string.
Arguments: IR, S, S or IR, S, S, I
interpinfo R<DEST>, R<FLAG>
Return information about the interpreter. An integer flag selects which information to return, as listed in CHP-11-TABLE-1Table 11-1.
Arguments: IR, I
invoke invoke R<SUB>
Call a subroutine, coroutine, or continuation stored in a PMC. If no PMC register is specified, it calls the subroutine in P0 and uses the standard calling conventions. Otherwise, no calling convention is defined. Also yield from a coroutine.
P0
yield
invokecc invokecc R<SUB>
Call a subroutine like invoke, but also generate a return continuation in P1.
invoke
See also: updatecc.
updatecc
isa R<DEST>, R<OBJECT>, R<CLASS>
Return a true value if OBJECT isa member of class CLASS, or of one of its subclasses, otherwise return a false value.
isnull R<VAL>, R<LABEL>
Jump to LABEL if the given PMC is a NULL PMC.
Arguments: P, IC
join R<DEST>, R<DELIM>, R<ARRAY>
Create a new string by joining all elements from array with the given delimiter.
Arguments: SR, S, P
jsr R<ADDRESS>
Jump to an address, like jump, but also push the current location onto the call stack so ret can return to it.
jump
jump R<ADDRESS>
Jump to a specified absolute address.
lcm R<DEST>, R<VAL>, R<VAL>
Return the least common multiple of two values.
Arguments: IR, I, I or NR, I, I
le R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is less than or equal to VAL2.
le_num R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is numerically less than or equal to VAL2.
le_str R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is stringwise less than or equal to VAL2.
length R<DEST>, R<STRING>
Return the character length of a string.
ln R<DEST>, R<VAL>
The natural logarithm of VAL.
load_bytecode R<FILE>
Load Parrot bytecode from a file.
loadlib R<DEST>, R<LIBRARY>
Load a dynamic link library by name and store it in a PMC.
See also: dlfunc.
dlfunc
localtime R<DEST>, R<VAL>
Take the integer, which represents GMT epoch-seconds, and turn it into a formatted string after adjusting to localtime.
See also: gmtime.
gmtime
log10 R<DEST>, R<VAL>
The base 10 logarithm of VAL.
log2 R<DEST>, R<VAL>
The base 2 logarithm of VAL.
lookback R<DEST>, R<OFFSET>
Retrieve an entry from the user stack by position. A positive offset counts from the top of the stack; a negative offset counts from the bottom.
Arguments: IR, I or NR, I or SR, I or P, I
lsr R<DEST>, R<BITS> lsr R<DEST>, R<VAL>, R<BITS>
Logically shift a value right by a given number of bits.
Arguments: IR, I or IR, I, I
lt R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is less than VAL2.
lt_num R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is numerically less than VAL2.
lt_str R<VAL1>, R<VAL2>, R<LABEL>
Jump to a label if VAL1 is stringwise less than VAL2.
mmdvtfind R<DEST>, R<FUNC>, R<LEFT>, R<RIGHT>
Get the subroutine PMC for the multi-method vtable function FUNC for the two given PMC types.
Arguments: P, I, I, I
mmdvtregister R<FUNC>, R<LEFT>, R<RIGHT>, R<SUB>
Register the subroutine SUB as the multi-method vtable function FUNC for the two given PMC types.
Arguments: I, I, I, P
mod R<DEST>, R<VAL> mod R<DEST>, R<VAL1>, R<VAL2>
Divide VAL1 by VAL2 and return the remainder. If VAL2 is omitted, divide DEST by VAL. The operation is defined as:
x mod y = x - y * floor(x / y)
Arguments: P, I or IR, I, I or NR, N, N or P, P, I or P, P, N
See also: cmod.
cmod
mul R<DEST>, R<VAL> mul R<DEST>, R<VAL>, R<VAL>
Multiply two values and return the result. If only one VAL, multiply DEST by VAL.
ne R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two values are not equal.
ne_addr R<VAL>, R<VAL>, R<LABEL>
Jump to a label if VAL1 and VAL2 do not point to the same string or PMC.
ne_num R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two values are numerically different.
ne_str R<VAL>, R<VAL>, R<LABEL>
Jump to a label if the two strings are not equal.
needs_destroy R<PMC>
Mark the PMC as requiring timely destruction.
See also: sweep.
sweep
neg R<DEST> neg R<DEST>, R<VAL>
Return the negative of a number. If there is no VAL, DEST is the negative of itself.
Arguments: IR or NR or P or IR, I or NR, N or P, P
new R<DEST>, R<TYPE> new R<DEST>, R<TYPE>, R<INITIALIZE> new R<DEST>, R<TYPE>, R<INITIALIZE>, R<PROPS>
Create a new PMC of type TYPE. INITIALIZE is an array PMC containing initialization data for the new PMC. PROPS is a propety hash.
Arguments: P, I or P, I, P or P, I, P, P
new R<DEST> new R<DEST>, R<LENGTH> new R<DEST>, R<LENGTH>, R<ENCODING> new R<DEST>, R<LENGTH>, R<ENCODING>, R<TYPE>
Allocate a new empty string with a given LENGTH, ENCODING, and TYPE.
Arguments: SR or SR, I or SR, I, I or SR, I, I, I
new_callback R<DEST>, R<SUB>, R<DATA>, R<SIG>
Create a callback stub DEST for a PASM subroutine SUB with user data DATA and function signature SIG.
Arguments: P, P, P, S
new_pad R<DEPTH> new_pad R<DEST>, R<DEPTH>
Create a new lexical scratchpad. If a destination PMC is provided, store the pad in the PMC, otherwise push it onto the pad stack. DEPTH specifies the static nesting depth for the pad (lower static depths are copied from the current static nesting).
Arguments: I or P, I
newclass R<DEST>, R<NAME>
Create a new class with the given name.
newsub R<DEST>, R<CLASS>, R<LABEL>
Generate a new subroutine object of the given CLASS, located at the given LABEL, and store the object in the destination PMC.
Arguments: P, I, IC
newsub R<CLASS>, R<RETCLASS>, R<LABEL>, R<RETADDR>
Generate a new subroutine object of the given CLASS, located at the given LABEL, and store the object in P0. Also generate a return continuation of class RETCLASS with the return address RETADDR and store it in P1.
Arguments: I, I, IC, IC
noop
Do nothing.
not R<DEST>, R<VAL>
Logical NOT. True if VAL is false.
null R<DEST>
Set DEST (which must be a register) to 0, 0.0 or a NULL pointer, depending on its type.
Arguments: IR or NR or SR or P
open R<DEST>, R<FILENAME> open R<DEST>, R<FILENAME>, R<MODE>
Open a file in the specified mode ("<", ">", etc.) and return a filehandle. Without the mode it defaults to read/write.
Arguments: P, S, S or P, S
or R<DEST>, R<VAL1>, R<VAL2>
Logical OR. Return VAL1 if it's true; otherwise, return VAL2.
ord R<DEST>, R<STRING> ord R<DEST>, R<STRING>, R<POS>
Return the character at position POS in STRING. If POS isn't specified, return the 0th character.
Arguments: IR, S or IR, S, I
peek R<DEST> peek R<DEST>, R<PIO>
Read the next byte from the given ParrotIO object or from stdin but don't remove it.
stdin
Arguments: SR or SR, P
peek_pad R<DEST>
Store the current lexical scope pad in a PMC.
pin R<DEST>
Make the string in DEST immobile. This prevents the garbage collector from moving it to a different location in memory (which it otherwise may choose to do).
See also: unpin.
unpin
pioctl R<DEST>, R<PIO>, R<VAL>, R<VAL>
Perform an operation on an IO object. This is a general purpose hook for setting various flags, modes, etc.
Arguments: IR, P, I, I
pop R<DEST>, R<PMC>
Pop the last entry off an aggregate PMC and return it.
Arguments: IR, P or NR, P or SR, P or P, P
pop_pad
Pop the current lexical scope pad off the lexical scope stack.
See also: peek_pad.
peek_pad
popi popn popp pops
Restore all the registers of one type from the stack ("i" = integer, "n" = float, "p" = PMC, "s" = string).
popbottomi popbottomn popbottomp popbottoms
Restore registers in the range 0..15.
poptopi poptopn poptopp poptops
Restore registers in the range 16..31.
See also: pushX.
push
pow R<DEST>, R<VAL1>, R<VAL2>
Return VAL1 raised to the power of VAL2.
Arguments: NR, I, I or NR, I, N or NR, N, I or NR, N, N
print R<VAL> print R<IO>, R<VAL>
Print a value to an I/O object or file descriptor. If no IO is given, print the value to standard output.
Arguments: I or N or S or P or P, I or P, N or P, S or P, P
printerr R<VAL>
Print a value to stderr.
stderr
Arguments: I or N or S or P
profile R<INT>
Toggle profiling in the interpreter (0 for off, any other value for on).
prophash R<DEST>, R<PMC>
Return a hash containing all the properties from a PMC.
See also: getprop.
push R<PMC>, R<VAL>
Push a value onto the end of an aggregate PMC.
Arguments: P, I or P, N or P, S or P, P
push_pad R<PAD>
Push a scratchpad stored in a PMC onto the lexical scope stack.
pushi pushn pushp pushs
Save all the registers of one type to the stack ("i" = integer, "n" = float, "p" = PMC, "s" = string). Restore with popX.
pop
pushbottomi pushbottomn pushbottomp pushbottoms
Push registers 0..15.
pushtopi pushtopn pushtopp pushtops
Push registers 16..31.
read R<DEST>, R<BYTES> read R<DEST>, R<IO>, R<BYTES>
Read the specified number of bytes from a Parrot I/O object. Read from stdin if no IO is provided.
Arguments: SR, I or SR, P, I
readline R<DEST>, R<IO>
Read a line from a Parrot I/O object.
register R<PMC>
Register the given PMC in the interpreter's root set, so that it's visible during DOD.
See also: unregister.
unregister
removeparent R<CLASS1>, R<CLASS2>
Remove CLASS2 from class CLASS1's list of parents.
CLASS1
repeat R<DEST>, R<VAL>, R<REPEAT>
Repeat a string REPEAT number of times.
Arguments: SR, S, I or P, P, I or P, P, P
restore R<DEST>
Restore a register from the user stack.
restoreall
Restore all the registers. Does a popX for every type.
restoretop
Restore registers 16..31. Does a popX for every type.
See also: savetop.
savetop
Pop a location off the top of the call stack, and go there. Often used with bsr and jsr.
bsr
jsr
rethrow R<EXCEPTION>
Rethrow an exception. Only valid inside an exception handler.
See also: throw
rotate_up R<COUNT>
Rotate the top COUNT entries on the user stack. A positive number rotates up: the top entry becomes the COUNTth entry, and the others move up one (the second entry becomes first, the third becomes the second, etc.). A negative number rotates down: the COUNTth entry becomes the top, and the others move down (the first becomes second, etc.).
runinterp R<INTERPRETER>, R<OFFSET>
Use an interpreter stored in PMC to run code starting at a given offset.
See also: newinterp.
newinterp
save R<VAL>
Save a value onto the user stack.
saveall
Save all the registers. Does a pushX for every type.
savec R<VAL>
Save a clone of a value onto the user stack.
Arguments: S or P
Save registers 16..31. Does a pushX for every type.
sec R<DEST>, R<VAL>
The secant of VAL in radians.
sech R<DEST>, R<VAL>
The hyperbolic secant of VAL in radians.
seek R<DEST>, R<IO>, R<OFFSET>, R<STARTFLAG> seek R<DEST>, R<IO>, R<UPPER32>, R<LOWER32>, R<STARTFLAG>
Set the file position of a Parrot I/O object to a given offset from a starting position (STARTFLAG: 0 is the beginning of the file, 1 is current the position, 2 is the end of the file). DEST is the success or failure of the seek.
64-bit seek combines UPPER32 and LOWER32 to get one 64-bit OFFSET.
seek
Arguments: P, I, I or P, I, I, I
set R<DEST>, R<VAL>
Set a register to a value.
Arguments: IR, I or IR, N or IR, S or IR, P or NR, I or NR, N or NR, S or NR, P or SR, I or SR, N or SR, S or SR, P or P, I or P, N or P, S or P, P
set R<DEST[KEY]>, R<VAL>
A keyed set operation on a PMC.
set R<DEST>, R<PMC[KEY]>
A keyed get operation on a PMC.
Arguments: I, P or N, P or S, P or P, P
seti_ind R<REG>, R<VAL> setn_ind R<REG>, R<VAL> sets_ind R<REG>, R<VAL> setp_ind R<REG>, R<VAL>
Set register number REG of the specified type to VAL. Bypasses the register allocator, so use with care.
Arguments: I, I or I, S or I, N or I, P
set_addr R<DEST>, R<LABEL>
Return the current address plus the offset to LABEL. Often used to calculate absolute addresses for jump or jsr.
Arguments: IR, IC
set_addr R<SUB>, R<LABEL>
Set the subroutine address pointing to the given label.
set_chartype R<STRING>, R<CHARTYPE>
Set the chartype of a string.
Arguments: S, I
set_eh R<HANDLER>
Push an exception handler on the control stack.
See also: clear_eh, throw.
set_encoding R<STRING>, R<ENCODING>
Set the encoding of a string.
setattribute R<OBJECT>, R<OFFSET>, R<ATTRIBUTE>
Set the given attribute at OFFSET for object OBJECT.
Arguments: P, I, P
See also: getattribute, classoffset.
getattribute
setprop R<PMC>, R<NAME>, R<VALUE>
Set the value of a named property on a PMC.
See also: getprop and delprop.
delprop
shift R<DEST>, R<PMC>
Shift a value off the front of an aggregate PMC.
shl R<DEST>, R<VAL>, R<BITS>
Bitwise shift a value left by a given number of bits.
shr R<DEST>, R<VAL>, R<BITS>
Bitwise shift a value right by a given number of bits.
sin R<DEST>, R<VAL>
The sine of VAL in radians.
singleton R<DEST>
Take the given object and put it into its own singleton class.
sinh R<DEST>, R<VAL>
The hyperbolic sine of VAL in radians.
sizeof R<DEST>, R<TYPE>
Set DEST to the size in bytes of the given natural type.
sleep R<SECONDS>
Sleep for the given number of seconds.
Arguments: I or N
spawnw R<DEST>, R<COMMAND>
Spawn a subprocess to run the given COMMAND, wait for it to finish, and return the result.
splice R<DEST>, R<REPLACE>, R<OFFSET>, R<COUNT>
Starting at OFFSET, replace COUNT number of values in the destination PMC with values provided in the REPLACE PMC.
Arguments: P, P, I, I
sprintf R<DEST>, R<FORMAT>, R<ARGS>
Format arguments in an aggregate PMC, using format string FORMAT.
Arguments: SR, S, P or P, P, P
store_global R<NAME>, R<OBJECT> store_global R<NAME>, R<NAMESPACE>, R<OBJECT>
Store a global variable as a named symbol.
Arguments: S, P or S, S, P or P, S, P
See also: find_global.
find_global
store_lex R<NAME>, R<OBJECT> store_lex R<DEPTH>, R<NAME>, R<OBJECT> store_lex R<DEPTH>, R<POSITION>, R<OBJECT>
Store an object as a lexical variable with a given name. If the symbol doesn't exist, it will be created in the lexical scratchpad at the specified depth (a negative depth counts back from the current scope). If DEPTH isn't provided, the symbol must already exist. If a position is provided instead of a name, the symbol will be stored at the given position in the scratchpad.
Arguments: S, P or I, I, P or I, S, P
See also: find_lex.
find_lex
string_chartype R<DEST>, R<STRING>
Return the chartype of the string.
string_encoding R<DEST>, R<STRING>
Return the encoding of the string.
stringinfo R<DEST>, R<STRING>, R<FLAG>
Return information about a string. An integer flag selects which information to return, as listed in CHP-11-TABLE-2Table 11-2.
Arguments: IR, S, I
sub R<DEST>, R<VAL> sub R<DEST>, R<VAL1>, R<VAL2>
Subtract VAL2 from VAL1. If no VAL2, subtract VAL from DEST.
subclass R<DEST>, R<CLASS> subclass R<DEST>, R<CLASS>, R<NAME>
Create a sublass of CLASS. Without NAME an anonymous subclass is created.
Arguments: P, S or P, P or P, S, S or P, P, S
substr R<DEST>, R<STRING>, R<OFFSET> substr R<DEST>, R<STRING>, R<OFFSET>, R<LENGTH>
Return a substring of STRING, beginning at OFFSET and with length LENGTH.
Arguments: SR, S, I or SR, S, I, I or SR, P, I, I
substr R<DEST>, R<STRING>, R<OFFSET>, R<LENGTH>, R<REPLACE>
If REPLACE is given, use it to replace the returned substring in STRING.
Arguments: SR, S, I, I, S
substr R<DEST>, R<OFFSET>, R<LENGTH>, R<REPLACE>
If STRING is omitted, operate on the string in DEST.
Arguments: SR, I, I, S
substr_r R<DEST>, R<STRING>, R<OFFSET>, R<LENGTH>
Acts like substr, but reuses the destination string instead of creating a new string.
substr
Arguments: SR, S, I, I
sweep R<LAZY>
Trigger a dead object detection (DOD) sweep. If LAZY is set to 1, only objects that need timely destruction may be destroyed.
Arguments: IC
sweepoff
Disable DOD sweeps (nestable).
sweepon
Re-enable DOD sweeps.
sysinfo R<DEST>, R<ITEM>
Return OS-specific details given by ITEM.
ITEM
Arguments: IR, I or SR, I
tan R<DEST>, R<VAL>
The tangent of VAL in radians.
tanh R<DEST>, R<VAL>
The hyperbolic tangent of VAL in radians.
tell R<DEST>, R<PIO> tell R<UPPER32>, R<LOWER32>, R<PIO>
Return the file position of the given ParrotIO object.
Arguments: IR, P or IR, I, P
See also: seek.
thaw R<DEST>, R<STR>
Create a new PMC representing the frozen image.
See also: freeze.
freeze
throw R<EXCEPTION>
Throw an exception.
See also: rethrow, set_eh, clear_eh
rethrow
time R<DEST>
Return the current system time.
Arguments: IR or NR
titlecase R<DEST> titlecase R<DEST>, R<VAL>
Create a copy of the string in VAL with all characters converted to title case, and store it in DEST. If VAL is omitted, convert and replace the string in DEST.
Arguments: SR or SR, S
See also: upcase, downcase.
downcase
trace R<INT>
Toggle tracing in the interpreter (0 for off, any other value for on).
transcode R<DEST>, R<ENCODING> transcode R<DEST>, R<SOURCE>, R<ENCODING> transcode R<DEST>, R<SOURCE>, R<ENCODING>, R<CHARTYPE>
Transcode a string to the given CHARTYPE and ENCODING. If CHARTYPE is omitted, it is assumed to be the same as the original.
Arguments: SR, I or SR, S, I or SR, S, I, I
typeof R<DEST>, R<VAL> typeof R<DEST>, R<PMC[KEY]>
Return the type of a PMC or Parrot data type, either its class name (to a string destination) or integer identifier (to an integer destination).
Arguments: IR, P or SR, I or SR, P
unless R<CONDITION>, R<LABEL>
Jump to a label unless the condition is a true value.
unpin R<DEST>
Make the string in DEST movable again. This is the default, so unpin is a no-op unless the string has been pinned with pin.
pin
See also: pin.
unregister R<PMC>
Remove one reference to PMC from the root set registry.
See also: register.
register
unshift R<DEST>, R<VAL>
Unshift a value onto the front of an aggregate PMC.
upcase R<DEST> upcase R<DEST>, R<VAL>
Create a copy of the string in VAL with all characters converted to upper case, and store it in DEST. If VAL is omitted, convert and replace the string in DEST.
See also: downcase, titlecase.
Update the state of a return continuation stored in P1. Used when context information changes after the return continuation is created but before it's invoked.
See also: invokecc.
invokecc
valid_type R<DEST>, R<TYPE>
Check whether a PMC type or native Parrot datatype is a valid one.
vers R<DEST>, R<VAL>
The versine of VAL in radians.
warningsoff R<CATEGORY>
Turn off a particular category of warnings by category number. Turning off one category will not affect the status of other warnings categories. See warningson for the list of categories.
warningson
warningson R<CATEGORY>
Turn on a particular category of warnings by category number. The default is all warnings off. Turning on one category will not turn off other categories. Combine category numbers with a bitwise OR to turn on more than one at a time. If you include warnings.pasm, the category numbers are available by name as:
.PARROT_WARNINGS_ALL_FLAG .PARROT_WARNINGS_UNDEF_FLAG .PARROT_WARNINGS_IO_FLAG .PARROT_WARNINGS_PLATFORM_FLAG
xor R<DEST>, R<VAL1>, R<VAL2>
Logical XOR. If VAL1 is true and VAL2 is false, return VAL1. If VAL1 is false and VAL2 is true, return VAL2. Otherwise, return a false value.
This is a summary of PIR directives. Directives are preprocessed by the Parrot interpreter. Since PIR and PASM run on the same interpreter, many of the directives listed here are also valid in PASM code.
.arg R<VAL>
Push a value onto the user stack or set it according to PCC.
.const R<TYPE>R<NAME> = R<VALUE>
Define a named constant.
.constant R<NAME>R<VALUE>
Define a named macro that expands to a given value. Macros are called as directives, i.e. .NAME (PASM code only).
.emit
Define a compilation unit of PASM code. Always paired with .eom.
.eom
.end
End a compilation unit. Always paired with .sub.
.sub
.endm
End a macro definition. Always paired with .macro.
.macro
End a compilation unit of PASM code. Always paired with .emit.
.flatten_arg R<PArray>
Flatten the passed array PMC and provide args for PCC calls.
.globalconst R<TYPE>R<NAME> = R<VALUE>
Define a named, file visible constant.
.include " R<FILENAME> "
Include the contents of an external file by inserting it in place.
.invocant R<OBJ>
Set the invocant for a method call.
.local R<TYPE>R<NAME>
Define a local named variable.
.macro R<NAME> (R<PARAMS>)
Define a named macro with a list of parameters. The macro is called as .NAME(arg1,arg2,...). Always paired with .endm.
.meth_call R<SUB> .meth_call R<SUB>, R<RETCONT>
Create a method call.
.namespace R< [ "namespace" ] >
Define a namespace.
.nci_call R<SUB>
Create an NCI call.
.param R<DEST> .param R<TYPE>R<NAME>
Pop a value off the user stack into a register or typed identifier.
Start a call sequence. Always paired with .pcc_end
.pcc_end
Start a return sequence. Always paired with .pcc_end_return
.pcc_end_return
Start a return of a coroutine sequence. Always paired with .pcc_end_yield
.pcc_end_yield
.pcc_call R<SUB> .pcc_call R<SUB>, R<RETCONT>
Create a subroutine call.
.pcc_sub R<_LABEL>
Create a symbol entry for subroutine at the _LABEL. This directive is for PASM code only.
.pragma fastcall .pragma prototyped
Set default calling conventions.
.result R<DEST>
Pop a value off the user stack or get it according to PCC.
.return R<VAL>
Return a value to the calling subroutine by pushing it onto the user stack or set it according to PCC.
.sub R<NAME>
Define a compilation unit. Always paired with .end. Names begin with "_" by convention.
_
.sym R<TYPE> R<NAME>
Same as .local.
.local
This section is a quick reference to PIR instructions. For more details and the latest changes, see imcc/docs/syntax.pod or dive into the source code in imcc/imcc.l and imcc/imcc.y.
R<DEST> = R<VAL>
Assign a value to a particular register, temporary register, or named variable.
R<DEST> = R<VAL> + R<VAL> R<DEST> += R<VAL>
Add two numbers or PMCs.
R<DEST> = R<VAL1> - R<VAL2> R<DEST> -= R<VAL1> R<DEST> = - R<VAL>
Subtract VAL1 from VAL2. The unary "-" negates a number.
-
R<DEST> = R<VAL> * R<VAL> R<DEST> *= R<VAL>
Multiply two numbers or PMCs.
R<DEST> = R<VAL1> / R<VAL2> R<DEST> /= R<VAL1>
Divide VAL1 by VAL2.
R<DEST> = R<VAL1> ** R<VAL2>
Raise VAL1 to the power of VAL2.
R<DEST> = R<VAL1> % R<VAL2> R<DEST> %= R<VAL1>
Divide VAL1 by VAL2 and return the (mod) remainder.
R<DEST> = R<VAL> . R<VAL> R<DEST> .= R<VAL>
Concatenate two strings. The concat operator must be surrounded by whitespace.
if R<VAL1> E<lt> R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is less than VAL2.
if R<VAL1> E<lt>= R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is less than or equal to VAL2.
if R<VAL1> E<gt> R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is greater than VAL2.
if R<VAL1> E<gt>= R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is greater than or equal to VAL2.
if R<VAL1> == R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is equal to VAL2.
if R<VAL1> != R<VAL2> goto R<LABEL>
Conditionally branch to a label if VAL1 is not equal to VAL2.
R<DEST> = R<VAL1> && R<VAL2>
Logical AND. Return VAL1 if it's false, otherwise return VAL2.
R<DEST> = R<VAL1> || R<VAL2>
Logical OR. Return VAL1 if it's true, otherwise return VAL2.
R<DEST> = R<VAL1> ~~ R<VAL2>
R<DEST> = ! R<VAL>
Logical NOT. Return a true value if VAL is false.
R<DEST> = R<VAL> & R<VAL> R<DEST> &= R<VAL>
Bitwise AND on two values.
R<DEST> = R<VAL> | R<VAL> R<DEST> |= R<VAL>
Bitwise OR on two values.
R<DEST> = R<VAL> ~ R<VAL> R<DEST> ~= R<VAL> R<DEST> = ~ R<VAL>
Bitwise XOR on two values. The unary form is a bitwise NOT on a value.
R<DEST> = R<VAL1> E<lt>E<lt> R<VAL2> R<DEST> E<lt>E<lt>= R<VAL2>
Bitwise shift VAL1 left by VAL2 number of bits.
R<DEST> = R<VAL1> E<gt>E<gt> R<VAL2> R<DEST> E<gt>E<gt>= R<VAL2>
Bitwise shift VAL1 right by VAL2 number of bits.
R<DEST> = R<VAL1> E<gt>E<gt>E<gt> R<VAL2> R<DEST> E<gt>E<gt>E<gt>= R<VAL2>
Logically shift VAL1 right by VAL2 number of bits.
R<DEST> = R<PMC> [ R<KEY> ] R<PMC> [ R<KEY> ] = R<VAL>
Indexed access to a PMC and indexed assignment to a PMC.
DEST = STRING [ OFFSET ] STRING [ OFFSET ] = VAL
Access a one-character substring on a string, starting at a particular offset, or assign to that substring.
R<DEST> = addr R<LABEL>
Return the address of a label.
call R<NAME>
Call the named subroutine (a .sub label).
R<DEST> = global R<NAME> global R<NAME> = R<VAL>
Access a global variable for read or write.
goto R<NAME>
Jump to the named identifier (label or subroutine name).
if R<EXPR> goto R<NAME>
If the value or expression evaluates as true, jump to the named identifier.
unless R<VAL> goto R<NAME>
Unless the value evaluates as true, jump to the named identifier.
Since Parrot is both an assembler and a bytecode interpreter, it has options to control both behaviors. Some options may have changed by the time you read this, especially options related to debugging and optimization. The document imcc/docs/running.pod should have the latest details. Or just run parrot --help.
parrot [options] file [arguments]
The file is either an .imc (.pir) or .pasm source file or a Parrot bytecode file. Parrot creates an Array object to hold the command-line arguments and stores it in P5 on program start.
Array
P5
Assume PASM input on stdin. When Parrot runs a source file with a .pasm extension, it parses the file as pure PASM code. This switch turns on PASM parsing (instead of the default PIR parsing) when a source file is read from stdin.
Assume PBC file on stdin. When Parrot runs a bytecode file with a .pbc extension, it immediately executes the file. This option tells Parrot to immediately execute a bytecode file piped in on stdin.
Turn on debugging output. The -d switch takes an optional argument, which is a hex value of debug bits. The individual bits are shown in CHP-11-TABLE-3Table 11-3. When hexbits isn't specified, the default debugging level is 0001. If hexbits is separated from the -d switch by whitespace, it has to start with a number.
-d
To produce a huge output on stderr, turn on all the debugging bits:
$ parrot -d 0ffff ...
Show debug option bits.
Print a short summary of options to stdout and exit.
stdout
Act like an assembler. With this switch Parrot won't run code unless it's combined with the -r switch. If the name of outputfile ends with a .pbc extension, Parrot writes a Parrot bytecode file. If outputfile ends with a .pasm extension, Parrot writes a PASM source file, even if the input file was also PASM. This can be handy to check various optimizations when you run Parrot with the -Op switch.
-r
-Op
If the extension is .o or equivalent, Parrot generates an object file from the JITed program code, which can be used to create a standalone executable program. This isn't available on all platforms yet; see PLATFORMS for which platforms support this.
Immediately execute bytecode. This is the default unless -o is present. The combination of -r -o output.pbc writes a bytecode file and executes the generated PBC.
-o
output.pbc
One -v switch (imcc -v) shows which files are worked on and prints a summary of register usage and optimization statistics. Two -v switches (imcc -v -v) also prints a line for each individual processing step.
-v
imcc
Turn on yydebug for yacc/bison.
yydebug
Show output of macro expansions and quit.
Print the program version to stdout and exit.
Turn on optimizations. The flags currently implemented are shown in CHP-11-TABLE-4Table 11-4.
The interpreter options are mainly for selecting which run-time core to use for interpreting bytecode. The current default is the computed goto core if it's available. Otherwise the fast core is used.
Activate bounds checking. This also runs with the slow core as a side effect.
Run with the fast core.
Run the computed goto core (CGoto).
Run with the JIT core if available.
Activate profiling. This prints a summary of opcode usage and execution times after the program stops. It also runs within the slow core.
Run with the CGoto-Prederefed core.
Run with the Prederefed core.
Run with the Switched core.
Trace execution. This also turns on the slow core.
Turn on warnings.
Turn off DOD/GC. This is for debugging only.
Wait for a keypress before running.
Cleanup up allocated memory when the final interpreter is destroyed. Parrot destroys created interpreters (e.g. threads) on exit but doesn't normally free all memory for the last terminating interpreter, since the operating system will do this anyway. This can create false positives when Parrot is run with a memory leak detector. To prevent this, use this option.
Parrot
167 POD Errors
The following errors were encountered while parsing the POD:
Unknown directive: =head0
A non-empty Z<>
Deleting unknown formatting code A<>
Deleting unknown formatting code R<>
To install Parrot::Op, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parrot::Op
CPAN shell
perl -MCPAN -e shell install Parrot::Op
For more information on module installation, please visit the detailed CPAN module installation guide.