=pod

=head0 Parrot Reference

Z<CHP-8>

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 A<CHP-8-SECT-1>"PASM Opcodes",
A<CHP-8-SECT-2>"PIR Directives", and A<CHP-8-SECT-3>"PIR
Instructions".

=head1 PASM Opcodes

Z<CHP-8-SECT-1>

X<PASM (Parrot assembly language);opcodes, quick reference>
For complete details on each opcode and the latest changes, read the
documentation in F<docs/ops/>, or look at all the C<.ops> files in the
F<ops/> directory.

We've followed a few conventions. C<DEST> is always the register where
the result of the operation is stored. Sometimes the original value of
C<DEST> is one of the source values. C<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 F<.ops> files
for the combinations allowed with a particular operation.

=head2 abs

X<abs opcode (PASM)>

  abs R<DEST>
  abs R<DEST>, R<VAL>

Return the absolute value of a number. If R<VAL> is left out, R<DEST>
gets the absolute value of itself.

I<Arguments: IR or NR or IR, I or IR, N or NR, I or NR, N>

=head2 acos

X<acos opcode (PASM)>

  acos R<DEST>, R<VAL>

The arc cosine of R<VAL> in radians.

I<Arguments: NR, N or NR, I>

=head2 add

X<add opcode (PASM)>

  add R<DEST>, R<VAL>
  add R<DEST>, R<VAL>, R<VAL>

Add two values and return the sum. If only one R<VAL>, add R<VAL> to
R<DEST>.

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

=head2 addattribute

X<addattribute opcode (PASM)>

  addattribute R<CLASS>, R<ATTR>

Add the attribute name R<ATTR> to class R<CLASS>.

I<Arguments: P, S>

=head2 addparent

X<addparent opcode (PASM)>

  addparent R<CLASS1>, R<CLASS2>

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

I<Arguments: P, P>

=head2 and

X<and opcode (PASM)>

  and R<DEST>, R<VAL1>, R<VAL2>

Logical AND. Return R<VAL1> if it's false; otherwise, return R<VAL2>.

I<Arguments: IR, I, I or P, P, P>

=head2 asec

X<asec opcode (PASM)>

  asec R<DEST>, R<VAL>

The arc secant of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 asin

X<asin opcode (PASM)>

  asin R<DEST>, R<VAL>

The arc sine of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 assign

X<assign opcode (PASM)>

  assign R<DEST>, R<VAL>

Assign a value to a PMC.

I<Arguments: SR, S or P, I or P, N or P, S or P, P>

=head2 atan

X<atan opcode (PASM)>

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

The arc tangent of R<VAL1> / R<VAL2> in radians (sign significant). If
R<VAL2> is omitted, then just the arc tangent of R<VAL>.

I<Arguments: NR, I or NR, N or NR, I, I or NR, I, N or NR, N, I or NR,
N, N>

=head2 band

X<band opcode (PASM)>

  band R<DEST>, R<VAL>
  band R<DEST>, R<VAL>, R<VAL>

Bitwise AND on two values. If only one R<VAL>, bitwise AND on R<DEST>
and R<VAL>.

I<Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P>

=head2 bands

X<bands opcode (PASM)>

  bands R<DEST>, R<VAL>
  bands R<DEST>, R<VAL>, R<VAL>

Bitwise AND on two strings. If only one R<VAL>, bitwise AND on R<DEST>
and R<VAL>.

I<Arguments: SR, S or P, S or P, P or SR, S, S or P, P, S or P, P, P>

=head2 bnot

X<bnot opcode (PASM)>

  bnot R<DEST>, R<VAL>

Bitwise NOT on R<VAL>.

I<Arguments: IR, I or P, P>

=head2 bnots

X<bnots opcode (PASM)>

  bnots R<DEST>, R<VAL>

Bitwise NOT on string R<VAL>.

I<Arguments: SR, S or P, P>

=head2 bor

X<bor opcode (PASM)>

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

Bitwise OR on two values. If only one R<VAL>, bitwise OR on R<DEST>
and R<VAL>.

I<Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P>

=head2 bors

X<bors opcode (PASM)>

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

Bitwise OR on two strings. If only one R<VAL>, bitwise OR on R<DEST>
and R<VAL>.

I<Arguments: SR, S or P, S or P, P or SR, S, S or P, P, S or P, P, P>

=head2 bounds

X<bounds opcode (PASM)>

  bounds R<INT>

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

I<Arguments: I>

=head2 branch

X<branch opcode (PASM)>

  branch R<LABEL>

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

I<Arguments: I>

=head2 branch_cs

X<branch_cs opcode (PASM)>

  branch_cs R<FIXUP_ENTRY>

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

I<Arguments: S>

=head2 bsr

X<bsr opcode (PASM)>

  bsr R<LABEL>

Branch to a label, like C<branch>, but also push the current location
onto the call stack so C<ret> can return to it.

I<Arguments: I>

=head2 bxor

X<bxor opcode (PASM)>

  bxor R<DEST>, R<VAL>
  bxor R<DEST>, R<VAL>, R<VAL>

Bitwise XOR on two values. If only one R<VAL>, bitwise XOR on R<DEST>
and R<VAL>.

I<Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P>

=head2 bxors

X<bxors opcode (PASM)>

  bxors R<DEST>, R<VAL>
  bxors R<DEST>, R<VAL>, R<VAL>

Bitwise XOR on two strings. If only one R<VAL>, bitwise XOR on R<DEST>
and R<VAL>.

I<Arguments: SR, S or P, S or P, P or SR, S, S or P, P, S or P, P, P>

=head2 callmethod

X<callmethod opcode (PASM)>

  callmethod
  callmethod R<METHODNAME>

Call the method named R<METHODNAME> on the object stored in C<P2>
according to the Parrot Calling Conventions. If no method name, pull the
name from C<S0>.

I<Arguments: S>

=head2 callmethodcc

X<callmethodcc opcode (PASM)>

  callmethodcc
  callmethodcc R<METHODNAME>

Call the method named R<METHODNAME> on the object stored in C<P2>
according to the Parrot Calling Conventions. If no method name, pull the
name from C<S0>. Also create a return continuation and store it in
C<P1>.

I<Arguments: S>

=head2 can

X<can opcode (PASM)>

  can R<DEST>, R<OBJECT>, R<METHODNAME>

Return a true value if R<OBJECT> I<can> do the R<METHODNAME> method,
otherwise return a false value.

I<Arguments: IR, P, S>

=head2 ceil

X<ceil opcode (PASM)>

  ceil R<DEST>
  ceil R<DEST>, R<VAL>

Set R<DEST> to the smallest integral value less than or equal to R<VAL>
(if present) or itself (if not).

I<Arguments: NR or IR, N or NR, N>

=head2 checkevents

X<checkevents opcode (PASM)>

  checkevents

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

=head2 chopn

X<chopn opcode (PASM)>

  chopn R<DEST>, R<VAL1>
  chopn R<DEST>, R<VAL1>, R<VAL2>

Remove R<VAL2> number of characters from string R<VAL1>. If no
R<VAL2>, remove R<VAL> number of characters from string R<DEST>.

I<Arguments: SR, I or SR, S, I>

=head2 chr

X<chr opcode (PASM)>

  chr R<DEST>, R<INT>

Return the character represented by the given number.

I<Arguments: SR, I>

=head2 class

X<class opcode (PASM)>

  class R<CLASS>, R<OBJECT>

Return the R<CLASS> of the given R<OBJECT>.

I<Arguments: P, P>

=head2 clear_eh

X<clear_eh>

  clear_eh

Clear the most recent exception handler.

See also: C<set_eh>, C<throw>.

=head2 clearX

X<cleari opcode (PASM)>
X<clearn opcode (PASM)>
X<clearp opcode (PASM)>
X<clears opcode (PASM)>

  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.

=head2 clone

X<clone opcode (PASM)>

  clone R<DEST>, R<VAL>

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

