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

PASM Opcodes

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.

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.

abs

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

acos R<DEST>, R<VAL>

The arc cosine of VAL in radians.

Arguments: NR, N or NR, I

add

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

addattribute R<CLASS>, R<ATTR>

Add the attribute name ATTR to class CLASS.

Arguments: P, S

addparent

addparent R<CLASS1>, R<CLASS2>

Add class CLASS2 to the list of parent classes for CLASS1.

Arguments: P, P

and

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

asec R<DEST>, R<VAL>

The arc secant of VAL in radians.

Arguments: NR, I or NR, N

asin

asin R<DEST>, R<VAL>

The arc sine of VAL in radians.

Arguments: NR, I or NR, N

assign

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

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

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

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

bnot R<DEST>, R<VAL>

Bitwise NOT on VAL.

Arguments: IR, I or P, P

bnots

bnots R<DEST>, R<VAL>

Bitwise NOT on string VAL.

Arguments: SR, S or P, P

bor

bor R<DEST>, R<VAL>, R<VAL>

Bitwise OR on two values. If only one VAL, bitwise OR 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

bors

bor R<DEST>, R<VAL>, R<VAL>

Bitwise OR on two strings. If only one VAL, bitwise OR 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

bounds

bounds R<INT>

Toggle bytecode bounds checking in the interpreter (0 for off, any other value for on).

Arguments: I

branch

branch R<LABEL>

Branch to a label. The label is calculated as a relative offset.

Arguments: I

branch_cs

branch_cs R<FIXUP_ENTRY>

Intersegment branch to the location of the given fixup table entry.

Arguments: S

bsr

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.

Arguments: I

bxor

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.

Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P

bxors

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.

Arguments: SR, S or P, S or P, P or SR, S, S or P, P, S or P, P, P

callmethod

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.

Arguments: S

callmethodcc

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.

Arguments: S

can

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

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

checkevents

Check the interpreter's task queue for unhandled events and run the associated event handlers.

chopn

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

chr R<DEST>, R<INT>

Return the character represented by the given number.

Arguments: SR, I

class

class R<CLASS>, R<OBJECT>

Return the CLASS of the given OBJECT.

Arguments: P, P

classoffset

classoffset R<OFFSET>, R<OBJECT>, R<CLASS>

Return the offset OFFSET of the first attribute of class CLASS in object OBJECT.

Arguments: IR, P, S

clear_eh

clear_eh

Clear the most recent exception handler.

clearX

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

clone R<DEST>, R<VAL>

Clone (deep copy) a string or PMC and return the result.

Arguments: SR, S or P, P

close

close R<DEST>

Close the filehandle in the given register.

Arguments: P

cmod

cmod R<DEST>, R<VAL1>, R<VAL2>

C's built-in mod operator.

cmp

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

cmp_num R<DEST>, R<VAL1>, R<VAL2>

Like cmp, but forces numeric comparison.

Arguments: IR, P, P

cmp_str

cmp_str R<DEST>, R<VAL1>, R<VAL2>

Like cmp, but forces string comparison.

Arguments: IR, P, P

collect

collect

Trigger a garbage collection (GC) run.

collectoff

collectoff

Disable garbage collection runs (nestable).

collecton

collecton

Re-enable garbage collection runs.

compile

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

compreg R<DEST>, R<TYPE>

Return a compiler PMC for a particular type of source code.

Arguments: P, S

compreg R<TYPE>, R<SUB>

Arguments: S, P

concat

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_*

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.

cos

cos R<DEST>, R<VAL>

The cosine of VAL in radians.

Arguments: NR, I or NR, N

cosh

cosh R<DEST>, R<VAL>

The hyperbolic cosine of VAL in radians.

Arguments: NR, I or NR, N

debug

debug R<FLAG>

Toggle debugging in the interpreter (0 for off, any other value for on).

Arguments: I

dec

dec R<DEST>

Decrement a value by 1.

Arguments: I or N or P

decodelocaltime

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

decodetime R<DEST>, R<VAL>

Set DEST to a new array which represents the decoded time of the given epoch-seconds value.

Arguments: P, I

defined

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

