Patrick R. Michaud

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.

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

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

See also: setprop and getprop.

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

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.

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

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

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

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

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

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>

Register the subroutine SUB as the multi-method vtable function FUNC for the two given PMC types.

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

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

  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.

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.

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

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

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.

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

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

See also: newinterp.

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

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.

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

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

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.

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.

.macro_const

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

Deleting unknown formatting code A<>

Deleting unknown formatting code A<>

Around line 16:

A non-empty Z<>

Around line 37:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 48:

Deleting unknown formatting code R<>

Around line 59:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 71:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 81:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 91:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 101:

Deleting unknown formatting code R<>

Around line 111:

Deleting unknown formatting code R<>

Around line 132:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 145:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 157:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 168:

Deleting unknown formatting code R<>

Around line 178:

Deleting unknown formatting code R<>

Around line 188:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 199:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 253:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 265:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 277:

Deleting unknown formatting code R<>

Around line 290:

Deleting unknown formatting code R<>

Around line 303:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 315:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 336:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 357:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 367:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 436:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 510:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 521:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 543:

Deleting unknown formatting code R<>

Around line 553:

Deleting unknown formatting code R<>

Around line 583:

Deleting unknown formatting code R<>

Around line 594:

Deleting unknown formatting code R<>

Around line 606:

Deleting unknown formatting code R<>

Around line 649:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 672:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 706:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 718:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 749:

Deleting unknown formatting code R<>

Around line 771:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 816:

Deleting unknown formatting code R<>

Around line 826:

Deleting unknown formatting code R<>

Around line 856:

Deleting unknown formatting code R<>

Around line 869:

Deleting unknown formatting code R<>

Around line 879:

Deleting unknown formatting code R<>

Around line 889:

Deleting unknown formatting code R<>

Around line 899:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 909:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 920:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 950:

Deleting unknown formatting code R<>

Around line 987:

Deleting unknown formatting code R<>

Around line 1000:

Deleting unknown formatting code R<>

Around line 1012:

Deleting unknown formatting code R<>

Around line 1023:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1056:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1067:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1077:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1099:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1210:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1221:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1231:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1241:

Deleting unknown formatting code R<>

Around line 1272:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1284:

Deleting unknown formatting code A<>

Around line 1400:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1411:

Deleting unknown formatting code R<>

Around line 1465:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1476:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1486:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1506:

Deleting unknown formatting code R<>

Around line 1551:

Deleting unknown formatting code R<>

Around line 1561:

Deleting unknown formatting code R<>

Around line 1594:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1605:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1615:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1625:

Deleting unknown formatting code R<>

Around line 1636:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1648:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1664:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1687:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1731:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1744:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1754:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1765:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1777:

Deleting unknown formatting code R<>

Around line 1800:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1807:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1828:

Deleting unknown formatting code R<>

Around line 1838:

Deleting unknown formatting code R<>

Around line 1861:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1872:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1905:

Deleting unknown formatting code R<>

Around line 1973:

Deleting unknown formatting code R<>

Around line 1981:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 1992:

Deleting unknown formatting code R<>

Around line 2061:

Deleting unknown formatting code R<>

Around line 2085:

Deleting unknown formatting code R<>

Around line 2119:

Deleting unknown formatting code R<>

Around line 2129:

Deleting unknown formatting code R<>

Around line 2149:

Deleting unknown formatting code R<>

Around line 2157:

Deleting unknown formatting code R<>

Around line 2188:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2226:

Deleting unknown formatting code R<>

Around line 2244:

Deleting unknown formatting code R<>

Around line 2252:

Deleting unknown formatting code R<>

Around line 2262:

Deleting unknown formatting code R<>

Around line 2273:

Deleting unknown formatting code R<>

Around line 2278:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2319:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2330:

Deleting unknown formatting code R<>

Around line 2380:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2434:

Deleting unknown formatting code R<>

Around line 2454:

Deleting unknown formatting code R<>

Around line 2464:

Deleting unknown formatting code R<>

Around line 2484:

Deleting unknown formatting code R<>

Around line 2495:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2506:

Deleting unknown formatting code R<>

Around line 2531:

Deleting unknown formatting code R<>

Around line 2569:

Deleting unknown formatting code A<>

Around line 2633:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2646:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2658:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2665:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2672:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2694:

Deleting unknown formatting code R<>

Around line 2731:

Deleting unknown formatting code R<>

Around line 2741:

Deleting unknown formatting code R<>

Around line 2799:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2825:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2858:

Deleting unknown formatting code R<>

Around line 2894:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2930:

Deleting unknown formatting code R<>

Around line 2971:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 2979:

A non-empty Z<>

Around line 3009:

Deleting unknown formatting code R<>

Around line 3090:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3208:

A non-empty Z<>

Around line 3244:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3264:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3272:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3282:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3301:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3309:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3318:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3326:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3335:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3343:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3351:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3359:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3367:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3377:

Deleting unknown formatting code R<>

Around line 3418:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3428:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3438:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3508:

A non-empty Z<>

Around line 3521:

A non-empty Z<>

Around line 3525:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3531:

A non-empty Z<>

Around line 3549:

Deleting unknown formatting code R<>

Around line 3551:

Deleting unknown formatting code A<>

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3648:

Deleting unknown formatting code R<>

Around line 3650:

Deleting unknown formatting code R<>

Deleting unknown formatting code R<>

Around line 3690:

Deleting unknown formatting code A<>

Around line 3746:

A non-empty Z<>