I<Arguments: SR, S or P, P>

=head2 close

X<close opcode (PASM)>

  close R<DEST>

Close the filehandle in the given register.

I<Arguments: P>

=head2 cmod

X<cmod opcode (PASM)>

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

C's built-in mod operator.

See also C<mod>.

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

=head2 cmp

X<cmp (comparison);opcode (PASM)>

  cmp R<DEST>, R<VAL1>, R<VAL2>

Set R<DEST> to 1 if R<VAL1> is greater then R<VAL2>, to -1 if it's less then
R<VAL2> or to zero if both are equal. If R<VAL1> and R<VAL2> are both PMCs,
then the type of comparison depends on R<VAL1>.

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

=head2 cmp_num

X<cmp_num opcode (PASM)>

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

Like C<cmp>, but forces numeric comparison.

I<Arguments: IR, P, P>

=head2 cmp_str

X<cmp_str opcode (PASM)>

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

Like C<cmp>, but forces string comparison.

I<Arguments: IR, P, P>

=head2 collect

X<collect opcode (PASM)>

  collect

Trigger a garbage collection (GC) run.

=head2 collectoff

X<collectoff opcode (PASM)>

  collectoff

Disable garbage collection runs (nestable).

=head2 collecton

X<collecton opcode (PASM)>

  collecton

Re-enable garbage collection runs.

=head2 compile

X<compile opcode (PASM)>

  compile R<DEST>, R<COMPILER>, R<SOURCE>

Compile a string of source code with a given compiler PMC and store
the result.

I<Arguments: P, P, S>

=head2 compreg

X<compreg opcode (PASM)>

  compreg R<DEST>, R<TYPE>

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

I<Arguments: P, S>

  compreg R<TYPE>, R<SUB>

Register R<SUB> as a compiler for language R<TYPE>.

I<Arguments: S, P>

=head2 concat

X<concat opcode (PASM)>

  concat R<DEST>, R<VAL>
  concat R<DEST>, R<VAL>, R<VAL>

Concatenate two strings. If only one R<VAL>, concatenate R<VAL> onto
R<DEST>.

I<Arguments: SR, S or SR, S, S or P, P, S or P, P, P>

=head2 conv_*

  conv_i1     R<DEST>, R<VAL>
  conv_i1_ovf R<DEST>, R<VAL>

Convert value to integer or number of given type C<i1>, C<i2>, C<i4>, C<i8>,
C<u1>, C<u2>, C<u4>, C<r4>, C<r8>. C<i> corresponds to a signed integer,
C<u> to an unsigned integer and C<r> to a float; the number indicates the
size (in bytes) of the type. The variants with C<_ovf> throw an exception
if the conversion would overflow.

=head2 cos

X<cos opcode (PASM)>

  cos R<DEST>, R<VAL>

The cosine of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 cosh

X<cosh opcode (PASM)>

  cosh R<DEST>, R<VAL>

The hyperbolic cosine of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 debug

X<debug opcode (PASM)>

  debug R<FLAG>

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

I<Arguments: I>

=head2 dec

X<dec opcode (PASM)>

  dec R<DEST>

Decrement a value by 1.

I<Arguments: I or N or P>

=head2 decodelocaltime

X<decodelocaltime opcode (PASM)>

  decodelocaltime R<DEST>, R<VAL>

Set R<DEST> to a new array which represents the decoded time of the
given epoch-seconds value shifted to local time.

I<Arguments: P, I>

=head2 decodetime

X<decodetime opcode (PASM)>

  decodetime R<DEST>, R<VAL>

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

I<Arguments: P, I>

=head2 defined

X<defined opcode (PASM)>

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

Test a keyed PMC value for definedness. If no R<KEY>, test a PMC for
definedness.

I<Arguments: IR, P>

=head2 delete

X<delete opcode (PASM)>

  delete R<DEST>[R<KEY>]

Delete a keyed value from an aggregate PMC.

I<Arguments: P>

=head2 delprop

X<delprop opcode (PASM)>

  delprop R<PMC>, R<NAME>

Delete a named property from a PMC.

I<Arguments: P, S>

See also: C<setprop> and C<getprop>.

=head2 deref

X<deref opcode (PASM)>

  deref R<DEST>, R<REF>

Set R<DEST> to the PMC that R<REF> refers to.

I<Arguments: P, P>

=head2 die_hard

X<die_hard opcode (PASM)>

  die_hard R<LEVEL>, R<ERROR>

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

I<Arguments: I, I>

See also: C<exit>.

=head2 div

X<div opcode (PASM)>

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

Divide R<VAL1> by R<VAL2>. If R<VAL2> is left out, divide R<DEST> by
R<VAL>.

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

=head2 dlfunc

X<dlfunc opcode (PASM)>

  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.

I<Arguments: P, P, S, S>

=head2 dlvar

X<dlvar opcode (PASM)>

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

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

I<Arguments: P, P, S>

=head2 does

X<does opcode (PASM)>

  does R<DEST>, R<OBJECT>, R<VAL>

Return a true value if R<OBJECT> I<does> provide the interface R<VAL>,
otherwise return a false value.

I<Arguments: I, P, S>

=head2 downcase

X<downcase opcode (PASM)>

  downcase R<DEST>
  downcase R<DEST>, R<VAL>

Create a copy of the string in R<VAL> with all characters converted to
lower case, and store it in R<DEST>. If R<VAL> is omitted, convert and
replace the string in R<DEST>.

I<Arguments: S or S, S>

See also: C<upcase>, C<titlecase>.

=head2 end

X<end opcode (PASM)>

  end

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

=head2 enternative

X<enternative opcode (PASM)>

  enternative

Run the C<run_native> C function.

=head2 eq

X<eq opcode (PASM)>

  eq R<VAL>, R<VAL>, R<LABEL>

Jump to a label if the two values are equal.

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

=head2 eq_addr

X<eq_addr opcode (PASM)>

  eq_addr R<VAL1>, R<VAL2>, R<LABEL>

Jump to a label if R<VAL1> and R<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.

I<Arguments: S, S, IC or P, P, IC>

=head2 eq_num

X<eq_num opcode (PASM)>

  eq_num R<VAL>, R<VAL>, R<LABEL>

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

I<Arguments: P, P, IC>

=head2 eq_str

X<eq_str opcode (PASM)>

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

Jump to a label if the two strings are equal.

I<Arguments: P, P, IC>

=head2 err

X<err opcode (PASM)>

  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.

I<Arguments: IR or SR or SR, I>

=head2 errorsoff

X<errorsoff opcode (PASM)>

  errorsoff R<VAL>

Turn off errors of type R<VAL>.

I<Arguments: I>

=head2 errorson

X<errorson opcode (PASM)>

  errorson R<VAL>

Turn on errors of type R<VAL>.

I<Arguments: I>

=head2 exchange

X<exchange opcode (PASM)>

  exchange R<REG>, R<REG>

Exchange the contents of two registers.

I<Arguments: IR, IR or NR, NR or SR, SR or P, P>

=head2 exists

X<exists opcode (PASM)>

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

Test a PMC key for existence.

I<Arguments: IR, P>

=head2 exit

X<exit opcode (PASM)>

  exit R<STATUS>

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

I<Arguments: I>

See also: C<throw>, C<die_hard>.

=head2 exp

X<exp opcode (PASM)>

  exp R<DEST>, R<VAL>

Base of the natural logarithm, I<e>, to the power of R<VAL>.

I<Arguments: NR, I or NR, N>

=head2 exsec

X<exsec opcode (PASM)>

  exsec R<DEST>, R<VAL>

The exsecant of R<VAL> in radians.

I<Arguments: NR, N>

=head2 fact

X<fact opcode (PASM)>

  fact R<DEST>, R<INT>

Return the factorial of R<INT>.

I<Arguments: IR, I or NR, I>

=head2 fdopen

X<fdopen opcode (PASM)>

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

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

I<Arguments: P, I, S>