delete R<DEST>[R<KEY>]

Delete a keyed value from an aggregate PMC.

Arguments: P

delprop

delprop R<PMC>, R<NAME>

Delete a named property from a PMC.

Arguments: P, S

depth

depth R<DEST>

Return the depth of the user stack.

Arguments: I

deref

deref R<DEST>, R<REF>

Set DEST to the PMC that REF refers to.

Arguments: P, P

die_hard

die_hard R<LEVEL>, R<ERROR>

Die at a given level of severity, and with the given error code.

Arguments: I, I

div

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.

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

dlfunc

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

dlvar R<DEST>, R<LIBRARY>, R<SYMBOL>

Look up a symbol in a dynamic link library PMC and create a PMC for that symbol.

Arguments: P, P, S

does

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

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

end

end

End execution within the current code segment or halt the interpreter if in the main code segment.

enternative

enternative

Run the run_native C function.

entrytype

entrytype R<DEST>, R<INT>

Return the type of an entry on the user stack. INT specifies the position on the stack.

Arguments: I, I

eq

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

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

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

eq_str R<VAL>, R<VAL>, R<LABEL>

Jump to a label if the two strings are equal.

Arguments: P, P, IC

err

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

errorsoff R<VAL>

Turn off errors of type VAL.

Arguments: I

errorson

errorson R<VAL>

Turn on errors of type VAL.

Arguments: I

exchange

exchange R<REG>, R<REG>

Exchange the contents of two registers.

Arguments: IR, IR or NR, NR or SR, SR or P, P

exists

exists R<DEST>, R<PMC>[R<KEY>]

Test a PMC key for existence.

Arguments: IR, P

exit

exit R<STATUS>

Exit the interpreter with a given STATUS. (For extended exit status, throw an exception with severity EXCEPT_exit.)

Arguments: I

exp

exp R<DEST>, R<VAL>

Base of the natural logarithm, e, to the power of VAL.

Arguments: NR, I or NR, N

exsec

exsec R<DEST>, R<VAL>

The exsecant of VAL in radians.

Arguments: NR, N

fact

fact R<DEST>, R<INT>

Return the factorial of INT.

Arguments: IR, I or NR, I

fdopen

fdopen R<DEST>, R<INT>, R<MODE>

Get a ParrotIO object for handle INT with open mode MODE.

Arguments: P, I, S

find_chartype

find_chartype R<DEST>, R<NAME>

Find the chartype named NAME and return its number in DEST.

Arguments: IR, S

find_encoding

find_encoding R<DEST>, R<NAME>

Find the encoding named NAME and return its number in DEST.

Arguments: IR, S

find_global

find_global R<DEST>, R<NAME>

Return a global variable with the given name.

Arguments: P, S

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

find_lex

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

find_method

find_method R<DEST>, R<PMC>, R<NAME>

Look up a method by name in a PMC's vtable. Return a method PMC.

Arguments: P, P, S

find_type

find_type R<DEST>, R<NAME>

Find the integer identifier for a PMC type or native Parrot datatype by name.

Arguments: IR, S

findclass

findclass R<DEST>, R<NAME>

Return 1 if the class NAME exists, and 0 otherwise.

Arguments: IR, S

floor

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

Arguments: NR or IR, N or NR, N

foldup

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

freeze R<DEST>, R<VAL>

Create a frozen image DEST from PMC VAL.

Arguments: SR, P

gc_debug

gc_debug R<INT>

Toggle garbage collection debugging in the interpreter (0 for off, any other value for on).

Arguments: I

gcd

gcd R<DEST>, R<VAL>, R<VAL>

Return the greatest common divisor of two values.

Arguments: IR, I, I or IR, N, N

ge

ge R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is greater than or equal to VAL2.

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

ge_num

ge_num R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is numerically greater than or equal to VAL2.

Arguments: P, P, IC

ge_str

ge_str R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is stringwise greater than or equal to VAL2.

Arguments: P, P, IC

get_addr

get_addr R<DEST>, R<SUB>

Get the absolute address of a subroutine PMC.

Arguments: IR, P

getattribute

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.

getclass

getclass R<DEST>, R<NAME>

