Instruction Reference

This chapter contains a condensed reference to the Parrot virtual machine's native instruction set, generally called opcodes. All opcodes are valid in both PIR and PASM, and correspond to the bytecode 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.

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

  bors 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

clear_eh

  clear_eh

Clear the most recent exception handler.

See also: set_eh, throw.

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.

See also mod.

Arguments: IR, I, I or NR, N, N or P, P, I or P, P, N or P, P, P

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>

Register SUB as a compiler for language TYPE.

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

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

See also: setprop and getprop.

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

See also: exit.

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

See also: upcase, titlecase.

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.

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

See also: throw, die_hard.

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

See also: store_global.

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

See also: store_lex.

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

See also: typeof.

findclass

  findclass R<DEST>, R<NAME>

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

Arguments: IR, S

See also: typeof.

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

See also: thaw.

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

See also: set_addr.

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.

get_class

  get_class R<DEST>, R<NAME>

Return the class PMC of the given name.

Arguments: P, S

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

See also: setprop and prophash.

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

See also: localtime.

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 Table 10-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

See also: updatecc.

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

See also: set_addr.

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

See also: dlfunc.

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

See also: gmtime.

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

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

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

See also: cmod.

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

See also: sweep.

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 property 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 ("r", "w", 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

  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

See also: unpin.

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.

See also: peek_pad.

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.

See also: pushX.

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

See also: getprop.

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>

Register the given PMC in the interpreter's root set, so that it's visible during the mark phase.

Arguments: P

See also: unregister.

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

restoretop

  restoretop

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

See also: savetop.

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

See also: throw

runinterp

  runinterp R<INTERPRETER>, R<OFFSET>

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

Arguments: P, I

See also: newinterp.

say

  say R<VAL>

Print a value to stdout with a trailing newline.

Arguments: I or N or S or P

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

See also: clear_eh, throw.

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

See also: getprop and delprop.

setstd*

  setstderr R<DEST>
  setstdout R<DEST>

Set a ParrotIO object for the given standard handle.

Arguments: 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

spawnw

  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

stat

  stat R<DEST>, R<VAL>, R<VAL>

Stat the VAL1 file and return stat element VAL2, as listed in Table 10-2.

Arguments: IR, S, I or IR, I, I

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

See also: find_global.

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

See also: find_lex.

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 Table 10-3.

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 subclass 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 GC mark run. If LAZY is set to 1, only objects that need timely destruction may be destroyed.

Arguments: IC

sweepoff

  sweepoff

Disable GC mark runs (nestable).

sweepon

  sweepon

Re-enable GC mark runs.

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

See also: seek.

thaw

  thaw R<DEST>, R<STR>

Create a new PMC representing the frozen image.

Arguments: P, S

See also: freeze.

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

See also: upcase, downcase.

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.

See also: pin.

Arguments: SR

unregister

  unregister R<PMC>

Remove one reference to PMC from the root set registry.

Arguments: P

See also: register.

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

See also: downcase, titlecase.

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.

See also: invokecc.

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

Copyright © 2002-2009, Parrot Foundation.