=head2 find_chartype

X<find_chartype opcode (PASM)>

  find_chartype R<DEST>, R<NAME>

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

I<Arguments: IR, S>

=head2 find_encoding

X<strings;encoding>
X<find_encoding opcode (PASM)>

  find_encoding R<DEST>, R<NAME>

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

I<Arguments: IR, S>

=head2 find_global

X<find_global opcode (PASM)>

  find_global R<DEST>, R<NAME>

Return a global variable with the given name.

I<Arguments: P, S>

  find_global R<DEST>, R<NAMESPACE>, R<NAME>

Return a global variable with the given name from the given namespace.

I<Arguments: P, S, S or P, P, S>

See also: C<store_global>.

=head2 find_lex

X<find_lex opcode (PASM)>

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

I<Arguments: P, S or P, I, S or P, I, I>

See also: C<store_lex>.

=head2 find_method

X<find_method opcode (PASM)>

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

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

I<Arguments: P, P, S>

=head2 find_type

X<find_type opcode (PASM)>

  find_type R<DEST>, R<NAME>

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

I<Arguments: IR, S>

See also: C<typeof>.

=head2 findclass

X<findclass opcode (PASM)>

  findclass R<DEST>, R<NAME>

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

I<Arguments: IR, S>

See also: C<typeof>.

=head2 floor

X<floor opcode (PASM)>

  floor R<DEST>
  floor R<DEST>, R<VAL>

Return the largest integral value less than or equal to R<VAL> (if
present) or itself (if not).

I<Arguments: NR or IR, N or NR, N>

=head2 foldup

X<foldup opcode (PASM)>

  foldup R<DEST>
  foldup R<DEST>, R<SKIP>

Return a new array holding all passed subroutine parameters. R<SKIP>
defines an optional offset.

I<Arguments: P or P, I>

=head2 freeze

X<freeze opcode (PASM)>

  freeze R<DEST>, R<VAL>

Create a frozen image R<DEST> from PMC R<VAL>.

I<Arguments: SR, P>

See also: C<thaw>.

=head2 gc_debug

X<gc_debug opcode (PASM)>

  gc_debug R<INT>

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

I<Arguments: I>

=head2 gcd

X<gcd opcode (PASM)>

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

Return the greatest common divisor of two values.

I<Arguments: IR, I, I or IR, N, N>

=head2 ge

X<ge (greater than or equal);opcode (PASM)>

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

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

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

=head2 ge_num

X<ge_num opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 ge_str

X<ge_str opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 get_addr

X<get_addr opcode (PASM)>

  get_addr R<DEST>, R<SUB>

Get the absolute address of a subroutine PMC.

I<Arguments: IR, P>

See also: C<set_addr>.

=head2 getattribute

X<getattribute opcode (PASM)>

  getattribute R<DEST>, R<OBJECT>, R<OFFS>

Get a reference to attribute number R<OFFS> from object R<OBJECT>.

I<Arguments: P, P, I>

See also: C<setattribute>, C<classoffset>.

=head2 get_class

X<get_class opcode (PASM)>

  get_class R<DEST>, R<NAME>

Return the class PMC of the given name.

I<Arguments: P, S>

=head2 getfd

X<getfd opcode (PASM)>

  getfd R<DEST>, R<PIO>

Return the file the descriptor for the given ParrotIO object.

I<Arguments: IR, P>

=head2 getfile

X<getfile opcode (PASM)>

  getfile R<DEST>

Return the name of the current file.

I<Arguments: SR>

=head2 getinterp

X<getinterp opcode (PASM)>

  getinterp R<DEST>

Get a PMC representing the current interpreter.

I<Arguments: P>

=head2 getline

X<getline opcode (PASM)>

  getline R<DEST>

Return the current line number.

I<Arguments: IR>

=head2 getpackage

X<getpackage opcode (PASM)>

  getpackage R<DEST>

Return the current package name.

I<Arguments: SR>

=head2 getprop

X<getprop opcode (PASM)>

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

Return the value of a named property on a PMC.

I<Arguments: P, S, P>

See also: C<setprop> and C<prophash>.

=head2 getstd*

X<getstderr opcode (PASM)>
X<getstdin opcode (PASM)>
X<getstdout opcode (PASM)>

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

Get a ParrotIO object for the given standard handle.

I<Arguments: P>

=head2 gmtime

X<gmtime opcode (PASM)>

  gmtime R<DEST>, R<VAL>

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

I<Arguments: SR, I>

See also: C<localtime>.

=head2 gt

X<gt opcode (PASM)>

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

Jump to a label if R<VAL1> is greater than R<VAL2>.

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

=head2 gt_num

X<gt_num opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 gt_str

X<gt_str opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 hav

X<hav opcode (PASM)>

  hav R<DEST>, R<VAL>

The haversine of R<VAL> in radians.

I<Arguments: NR, N>

=head2 if

X<if (conditional);opcode (PASM)>

  if R<CONDITION>, R<LABEL>

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

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

=head2 inc

X<inc opcode (PASM)>

  inc R<DEST>

Increment a value by one.

I<Arguments: IR or NR or P>

=head2 index

X<index opcode (PASM)>

  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 R<SEARCH> in
the string R<STRING>, starting at the position R<POS>. If the starting
position is unspecified, start at the beginning of the string.

I<Arguments: IR, S, S or IR, S, S, I>

=head2 interpinfo

X<interpinfo opcode (PASM)>

  interpinfo R<DEST>, R<FLAG>

Return information about the interpreter. An integer flag selects
which information to return, as listed in
A<CHP-8-TABLE-1>Table 11-1.

=begin table picture Interpinfo flags

Z<CHP-8-TABLE-1>

=headrow

=row

=cell Flag

=cell Returns

=bodyrows

=row

=cell C<1>

=cell Allocated memory, in bytes.

=row

=cell C<2>

=cell Number of DOD sweeps performed.

=row

=cell C<3>

=cell Number of GC runs performed.

=row

=cell C<4>

=cell Number of active PMCs.

=row

=cell C<5>

=cell Number of active buffers.

=row

=cell C<6>

=cell Number of allocated PMCs.

=row

=cell C<7>

=cell Number of allocated buffers.

=row

=cell C<8>

=cell Number of new PMC or buffer headers allocated since last DOD run.

=row

=cell C<9>

=cell Number of memory blocks allocated since last GC run.

=row

=cell C<10>

=cell Amount of memory copied during GC runs, in bytes.

=end table

I<Arguments: IR, I>

=head2 invoke

X<invoke opcode (PASM)>

  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 C<P0> and uses
the standard calling conventions.  Otherwise, no calling convention is
defined. Also C<yield> from a coroutine.

I<Arguments: P>

=head2 invokecc

X<invokecc opcode (PASM)>

  invokecc
  invokecc R<SUB>

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

I<Arguments: P>

See also: C<updatecc>.

=head2 isa

X<isa opcode (PASM)>

  isa R<DEST>, R<OBJECT>, R<CLASS>

Return a true value if R<OBJECT> I<isa> member of class R<CLASS>, or of
one of its subclasses, otherwise return a false value.

I<Arguments: IR, P, S>

=head2 isnull

X<isnull opcode (PASM)>

  isnull R<VAL>, R<LABEL>

Jump to R<LABEL> if the given PMC is a NULL PMC.

I<Arguments: P, IC>

=head2 join

X<join opcode (PASM)>

  join R<DEST>, R<DELIM>, R<ARRAY>

Create a new string by joining all elements from array with the given
delimiter.

I<Arguments: SR, S, P>

=head2 jsr

X<jsr opcode (PASM)>

  jsr R<ADDRESS>

Jump to an address, like C<jump>, but also push the current location
onto the call stack so C<ret> can return to it.

I<Arguments: I>

=head2 jump

X<jump opcode (PASM)>

  jump R<ADDRESS>

Jump to a specified absolute address.

I<Arguments: I>

See also: C<set_addr>.