Return the class PMC of the given name.

Arguments: P, S

getfd

getfd R<DEST>, R<PIO>

Return the file the descriptor for the given ParrotIO object.

Arguments: IR, P

getfile

getfile R<DEST>

Return the name of the current file.

Arguments: SR

getinterp

getinterp R<DEST>

Get a PMC representing the current interpreter.

Arguments: P

getline

getline R<DEST>

Return the current line number.

Arguments: IR

getpackage

getpackage R<DEST>

Return the current package name.

Arguments: SR

getprop

getprop R<DEST>, R<NAME>, R<PMC>

Return the value of a named property on a PMC.

Arguments: P, S, P

getstd*

getstderr R<DEST>
getstdin R<DEST>
getstdout R<DEST>

Get a ParrotIO object for the given standard handle.

Arguments: P

gmtime

gmtime R<DEST>, R<VAL>

Take the integer, which represents GMT epoch-seconds, and turn it into a formatted string.

Arguments: SR, I

gt

gt R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is greater than VAL2.

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

gt_num

gt_num R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is numerically greater than VAL2.

Arguments: P, P, IC

gt_str

gt_str R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is stringwise greater than VAL2.

Arguments: P, P, IC

hav

hav R<DEST>, R<VAL>

The haversine of VAL in radians.

Arguments: NR, N

if

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

inc R<DEST>

Increment a value by one.

Arguments: IR or NR or P

index

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

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

Arguments: P

invokecc

invokecc
invokecc R<SUB>

Call a subroutine like invoke, but also generate a return continuation in P1.

Arguments: P

isa

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.

Arguments: IR, P, S

isnull

isnull R<VAL>, R<LABEL>

Jump to LABEL if the given PMC is a NULL PMC.

Arguments: P, IC

join

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

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.

Arguments: I

jump

jump R<ADDRESS>

Jump to a specified absolute address.

Arguments: I

lcm

lcm R<DEST>, R<VAL>, R<VAL>

Return the least common multiple of two values.

Arguments: IR, I, I or NR, I, I

le

le R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is less than or equal to VAL2.

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

le_num

le_num R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is numerically less than or equal to VAL2.

Arguments: P, P, IC

le_str

le_str R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is stringwise less than or equal to VAL2.

Arguments: P, P, IC

length

length R<DEST>, R<STRING>

Return the character length of a string.

Arguments: IR, S

ln

ln R<DEST>, R<VAL>

The natural logarithm of VAL.

Arguments: NR, I or NR, N

load_bytecode

load_bytecode R<FILE>

Load Parrot bytecode from a file.

Arguments: S

loadlib

loadlib R<DEST>, R<LIBRARY>

Load a dynamic link library by name and store it in a PMC.

Arguments: P, S

localtime

localtime R<DEST>, R<VAL>

Take the integer, which represents GMT epoch-seconds, and turn it into a formatted string after adjusting to localtime.

Arguments: SR, I

log10

log10 R<DEST>, R<VAL>

The base 10 logarithm of VAL.

Arguments: NR, I or NR, N

log2

log2 R<DEST>, R<VAL>

The base 2 logarithm of VAL.

Arguments: NR, I or NR, N

lookback

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

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

lt R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is less than VAL2.

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

lt_num

lt_num R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is numerically less than VAL2.

Arguments: P, P, IC

lt_str

lt_str R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if VAL1 is stringwise less than VAL2.

Arguments: P, P, IC

mmdvtfind

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

mmdvtregister R<FUNC>, R<LEFT>, R<RIGHT>, R<SUB>

Arguments: I, I, I, P

mod

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

mul

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.

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

ne

ne R<VAL>, R<VAL>, R<LABEL>

Jump to a label if the two values are not 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

ne_addr

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.

Arguments: S, S, IC or P, P, IC

ne_num

ne_num R<VAL>, R<VAL>, R<LABEL>

Jump to a label if the two values are numerically different.

Arguments: P, P, IC

ne_str

ne_str R<VAL>, R<VAL>, R<LABEL>

Jump to a label if the two strings are not equal.

Arguments: P, P, IC

needs_destroy

needs_destroy R<PMC>