=head2 lcm

X<lcm opcode (PASM)>

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

Return the least common multiple of two values.

I<Arguments: IR, I, I or NR, I, I>

=head2 le

X<le (less than or equal);opcode (PASM)>

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

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

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

=head2 le_num

X<le_num opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 le_str

X<le_str opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 length

X<length opcode (PASM)>

  length R<DEST>, R<STRING>

Return the character length of a string.

I<Arguments: IR, S>

=head2 ln

X<ln opcode (PASM)>

  ln R<DEST>, R<VAL>

The natural logarithm of R<VAL>.

I<Arguments: NR, I or NR, N>

=head2 load_bytecode

X<load_bytecode>

  load_bytecode R<FILE>

Load Parrot bytecode from a file.

I<Arguments: S>

=head2 loadlib

X<loadlib opcode (PASM)>

  loadlib R<DEST>, R<LIBRARY>

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

I<Arguments: P, S>

See also: C<dlfunc>.

=head2 localtime

X<localtime opcode (PASM)>

  localtime R<DEST>, R<VAL>

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

I<Arguments: SR, I>

See also: C<gmtime>.

=head2 log10

X<log10 opcode (PASM)>

  log10 R<DEST>, R<VAL>

The base 10 logarithm of R<VAL>.

I<Arguments: NR, I or NR, N>

=head2 log2

X<log2 opcode (PASM)>

  log2 R<DEST>, R<VAL>

The base 2 logarithm of R<VAL>.

I<Arguments: NR, I or NR, N>

=head2 lsr

X<lsr opcode (PASM)>

  lsr R<DEST>, R<BITS>
  lsr R<DEST>, R<VAL>, R<BITS>

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

I<Arguments: IR, I or IR, I, I>

=head2 lt

X<lt (less than);opcode (PASM)>

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

Jump to a label if R<VAL1> is less than R<VAL2>.

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

=head2 lt_num

X<lt_num opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 lt_str

X<lt_str opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 mmdvtfind

X<mmdvtfind opcode (PASM)>

  mmdvtfind R<DEST>, R<FUNC>, R<LEFT>, R<RIGHT>

Get the subroutine PMC for the multi-method vtable function R<FUNC>
for the two given PMC types.

I<Arguments: P, I, I, I>

=head2 mmdvtregister

X<mmdvtregister opcode (PASM)>

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

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

I<Arguments: I, I, I, P>

=head2 mod

X<mod opcode (PASM)>

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

Divide R<VAL1> by R<VAL2> and return the remainder. If R<VAL2> is omitted,
divide R<DEST> by R<VAL>.  The operation is defined as:

  x mod y = x - y * floor(x / y)

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

See also: C<cmod>.

=head2 mul

X<mul opcode (PASM)>

  mul R<DEST>, R<VAL>
  mul R<DEST>, R<VAL>, R<VAL>

Multiply two values and return the result. If only one R<VAL>,
multiply R<DEST> by R<VAL>.

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

=head2 ne

X<ne (not equal);opcode (PASM)>

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

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

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

=head2 ne_addr

X<ne_addr opcode (PASM)>

  ne_addr R<VAL>, R<VAL>, R<LABEL>

Jump to a label if R<VAL1> and R<VAL2> do not point to the same string
or PMC.

I<Arguments: S, S, IC or P, P, IC>

=head2 ne_num

X<ne_num opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 ne_str

X<ne_str opcode (PASM)>

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

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

I<Arguments: P, P, IC>

=head2 needs_destroy

X<needs_destroy opcode (PASM)>

  needs_destroy R<PMC>

Mark the PMC as requiring timely destruction.

I<Arguments: P>

See also: C<sweep>.

=head2 neg

X<neg opcode (PASM)>

  neg R<DEST>
  neg R<DEST>, R<VAL>

Return the negative of a number. If there is no R<VAL>, R<DEST> is the
negative of itself.

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

=head2 new

X<new opcode (PASM)>

  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 R<TYPE>. R<INITIALIZE> is an array PMC
containing initialization data for the new PMC. R<PROPS> is a propety hash.

I<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 R<LENGTH>, R<ENCODING>, and
R<TYPE>.

I<Arguments: SR or SR, I or SR, I, I or SR, I, I, I>

=head2 new_callback

X<new_callback opcode (PASM)>

  new_callback R<DEST>, R<SUB>, R<DATA>, R<SIG>

Create a callback stub R<DEST> for a PASM subroutine R<SUB> with user
data R<DATA> and function signature R<SIG>.

I<Arguments: P, P, P, S>

=head2 new_pad

X<new_pad opcode (PASM)>

  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.
R<DEPTH> specifies the static nesting depth for the pad (lower static
depths are copied from the current static nesting).

I<Arguments: I or P, I>

=head2 newclass

X<newclass opcode (PASM)>

  newclass R<DEST>, R<NAME>

Create a new class with the given name.

I<Arguments: P, S>

=head2 newsub

X<newsub opcode (PASM)>

  newsub R<DEST>, R<CLASS>, R<LABEL>

Generate a new subroutine object of the given R<CLASS>, located at the
given R<LABEL>, and store the object in the destination PMC.

I<Arguments: P, I, IC>

  newsub R<CLASS>, R<RETCLASS>, R<LABEL>, R<RETADDR>

Generate a new subroutine object of the given R<CLASS>, located at the
given R<LABEL>, and store the object in C<P0>. Also generate a return
continuation of class R<RETCLASS> with the return address R<RETADDR> and
store it in C<P1>.

I<Arguments: I, I, IC, IC>

=head2 noop

X<noop opcode (PASM)>

  noop

Do nothing.

=head2 not

X<not opcode (PASM)>

  not R<DEST>, R<VAL>

Logical NOT. True if R<VAL> is false.

I<Arguments: IR, I or P, P>

=head2 null

X<null opcode (PASM)>

  null R<DEST>

Set R<DEST> (which must be a register) to 0, 0.0 or a NULL pointer,
depending on its type.

I<Arguments: IR or NR or SR or P>

=head2 open

X<open opcode (PASM)>

  open R<DEST>, R<FILENAME>
  open R<DEST>, R<FILENAME>, R<MODE>

Open a file in the specified mode ("E<lt>", "E<gt>", etc.) and return
a filehandle. Without the mode it defaults to read/write.

I<Arguments: P, S, S or P, S>

=head2 or

X<or opcode (PASM)>

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

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

I<Arguments: IR, I, I or P, P, P>

=head2 ord

X<ord opcode (PASM)>

  ord R<DEST>, R<STRING>
  ord R<DEST>, R<STRING>, R<POS>

Return the character at position R<POS> in R<STRING>. If R<POS> isn't
specified, return the 0th character.

I<Arguments: IR, S or IR, S, I>

=head2 peek

X<peek opcode (PASM)>

  peek R<DEST>
  peek R<DEST>, R<PIO>

Read the next byte from the given ParrotIO object or from C<stdin> but
don't remove it.

I<Arguments: SR or SR, P>

=head2 peek_pad

X<peek_pad opcode (PASM)>

  peek_pad R<DEST>

Store the current lexical scope pad in a PMC.

I<Arguments: P>

=head2 pin

X<pin opcode (PASM)>

  pin R<DEST>

Make the string in R<DEST> immobile. This prevents the garbage collector
from moving it to a different location in memory (which it otherwise may
choose to do).

I<Arguments: SR>

See also: C<unpin>.

=head2 pioctl

X<pioctl opcode (PASM)>

  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.

I<Arguments: IR, P, I, I>

=head2 pop

X<pop opcode (PASM)>

  pop R<DEST>, R<PMC>

Pop the last entry off an aggregate PMC and return it.

I<Arguments: IR, P or NR, P or SR, P or P, P>

=head2 pop_pad

X<pop_pad opcode (PASM)>

  pop_pad

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

See also: C<peek_pad>.

=head2 popX

X<popi opcode (PASM)>
X<popn opcode (PASM)>
X<popp opcode (PASM)>
X<pops opcode (PASM)>

  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: C<push>R<X>.

=head2 pow

X<pow opcode (PASM)>

  pow R<DEST>, R<VAL1>, R<VAL2>

Return R<VAL1> raised to the power of R<VAL2>.

I<Arguments: NR, I, I or NR, I, N or NR, N, I or NR, N, N>

=head2 print

X<print opcode (PASM)>

  print R<VAL>
  print R<IO>, R<VAL>

Print a value to an I/O object or file descriptor. If no R<IO> is
given, print the value to standard output.

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

=head2 printerr

X<printerr opcode (PASM)>

  printerr R<VAL>

Print a value to C<stderr>.

I<Arguments: I or N or S or P>

=head2 profile

X<profile opcode (PASM)>

  profile R<INT>

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

I<Arguments: I>

=head2 prophash

X<prophash opcode (PASM)>

  prophash R<DEST>, R<PMC>

Return a hash containing all the properties from a PMC.

I<Arguments: P, P>

See also: C<getprop>.

=head2 push

X<push opcode (PASM)>

  push R<PMC>, R<VAL>

Push a value onto the end of an aggregate PMC.

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

=head2 push_pad

X<push_pad opcode (PASM)>

  push_pad R<PAD>

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

I<Arguments: P>

=head2 pushX

X<pushi opcode (PASM)>
X<pushn opcode (PASM)>
X<pushp opcode (PASM)>
X<pushs opcode (PASM)>

  pushi
  pushn
  pushp
  pushs

Save all the registers of one type to the stack ("i" = integer, "n" =
float, "p" = PMC, "s" = string). Restore with C<pop>R<X>.

  pushbottomi
  pushbottomn
  pushbottomp
  pushbottoms

Push registers 0..15.

  pushtopi
  pushtopn
  pushtopp
  pushtops

Push registers 16..31.

=head2 read

X<read opcode (PASM)>

  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
C<stdin> if no R<IO> is provided.

I<Arguments: SR, I or SR, P, I>

=head2 readline

X<readline opcode (PASM)>

  readline R<DEST>, R<IO>

Read a line from a Parrot I/O object.

I<Arguments: SR, P>

=head2 register

X<register opcode (PASM)>

  register R<PMC>

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

I<Arguments: P>

See also: C<unregister>.

=head2 removeparent

X<removeparent opcode (PASM)>

  removeparent R<CLASS1>, R<CLASS2>

Remove R<CLASS2> from class C<CLASS1>'s list of parents.

I<Arguments: P, P>

=head2 repeat

X<repeat opcode (PASM)>

  repeat R<DEST>, R<VAL>, R<REPEAT>

Repeat a string R<REPEAT> number of times.

I<Arguments: SR, S, I or P, P, I or P, P, P>

=head2 restoretop

X<restoretop opcode (PASM)>

  restoretop

Restore registers 16..31. Does a C<pop>R<X> for every type.

See also: C<savetop>.

=head2 ret

X<ret opcode (PASM)>

  ret

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

=head2 rethrow

X<rethrow opcode (PASM)>

  rethrow R<EXCEPTION>

Rethrow an exception. Only valid inside an exception handler.

I<Arguments: P>

See also: C<throw>

=head2 runinterp

X<runinterp opcode (PASM)>

  runinterp R<INTERPRETER>, R<OFFSET>

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

I<Arguments: P, I>

See also: C<newinterp>.

=head2 sec

X<sec opcode (PASM)>

  sec R<DEST>, R<VAL>

The secant of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 sech

X<sech opcode (PASM)>

  sech R<DEST>, R<VAL>

The hyperbolic secant of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 seek

X<seek opcode (PASM)>

  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).  R<DEST> is the
success or failure of the seek.

64-bit C<seek> combines R<UPPER32> and R<LOWER32> to get one 64-bit
R<OFFSET>.

I<Arguments: P, I, I or P, I, I, I>

=head2 set

X<set opcode (PASM)>

  set R<DEST>, R<VAL>

Set a register to a value.

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

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

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

=head2 setX_ind

X<seti_ind opcode (PASM)>
X<setn_ind opcode (PASM)>
X<sets_ind opcode (PASM)>
X<setp_ind opcode (PASM)>

  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 R<REG> of the specified type to R<VAL>. Bypasses
the register allocator, so use with care.

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

=head2 set_addr

X<set_addr opcode (PASM)>

  set_addr R<DEST>, R<LABEL>

Return the current address plus the offset to R<LABEL>. Often used to
calculate absolute addresses for C<jump> or C<jsr>.

I<Arguments: IR, IC>

  set_addr R<SUB>, R<LABEL>

Set the subroutine address pointing to the given label.

I<Arguments: P, I>

=head2 set_chartype

X<set_chartype opcode (PASM)>

  set_chartype R<STRING>, R<CHARTYPE>

Set the chartype of a string.

I<Arguments: S, I>

=head2 set_eh

X<set_eh opcode (PASM)>

  set_eh R<HANDLER>

Push an exception handler on the control stack.

I<Arguments: P>

See also: C<clear_eh>, C<throw>.

=head2 set_encoding

X<set_encoding opcode (PASM)>
X<strings;encoding>

  set_encoding R<STRING>, R<ENCODING>

Set the encoding of a string.

I<Arguments: S, I>

=head2 setattribute

X<setattribute opcode (PASM)>

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

Set the given attribute at R<OFFSET> for object R<OBJECT>.

I<Arguments: P, I, P>

See also: C<getattribute>, C<classoffset>.

=head2 setprop

X<setprop opcode (PASM)>

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

Set the value of a named property on a PMC.

I<Arguments: P, S, P>

See also: C<getprop> and C<delprop>.

=head2 shift

X<shift opcode (PASM)>

  shift R<DEST>, R<PMC>

Shift a value off the front of an aggregate PMC.

I<Arguments: IR, P or NR, P or SR, P or P, P>

=head2 shl

X<shl opcode (PASM)>

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

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

I<Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P>

=head2 shr

X<shr opcode (PASM)>

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

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

I<Arguments: IR, I or P, I or P, P or IR, I, I or P, P, I or P, P, P>

=head2 sin

X<sin opcode (PASM)>

  sin R<DEST>, R<VAL>

The sine of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 singleton

X<singleton opcode (PASM)>

  singleton R<DEST>

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

I<Arguments: P>

=head2 sinh

X<sinh opcode (PASM)>

  sinh R<DEST>, R<VAL>

The hyperbolic sine of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 sizeof

X<sizeof opcode (PASM)>

  sizeof R<DEST>, R<TYPE>

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

I<Arguments: IR, I>

=head2 sleep

X<sleep opcode (PASM)>

  sleep R<SECONDS>

Sleep for the given number of seconds.

I<Arguments: I or N>

=head2 spanw

X<spawnw opcode (PASM)>

  spawnw R<DEST>, R<COMMAND>

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

I<Arguments: IR, S>

=head2 splice

X<splice opcode (PASM)>

  splice R<DEST>, R<REPLACE>, R<OFFSET>, R<COUNT>

Starting at R<OFFSET>, replace R<COUNT> number of values in the
destination PMC with values provided in the R<REPLACE> PMC.

I<Arguments: P, P, I, I>

=head2 sprintf

X<sprintf opcode (PASM)>

  sprintf R<DEST>, R<FORMAT>, R<ARGS>

Format arguments in an aggregate PMC, using format string R<FORMAT>.

I<Arguments: SR, S, P or P, P, P>

=head2 store_global

X<store_global opcode (PASM)>

  store_global R<NAME>, R<OBJECT>
  store_global R<NAME>, R<NAMESPACE>, R<OBJECT>

Store a global variable as a named symbol.

I<Arguments: S, P or S, S, P or P, S, P>

See also: C<find_global>.

=head2 store_lex

X<store_lex opcode (PASM)>

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

I<Arguments: S, P or I, I, P or I, S, P>

See also: C<find_lex>.

=head2 string_chartype

X<string_chartype opcode (PASM)>

  string_chartype R<DEST>, R<STRING>

Return the chartype of the string.

I<Arguments: IR, S>

=head2 string_encoding

X<string_encoding opcode (PASM)>
X<strings;encoding>

  string_encoding R<DEST>, R<STRING>

Return the encoding of the string.

I<Arguments: IR, S>

=head2 stringinfo

X<stringinfo opcode (PASM)>

  stringinfo R<DEST>, R<STRING>, R<FLAG>

Return information about a string. An integer flag selects which
information to return, as listed in A<CHP-8-TABLE-2>Table 11-2.

=begin table picture Stringinfo arguments

Z<CHP-8-TABLE-2>

=headrow

=row

=cell Flag

=cell Returns

=bodyrows

=row

=cell C<1>

=cell Location of string buffer header.

=row

=cell C<2>

=cell Location of start of string memory.

=row

=cell C<3>

=cell Allocated length, in bytes.

=row

=cell C<4>

=cell String flags.

=row

=cell C<5>

=cell Length of string buffer currently used, in bytes.

=row

=cell C<6>

=cell String length, in characters.

=end table

I<Arguments: IR, S, I>

=head2 sub

X<sub opcode (PASM)>

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

Subtract R<VAL2> from R<VAL1>. If no R<VAL2>, subtract R<VAL> from
R<DEST>.

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

=head2 subclass

X<subclass opcode (PASM)>

  subclass R<DEST>, R<CLASS>
  subclass R<DEST>, R<CLASS>, R<NAME>

Create a sublass of R<CLASS>. Without R<NAME> an anonymous subclass is
created.

I<Arguments: P, S or P, P or P, S, S or P, P, S>

=head2 substr

X<substr opcode (PASM)>

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

Return a substring of R<STRING>, beginning at R<OFFSET> and with length
R<LENGTH>.

I<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 R<REPLACE> is given, use it to replace the returned substring in
R<STRING>.

I<Arguments: SR, S, I, I, S>

  substr R<DEST>, R<OFFSET>, R<LENGTH>, R<REPLACE>

If R<STRING> is omitted, operate on the string in R<DEST>.

I<Arguments: SR, I, I, S>


=head2 substr_r

X<substr_r opcode (PASM)>

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

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

I<Arguments: SR, S, I, I>

=head2 sweep

X<sweep opcode (PASM)>

  sweep R<LAZY>

Trigger a dead object detection (DOD) sweep. If R<LAZY> is set to 1,
only objects that need timely destruction may be destroyed.

I<Arguments: IC>

=head2 sweepoff

X<sweepoff opcode (PASM)>

  sweepoff

Disable DOD sweeps (nestable).

=head2 sweepon

X<sweepon opcode (PASM)>

  sweepon

Re-enable DOD sweeps.

=head2 sysinfo

X<sysinfo opcode (PASM)>

  sysinfo R<DEST>, R<ITEM>

Return OS-specific details given by C<ITEM>.

I<Arguments: IR, I or SR, I>

=head2 tan

X<tan opcode (PASM)>

  tan R<DEST>, R<VAL>

The tangent of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 tanh

X<tanh opcode (PASM)>

  tanh R<DEST>, R<VAL>

The hyperbolic tangent of R<VAL> in radians.

I<Arguments: NR, I or NR, N>

=head2 tell

X<tell opcode (PASM)>

  tell R<DEST>, R<PIO>
  tell R<UPPER32>, R<LOWER32>, R<PIO>

Return the file position of the given ParrotIO object.

I<Arguments: IR, P or IR, I, P>

See also: C<seek>.

=head2 thaw

X<thaw opcode (PASM)>

  thaw R<DEST>, R<STR>

Create a new PMC representing the frozen image.

I<Arguments: P, S>

See also: C<freeze>.

=head2 throw

X<throw opcode (PASM)>

  throw R<EXCEPTION>

Throw an exception.

I<Arguments: P>

See also: C<rethrow>, C<set_eh>, C<clear_eh>

=head2 time

X<time opcode (PASM)>

  time R<DEST>

Return the current system time.

I<Arguments: IR or NR>

=head2 titlecase

X<titlecase opcode (PASM)>

  titlecase R<DEST>
  titlecase R<DEST>, R<VAL>

Create a copy of the string in R<VAL> with all characters converted to
title case, and store it in R<DEST>. If R<VAL> is omitted, convert and
replace the string in R<DEST>.

I<Arguments: SR or SR, S>

See also: C<upcase>, C<downcase>.

=head2 trace

X<trace opcode (PASM)>

  trace R<INT>

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

I<Arguments: I>

=head2 transcode

X<transcode opcode (PASM)>

  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 R<CHARTYPE> and R<ENCODING>. If
R<CHARTYPE> is omitted, it is assumed to be the same as the original.

I<Arguments: SR, I or SR, S, I or SR, S, I, I>

=head2 typeof

X<typeof opcode (PASM)>

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

I<Arguments: IR, P or SR, I or SR, P>

=head2 unless

X<unless (conditional);opcode (PASM)>

  unless R<CONDITION>, R<LABEL>

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

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

=head2 unpin

X<unpin opcode (PASM)>

  unpin R<DEST>

Make the string in R<DEST> movable again. This is the default, so
C<unpin> is a no-op unless the string has been pinned with C<pin>.

See also: C<pin>.

I<Arguments: SR>

=head2 unregister

X<unregister opcode (PASM)>

  unregister R<PMC>

Remove one reference to PMC from the root set registry.

I<Arguments: P>

See also: C<register>.

=head2 unshift

X<unshift opcode (PASM)>

  unshift R<DEST>, R<VAL>

Unshift a value onto the front of an aggregate PMC.

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

=head2 upcase

X<upcase opcode (PASM)>

  upcase R<DEST>
  upcase R<DEST>, R<VAL>

Create a copy of the string in R<VAL> with all characters converted to
upper case, and store it in R<DEST>. If R<VAL> is omitted, convert and
replace the string in R<DEST>.

I<Arguments: SR or SR, S>

See also: C<downcase>, C<titlecase>.

=head2 updatecc

X<updatecc>

  updatecc

Update the state of a return continuation stored in C<P1>. Used when
context information changes after the return continuation is created
but before it's invoked.

See also: C<invokecc>.

=head2 valid_type

X<valid_type opcode (PASM)>

  valid_type R<DEST>, R<TYPE>

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

I<Arguments: IR, I>

=head2 vers

X<vers opcode (PASM)>

  vers R<DEST>, R<VAL>

The versine of R<VAL> in radians.

I<Arguments: NR, N>

=head2 warningsoff

X<warningsoff opcode (PASM)>

  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 C<warningson> for the list of categories.

I<Arguments: I>

=head2 warningson

X<warningson opcode (PASM)>

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

I<Arguments: I>

=head2 xor

X<xor opcode (PASM)>

  xor R<DEST>, R<VAL1>, R<VAL2>

Logical XOR. If R<VAL1> is true and R<VAL2> is false, return R<VAL1>.
If R<VAL1> is false and R<VAL2> is true, return R<VAL2>. Otherwise,
return a false value.

I<Arguments: IR, I, I or P, P, P>

=head1 PIR Directives

Z<CHP-8-SECT-2>

X<PIR (Parrot intermediate representation);quick reference;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.


=head2 .arg

X<.arg directive>

  .arg R<VAL>

pass a value to a subroutine according to PCC.

=head2 .const

X<.const directive>

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

Define a named constant.

=head2 .macro_const

X<.macro_const directive>

  .macro_const R<NAME>R<VALUE>

Define a named macro that expands to a given value. Macros are called
as directives, i.e. .R<NAME> (PASM code only).

=head2 .emit

X<.emit directive>

  .emit

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

=head2 .end

X<.end directive>

  .end

End a compilation unit. Always paired with C<.sub>.