Mark the PMC as requiring timely destruction.

Arguments: P

neg

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

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

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

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

newclass R<DEST>, R<NAME>

Create a new class with the given name.

Arguments: P, S

newsub

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

noop

Do nothing.

not

not R<DEST>, R<VAL>

Logical NOT. True if VAL is false.

Arguments: IR, I or P, P

null

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

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

or R<DEST>, R<VAL1>, R<VAL2>

Logical OR. Return VAL1 if it's true; otherwise, return VAL2.

Arguments: IR, I, I or P, P, P

ord

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

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.

Arguments: SR or SR, P

peek_pad

peek_pad R<DEST>

Store the current lexical scope pad in a PMC.

Arguments: P

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

Arguments: SR

pioctl

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

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_pad

Pop the current lexical scope pad off the lexical scope stack.

popX

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.

pow

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

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

printerr R<VAL>

Print a value to stderr.

Arguments: I or N or S or P

profile

profile R<INT>

Toggle profiling in the interpreter (0 for off, any other value for on).

Arguments: I

prophash

prophash R<DEST>, R<PMC>

Return a hash containing all the properties from a PMC.

Arguments: P, P

push

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

push_pad R<PAD>

Push a scratchpad stored in a PMC onto the lexical scope stack.

Arguments: P

pushX

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.

pushbottomi
pushbottomn
pushbottomp
pushbottoms

Push registers 0..15.

pushtopi
pushtopn
pushtopp
pushtops

Push registers 16..31.

read

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

readline R<DEST>, R<IO>

Read a line from a Parrot I/O object.

Arguments: SR, P

register

register R<PMC>

Arguments: P

removeparent

removeparent R<CLASS1>, R<CLASS2>

Remove CLASS2 from class CLASS1's list of parents.

Arguments: P, P

repeat

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

restore R<DEST>

Restore a register from the user stack.

Arguments: IR or NR or SR or P

restoreall

restoreall

Restore all the registers. Does a popX for every type.

restoretop

restoretop

Restore registers 16..31. Does a popX for every type.

ret

ret

Pop a location off the top of the call stack, and go there. Often used with bsr and jsr.

rethrow

rethrow R<EXCEPTION>

Rethrow an exception. Only valid inside an exception handler.

Arguments: P

rotate_up

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

Arguments: I

runinterp

runinterp R<INTERPRETER>, R<OFFSET>

Use an interpreter stored in PMC to run code starting at a given offset.

Arguments: P, I

save

save R<VAL>

Save a value onto the user stack.

Arguments: I or N or S or P

saveall

saveall

Save all the registers. Does a pushX for every type.

savec

savec R<VAL>

Save a clone of a value onto the user stack.

Arguments: S or P

savetop

savetop

Save registers 16..31. Does a pushX for every type.

sec

sec R<DEST>, R<VAL>

The secant of VAL in radians.

Arguments: NR, I or NR, N

sech

sech R<DEST>, R<VAL>

The hyperbolic secant of VAL in radians.

Arguments: NR, I or NR, N

seek

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.

Arguments: P, I, I or P, I, I, I

set

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.

Arguments: P, I or P, N or P, S or P, P

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

setX_ind

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

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.

Arguments: P, I

set_chartype

set_chartype R<STRING>, R<CHARTYPE>

Set the chartype of a string.

Arguments: S, I

set_eh

set_eh R<HANDLER>

Push an exception handler on the control stack.

Arguments: P

set_encoding

set_encoding R<STRING>, R<ENCODING>

Set the encoding of a string.

Arguments: S, I

setattribute

setattribute R<OBJECT>, R<OFFSET>, R<ATTRIBUTE>

Set the given attribute at OFFSET for object OBJECT.

Arguments: P, I, P

See also: getattribute, classoffset.

setprop

setprop R<PMC>, R<NAME>, R<VALUE>

Set the value of a named property on a PMC.

Arguments: P, S, P

shift

shift R<DEST>, R<PMC>

Shift a value off the front of an aggregate PMC.

Arguments: IR, P or NR, P or SR, P or P, P

shl

shl R<DEST>, R<VAL>, R<BITS>

Bitwise shift a value left by a given number of bits.

Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P

shr

shr R<DEST>, R<VAL>, R<BITS>

Bitwise shift a value right by a given number of bits.

Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P

sin

sin R<DEST>, R<VAL>

The sine of VAL in radians.

Arguments: NR, I or NR, N

singleton

singleton R<DEST>

Take the given object and put it into its own singleton class.

Arguments: P

sinh

sinh R<DEST>, R<VAL>

The hyperbolic sine of VAL in radians.

Arguments: NR, I or NR, N

sizeof

sizeof R<DEST>, R<TYPE>

Set DEST to the size in bytes of the given natural type.

Arguments: IR, I

sleep

sleep R<SECONDS>

Sleep for the given number of seconds.

Arguments: I or N

spanw

spawnw R<DEST>, R<COMMAND>

Spawn a subprocess to run the given COMMAND, wait for it to finish, and return the result.

Arguments: IR, S

splice

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

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

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

store_lex

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

string_chartype

string_chartype R<DEST>, R<STRING>

Return the chartype of the string.

Arguments: IR, S

string_encoding

string_encoding R<DEST>, R<STRING>

Return the encoding of the string.

Arguments: IR, S

stringinfo

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

sub R<DEST>, R<VAL>
sub R<DEST>, R<VAL1>, R<VAL2>

Subtract VAL2 from VAL1. If no VAL2, subtract VAL from 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

subclass

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

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

substr_r R<DEST>, R<STRING>, R<OFFSET>, R<LENGTH>

Acts like substr, but reuses the destination string instead of creating a new string. Deprecated.

Arguments: SR, S, I, I

sweep

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

sweepoff

Disable DOD sweeps (nestable).

sweepon

sweepon

Re-enable DOD sweeps.

sysinfo

sysinfo R<DEST>, R<ITEM>

Return OS-specific details given by ITEM.

Arguments: IR, I or SR, I

tan

tan R<DEST>, R<VAL>

The tangent of VAL in radians.

Arguments: NR, I or NR, N

tanh

tanh R<DEST>, R<VAL>

The hyperbolic tangent of VAL in radians.

Arguments: NR, I or NR, N

tell

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

thaw

thaw R<DEST>, R<STR>

Create a new PMC representing the frozen image.

Arguments: P, S

throw

throw R<EXCEPTION>

Throw an exception.

Arguments: P

See also: rethrow, set_eh, clear_eh

time

time R<DEST>

Return the current system time.

Arguments: IR or NR

titlecase

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

trace

trace R<INT>

Toggle tracing in the interpreter (0 for off, any other value for on).

Arguments: I

transcode

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

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

unless R<CONDITION>, R<LABEL>

Jump to a label unless the condition is a true value.

Arguments: I, IC or N, IC or S, IC or P, IC

unpin

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.

unregister

unregister R<PMC>

Remove one reference to PMC from the root set registry.

Arguments: P

unshift

unshift R<DEST>, R<VAL>

Unshift a value onto the front of an aggregate PMC.

Arguments: P, I or P, N or P, S or P, P

upcase

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.

Arguments: SR or SR, S

updatecc

updatecc

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.

valid_type

valid_type R<DEST>, R<TYPE>

Check whether a PMC type or native Parrot datatype is a valid one.

Arguments: IR, I

vers

vers R<DEST>, R<VAL>

The versine of VAL in radians.

Arguments: NR, N

warningsoff

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.

Arguments: I

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

Arguments: I

xor

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.

Arguments: IR, I, I or P, P, P

PIR Directives

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

.arg R<VAL>

Push a value onto the user stack or set it according to PCC.

.const

.const R<TYPE>R<NAME> = R<VALUE>

Define a named constant.

.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

.emit

Define a compilation unit of PASM code. Always paired with .eom.

.end

.end

End a compilation unit. Always paired with .sub.

.endm

.endm

End a macro definition. Always paired with .macro.

.eom

.eom

End a compilation unit of PASM code. Always paired with .emit.

.flatten_arg

.flatten_arg R<PArray>

Flatten the passed array PMC and provide args for PCC calls.

.globalconst