=head2 .endm

X<.endm directive>

  .endm

End a macro definition. Always paired with C<.macro>.

=head2 .eom

X<.eom directive>

  .eom

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

=head2 .flatten_arg

X<.flatten_arg directive>

  .flatten_arg R<PArray>

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

=head2 .globalconst

X<.cglobalonst directive>

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

Define a named, file visible constant.

=head2 .include

X<.include directive>

  .include " R<FILENAME> "

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

=head2 .invocant

X<.invocant directive>

  .invocant R<OBJ>

Set the invocant for a method call.

=head2 .local

X<.local directive>

  .local R<TYPE>R<NAME>

Define a local named variable.

=head2 .macro

X<.macro directive>

  .macro R<NAME> (R<PARAMS>)

Define a named macro with a list of parameters. The macro is called as
.R<NAME>(R<arg1>,R<arg2>,...).  Always paired with C<.endm>.

=head2 .meth_call

X<.meth_call directive>

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

Create a method call.

=head2 .namespace

X<.namespace directive>

  .namespace R< [ "namespace" ] >

Define a namespace.

=head2 .nci_call

X<.nci_call directive>

  .nci_call R<SUB>

Create an NCI call.

=head2 .param

X<.param directive>

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

Define a subroutine parameter.

=head2 .begin_call

X<.begin_call directive>

Start a call sequence. Always paired with C<.end_call>

=head2 .begin_return

X<.begin_return directive>

Start a return sequence. Always paired with C<.end_return>

=head2 .begin_yield

X<.begin_yield directive>

Start a return of a coroutine sequence. Always paired with C<.end_yield>

=head2 .call

X<.call directive>

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

Create a subroutine call.

=head2 .pcc_sub

X<.pcc_sub directive>

  .pcc_sub R<_LABEL>

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

=head2 .pragma

X<.pragma directive>

  .pragma prototyped

Set default calling conventions.

=head2 .result

X<.result directive>

  .result R<DEST>

Get a return value according to PCC.

=head2 .return

X<.return directive>

  .return R<VAL>

Return a value to the calling subroutine according to PCC.

=head2 .sub

X<.sub directive>

  .sub R<NAME>

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

=head2 .sym

X<.sym directive>

  .sym R<TYPE> R<NAME>

Same as C<.local>.

=head1 PIR Instructions

Z<CHP-8-SECT-3>

X<PIR (Parrot intermediate representation);quick reference;instructions>
This section is a quick reference to PIR instructions. For more details
and the latest changes, see F<imcc/docs/syntax.pod> or dive into the
source code in F<imcc/imcc.l> and F<imcc/imcc.y>.

=head2 =

X<= (equal sign);= (assignment);instruction (PIR)>

  R<DEST> = R<VAL>

Assign a value to a particular register, temporary register, or named
variable.

=head2 +, +=

X<+ (plus sign);+ (addition);instruction (PIR)>
X<+ (plus sign);+= (addition assignment);instruction (PIR)>

  R<DEST> = R<VAL> + R<VAL>
  R<DEST> += R<VAL>

Add two numbers or PMCs.

=head2 -, -=

X<- (hyphen);- (subtraction);instruction (PIR)>
X<- (hyphen);-= (subtraction assignment);instruction (PIR)>
X<- (hyphen);- (negation);instruction (PIR)>

  R<DEST> = R<VAL1> - R<VAL2>
  R<DEST> -= R<VAL1>
  R<DEST> = - R<VAL>

Subtract R<VAL1> from R<VAL2>. The unary "C<->" negates a number.

=head2 *, *=

X<* (asterisk);* (multiplication);instruction (PIR)>
X<* (asterisk);*= (multiplication assignment);instruction (PIR)>

  R<DEST> = R<VAL> * R<VAL>
  R<DEST> *= R<VAL>

Multiply two numbers or PMCs.

=head2 /, /=

X</ (slash);/ (division);instruction (PIR)>
X</ (slash);/= (division assignment);instruction (PIR)>

  R<DEST> = R<VAL1> / R<VAL2>
  R<DEST> /= R<VAL1>

Divide R<VAL1> by R<VAL2>.

=head2 **

X<* (asterisk);** (exponentiation);instruction (PIR)>

  R<DEST> = R<VAL1> ** R<VAL2>

Raise R<VAL1> to the power of R<VAL2>.

=head2 %, %=

X<% (percent sign);% (modulus);instruction (PIR)>
X<% (percent sign);%= (modulus assignment);instruction (PIR)>

  R<DEST> = R<VAL1> % R<VAL2>
  R<DEST> %= R<VAL1>

Divide R<VAL1> by R<VAL2> and return the (C<mod>) remainder.

=head2 ., .=

X<. (dot);. (concatenation) instruction (PIR)>
X<. (dot);.= (concatenation assignment) instruction (PIR)>

  R<DEST> = R<VAL> . R<VAL>
  R<DEST> .= R<VAL>

Concatenate two strings. The concat operator must be surrounded by
whitespace.

=head2 E<lt>

X<E<lt> (left angle bracket);E<lt> (less than);instruction (PIR)>

  if R<VAL1> E<lt> R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is less than R<VAL2>.

=head2 E<lt>=

X<E<lt> (left angle bracket);E<lt>= (less than or equal);instruction (PIR)>

  if R<VAL1> E<lt>= R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is less than or equal to
R<VAL2>.

=head2 E<gt>

X<E<gt> (right angle bracket);E<gt> (greater than);instruction (PIR)>

  if R<VAL1> E<gt> R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is greater than R<VAL2>.

=head2 E<gt>=

X<E<gt> (right angle bracket);E<gt>= (greater than or equal);instruction (PIR)>

  if R<VAL1> E<gt>= R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is greater than or equal to
R<VAL2>.

=head2 ==

X<= (equal sign);== (equality);instruction (PIR)>

  if R<VAL1> == R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is equal to R<VAL2>.

=head2 !=

X<! (bang);!= (not equal);instruction (PIR)>

  if R<VAL1> != R<VAL2> goto R<LABEL>

Conditionally branch to a label if R<VAL1> is not equal to R<VAL2>.

=head2 &&

X<& (ampersand);&& (logical AND);instruction (PIR)>

  R<DEST> = R<VAL1> && R<VAL2>

Logical AND. Return R<VAL1> if it's false, otherwise return R<VAL2>.

=head2 ||

X<| (pipe);|| (logical OR);instruction (PIR)>

  R<DEST> = R<VAL1> || R<VAL2>

Logical OR. Return R<VAL1> if it's true, otherwise return R<VAL2>.

=head2 ~~

X<~ (tilde);~~ (logical XOR) instruction (PIR)>

  R<DEST> = R<VAL1> ~~ R<VAL2>

Logical XOR. If R<VAL1> is true and R<VAL2> is false, return R<VAL1>.
If R<VAL1> is false and R<VAL2> is true, return R<VAL2>. Otherwise,
return a false value.

=head2 !

X<! (bang);! (not);instruction (PIR)>

  R<DEST> = ! R<VAL>

Logical NOT. Return a true value if R<VAL> is false.

=head2 &, &=

X<& (ampersand);& (bitwise AND) instruction (PIR)>
X<& (ampersand);&= (bitwise AND assignment) instruction (PIR)>

  R<DEST> = R<VAL> & R<VAL>
  R<DEST> &= R<VAL>

Bitwise AND on two values.

=head2 |, |=

X<| (pipe);| (bitwise AND) instruction (PIR)>
X<| (pipe);|= (bitwise AND assignment) instruction (PIR)>

  R<DEST> = R<VAL> | R<VAL>
  R<DEST> |= R<VAL>

Bitwise OR on two values.

=head2 ~, ~=

X<~ (tilde);~ (bitwise XOR) instruction (PIR)>
X<~ (tilde);~= (bitwise XOR assignment) instruction (PIR)>

  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.

=head2 E<lt>E<lt>, E<lt>E<lt>=

X<E<lt> (left angle bracket);E<lt>E<lt> (bitwise left shift);instruction (PIR)>
X<E<lt> (left angle bracket);E<lt>E<lt>= (bitwise left shift assignment);instruction (PIR)>

  R<DEST> = R<VAL1> E<lt>E<lt> R<VAL2>
  R<DEST> E<lt>E<lt>= R<VAL2>

Bitwise shift R<VAL1> left by R<VAL2> number of bits.

=head2 E<gt>E<gt>, E<gt>E<gt>=

X<E<gt> (right angle bracket);E<gt>E<gt> (bitwise right shift);instruction (PIR)>
X<E<gt> (right angle bracket);E<gt>E<gt>= (bitwise right shift assignment);instruction (PIR)>

  R<DEST> = R<VAL1> E<gt>E<gt> R<VAL2>
  R<DEST> E<gt>E<gt>= R<VAL2>

Bitwise shift R<VAL1> right by R<VAL2> number of bits.

=head2 E<gt>E<gt>E<gt>, E<gt>E<gt>E<gt>=

X<E<gt> (right angle bracket);E<gt>E<gt>E<gt> (logical right shift) instruction (PIR)>
X<E<gt> (right angle bracket);E<gt>E<gt>E<gt>= (logical right shift assignment) instruction (PIR)>

  R<DEST> = R<VAL1> E<gt>E<gt>E<gt> R<VAL2>
  R<DEST> E<gt>E<gt>E<gt>= R<VAL2>

Logically shift R<VAL1> right by R<VAL2> number of bits.

=head2 [  ]

X<[] (brackets);indexed access to PMC (PIR)>

  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.

=head2 addr

X<addr instruction (PIR)>

  R<DEST> = addr R<LABEL>

Return the address of a label.

=head2 call

X<call instruction (PIR)>

  call R<NAME>

Call the named subroutine (a C<.sub> label).

=head2 global

X<global instruction (PIR)>

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

Access a global variable for read or write.

=head2 goto

X<goto command (PIR)>

  goto R<NAME>

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

=head2 if

X<if (conditional);instruction (PIR)>

  if R<EXPR> goto R<NAME>

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

=head2 unless

X<unless (conditional);instruction (PIR)>

  unless R<VAL> goto R<NAME>

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


=head1 Parrot Command-Line Options

Z<CHP-8-SECT-4>

X<command-line options (Parrot)>
X<Parrot;command-line options>
X<running.pod file>
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 F<imcc/docs/running.pod> should
have the latest details. Or just run F<parrot --help>.

=head2 General Usage

Z<CHP-8-SECT-4.1>

  parrot [options] file [arguments]

The R<file> is either an F<.pir> or F<.pasm> source file or a
Parrot bytecode file. Parrot creates an C<Array> object to hold the
command-line R<arguments> and stores it in C<P5> on program start.

=head2 Assembler Options

Z<CHP-8-SECT-4.2>

=over 4

=item -a, --pasm

X<Parrot;assembler options>
Assume PASM input on C<stdin>. When Parrot runs a source file with a
F<.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 C<stdin>.

=item -c,--pbc

Assume PBC file on C<stdin>. When Parrot runs a bytecode file with a
F<.pbc> extension, it immediately executes the file. This option tells
Parrot to immediately execute a bytecode file piped in on C<stdin>.

=item -d,--debug [R<hexbits>]

Turn on debugging output. The C<-d> switch takes an optional argument,
which is a hex value of debug bits. The individual bits are shown in
A<CHP-8-TABLE-3>Table 11-3. When R<hexbits> isn't specified,
the default debugging level is 0001. If R<hexbits> is separated
from the C<-d> switch by whitespace, it has to start with a number.

=begin table picture Debug bits

Z<CHP-8-TABLE-3>

=headrow

=row

=cell Description

=cell Debug bit

=bodyrows

=row

=cell DEBUG_PARROT

=cell 0001

=row

=cell DEBUG_LEXER

=cell 0002

=row

=cell DEBUG_PARSER

=cell 0004

=row

=cell DEBUG_IMC

=cell 0008

=row

=cell DEBUG_CFG

=cell 0010

=row

=cell DEBUG_OPT1

=cell 0020

=row

=cell DEBUG_OPT2

=cell 0040

=row

=cell DEBUG_PBC

=cell 1000

=row

=cell DEBUG_PBC_CONST

=cell 2000

=row

=cell DEBUG_PBC_FIXUP

=cell 4000

=end table

X<Parrot;debugging bits>
X<debugging bits (Parrot)>
To produce a huge output on C<stderr>, turn on all the debugging bits:

  $ parrot -d 0ffff ...


=item --help-debug

Show debug option bits.

=item -h,--help

Print a short summary of options to C<stdout> and exit.

=item -o R<outputfile>

Act like an assembler. With this switch Parrot won't run code unless
it's combined with the C<-r> switch. If the name of R<outputfile> ends
with a F<.pbc> extension, Parrot writes a Parrot bytecode file. If
R<outputfile> ends with a F<.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 C<-Op>
switch.

If the extension is F<.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 F<PLATFORMS> for which platforms support this.

=item -r,--run-pbc

Immediately execute bytecode. This is the default unless C<-o> is
present. The combination of C<-r> C<-o> C<output.pbc> writes a
bytecode file and executes the generated PBC.

=item -v,--verbose

One C<-v> switch (C<imcc> C<-v>) shows which files are worked on and
prints a summary of register usage and optimization statistics. Two
C<-v> switches (C<imcc> C<-v> C<-v>) also prints a line for each
individual processing step.

=item -y,--yydebug

Turn on C<yydebug> for F<yacc>/F<bison>.

=item -E,--pre-process-only

Show output of macro expansions and quit.

=item -V,--version

Print the program version to C<stdout> and exit.

=item -Ox

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

X<Parrot;optimizations>
X<optimizations (Parrot)>

=begin table picture Optimizations

Z<CHP-8-TABLE-4>

=headrow

=row

=cell Flag

=cell Meaning

=bodyrows

=row

=cell C<-O0>

=cell No optimization (default).

=row

=cell C<-O1>

=cell Optimizations without life info (e.g. branches and constants).

=row

=cell C<-O2>

=cell Optimizations with life info.

=row

=cell C<-Oc>

=cell Optimize function call sequence.

=row

=cell C<-Op>

=cell Rearrange PASM registers with the most-used first.

=end table

=back

=head2 Bytecode Interpreter Options

Z<CHP-8-SECT-4.3>

X<Parrot;bytecode interpreter options>
X<bytecode interpreter options (Parrot)>
X<computed goto core>
X<fast core>
The interpreter options are mainly for selecting which run-time core to
use for interpreting bytecode. The current default is the I<computed
goto core> if it's available. Otherwise the I<fast core> is used.

=over 4

=item -b,--bounds-checks

Activate bounds checking. This also runs with the I<slow core> as a
side effect.

=item -f,--fast-core

Run with the I<fast core>.

=item -g,--computed-goto-core

Run the I<computed goto core> (CGoto).

=item -j,--jit-core

Run with the I<JIT core> if available.

=item -p,--profile

Activate profiling. This prints a summary of opcode usage and
execution times after the program stops. It also runs within the
I<slow core>.

=item -C,--CGP-core

Run with the I<CGoto-Prederefed> core.

=item -P,--predereferenced-core

Run with the I<Prederefed core>.

=item -S,--switched-core

Run with the I<Switched core>.

=item -t,--trace

Trace execution. This also turns on the I<slow core>.

=item -w,--warnings

Turn on warnings.

=item -G,--no-gc

Turn off DOD/GC. This is for debugging only.

=item -.,--wait

Wait for a keypress before running.

=item --leak-test,--destroy-at-end

Cleanup up allocated memory when the final interpreter is destroyed.
C<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 C<Parrot> is run with a memory leak detector. To prevent
this, use this option.

=back

=cut