.globalconst R<TYPE>R<NAME> = R<VALUE>

Define a named, file visible constant.

.include

.include " R<FILENAME> "

Include the contents of an external file by inserting it in place.

.invocant

.invocant R<OBJ>

Set the invocant for a method call.

.local

.local R<TYPE>R<NAME>

Define a local named variable.

.macro

.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

.meth_call R<SUB>
.meth_call R<SUB>, R<RETCONT>

Create a method call.

.namespace

.namespace R< [ "namespace" ] >

Define a namespace.

.nci_call

.nci_call R<SUB>

Create an NCI call.

.param

.param R<DEST>
.param R<TYPE>R<NAME>

Pop a value off the user stack into a register or typed identifier.

.begin_call

Start a call sequence. Always paired with .end_call

.begin_return

Start a return sequence. Always paired with .end_return

.begin_yield

Start a return of a coroutine sequence. Always paired with .end_yield

.call

.call R<SUB>
.call R<SUB>, R<RETCONT>

Create a subroutine call.

.pcc_sub

.pcc_sub R<_LABEL>

Create a symbol entry for subroutine at the _LABEL. This directive is for PASM code only.

.pragma

.pragma fastcall
.pragma prototyped

Set default calling conventions.

.result

.result R<DEST>

Pop a value off the user stack or get it according to PCC.

.return

.return R<VAL>

Return a value to the calling subroutine by pushing it onto the user stack or set it according to PCC.

.sub

.sub R<NAME>

Define a compilation unit. Always paired with .end. Names begin with "_" by convention.

.sym

.sym R<TYPE> R<NAME>

Same as .local.

PIR Instructions

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>

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.

!

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.

addr

R<DEST> = addr R<LABEL>

Return the address of a label.

call

call R<NAME>

Call the named subroutine (a .sub label).

global

R<DEST> = global R<NAME>
global R<NAME> = R<VAL>

Access a global variable for read or write.

goto

goto R<NAME>

Jump to the named identifier (label or subroutine name).

if

if R<EXPR> goto R<NAME>

If the value or expression evaluates as true, jump to the named identifier.

unless

unless R<VAL> goto R<NAME>

Unless the value evaluates as true, jump to the named identifier.

Parrot Command-Line Options

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.

General Usage

parrot [options] file [arguments]

The file is either an .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.

Assembler Options

-a, --pasm

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.

-c,--pbc

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.

-d,--debug [hexbits]

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.

To produce a huge output on stderr, turn on all the debugging bits:

$ parrot -d 0ffff ...

--help-debug

Show debug option bits.

-h,--help

Print a short summary of options to stdout and exit.

-o outputfile

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.

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.

-r,--run-pbc

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.

-v,--verbose

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.

-y,--yydebug

Turn on yydebug for yacc/bison.

-E,--pre-process-only

Show output of macro expansions and quit.

-V,--version

Print the program version to stdout and exit.

-Ox

Turn on optimizations. The flags currently implemented are shown in CHP-11-TABLE-4Table 11-4.

Bytecode Interpreter Options

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.

-b,--bounds-checks: Activate bounds checking. This also runs with the slow core as a side effect.
-f,--fast-core: Run with the fast core.
-g,--computed-goto-core: Run the computed goto core (CGoto).
-j,--jit-core: Run with the JIT core if available.
-p,--profile: Activate profiling. This prints a summary of opcode usage and execution times after the program stops. It also runs within the slow core.
-C,--CGP-core: Run with the CGoto-Prederefed core.
-P,--predereferenced-core: Run with the Prederefed core.
-S,--switched-core: Run with the Switched core.
-t,--trace: Trace execution. This also turns on the slow core.
-w,--warnings: Turn on warnings.
-G,--no-gc: Turn off DOD/GC. This is for debugging only.
-.,--wait: Wait for a keypress before running.
--leak-test,--destroy-at-end: 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.

166 POD Errors

The following errors were encountered while parsing the POD:

Around line 3:

Unknown directive: =head0

Around line 5:

A non-empty Z<>

Around line 7:

Deleting unknown formatting code A<>

Around line 16:

A non-empty Z<>

Around line 37: