ch13_reference.pod

=pod

=head1 Parrot Reference

Z<CHP-10>

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

=head2 PASM Opcodes

Z<CHP-10-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.

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

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

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

=head3 addattribute

X<addattribute opcode (PASM)>

  addattribute R<CLASS>, R<ATTR>

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

I<Arguments: P, S>

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

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

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

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

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

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

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

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

=head3 bnot

X<bnot opcode (PASM)>

  bnot R<DEST>, R<VAL>

Bitwise NOT on R<VAL>.

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

=head3 bnots

X<bnots opcode (PASM)>

  bnots R<DEST>, R<VAL>

Bitwise NOT on string R<VAL>.

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

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

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

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

=head3 branch

X<branch opcode (PASM)>

  branch R<LABEL>

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

I<Arguments: I>

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

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

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

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

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

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

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

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

=head3 checkevents

X<checkevents opcode (PASM)>

  checkevents

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

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

=head3 chr

X<chr opcode (PASM)>

  chr R<DEST>, R<INT>

Return the character represented by the given number.

I<Arguments: SR, I>

=head3 class

X<class opcode (PASM)>

  class R<CLASS>, R<OBJECT>

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

I<Arguments: P, P>

=head3 clear_eh

X<clear_eh>

  clear_eh

Clear the most recent exception handler.

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

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

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

=head3 close

X<close opcode (PASM)>

  close R<DEST>

Close the filehandle in the given register.

I<Arguments: P>

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

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

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

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

=head3 collect

X<collect opcode (PASM)>

  collect

Trigger a garbage collection (GC) run.

=head3 collectoff

X<collectoff opcode (PASM)>

  collectoff

Disable garbage collection runs (nestable).

=head3 collecton

X<collecton opcode (PASM)>

  collecton

Re-enable garbage collection runs.

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

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

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

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

=head3 cos

X<cos opcode (PASM)>

  cos R<DEST>, R<VAL>

The cosine of R<VAL> in radians.

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

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

=head3 debug

X<debug opcode (PASM)>

  debug R<FLAG>

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

I<Arguments: I>

=head3 dec

X<dec opcode (PASM)>

  dec R<DEST>

Decrement a value by 1.

I<Arguments: I or N or P>

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

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

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

=head3 delete

X<delete opcode (PASM)>

  delete R<DEST>[R<KEY>]

Delete a keyed value from an aggregate PMC.

I<Arguments: P>

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

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

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

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

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

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

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

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

=head3 end

X<end opcode (PASM)>

  end

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

=head3 enternative

X<enternative opcode (PASM)>

  enternative

Run the C<run_native> C function.

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

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

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

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

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

=head3 errorsoff

X<errorsoff opcode (PASM)>

  errorsoff R<VAL>

Turn off errors of type R<VAL>.

I<Arguments: I>

=head3 errorson

X<errorson opcode (PASM)>

  errorson R<VAL>

Turn on errors of type R<VAL>.

I<Arguments: I>

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

=head3 exists

X<exists opcode (PASM)>

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

Test a PMC key for existence.

I<Arguments: IR, P>

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

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

=head3 exsec

X<exsec opcode (PASM)>

  exsec R<DEST>, R<VAL>

The exsecant of R<VAL> in radians.

I<Arguments: NR, N>

=head3 fact

X<fact opcode (PASM)>

  fact R<DEST>, R<INT>

Return the factorial of R<INT>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=head3 getfile

X<getfile opcode (PASM)>

  getfile R<DEST>

Return the name of the current file.

I<Arguments: SR>

=head3 getinterp

X<getinterp opcode (PASM)>

  getinterp R<DEST>

Get a PMC representing the current interpreter.

I<Arguments: P>

=head3 getline

X<getline opcode (PASM)>

  getline R<DEST>

Return the current line number.

I<Arguments: IR>

=head3 getpackage

X<getpackage opcode (PASM)>

  getpackage R<DEST>

Return the current package name.

I<Arguments: SR>

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

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

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

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

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

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

=head3 hav

X<hav opcode (PASM)>

  hav R<DEST>, R<VAL>

The haversine of R<VAL> in radians.

I<Arguments: NR, N>

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

=head3 inc

X<inc opcode (PASM)>

  inc R<DEST>

Increment a value by one.

I<Arguments: IR or NR or P>

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

=head3 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-10-TABLE-1>Table 11-1.

=begin table picture Interpinfo flags

Z<CHP-10-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>

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

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

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

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

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

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

=head3 jump

X<jump opcode (PASM)>

  jump R<ADDRESS>

Jump to a specified absolute address.

I<Arguments: I>

See also: C<set_addr>.

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

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

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

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

=head3 length

X<length opcode (PASM)>

  length R<DEST>, R<STRING>

Return the character length of a string.

I<Arguments: IR, S>

=head3 ln

X<ln opcode (PASM)>

  ln R<DEST>, R<VAL>

The natural logarithm of R<VAL>.

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

=head3 load_bytecode

X<load_bytecode>

  load_bytecode R<FILE>

Load Parrot bytecode from a file.

I<Arguments: S>

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

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

=head3 log10

X<log10 opcode (PASM)>

  log10 R<DEST>, R<VAL>

The base 10 logarithm of R<VAL>.

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

=head3 log2

X<log2 opcode (PASM)>

  log2 R<DEST>, R<VAL>

The base 2 logarithm of R<VAL>.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=head3 newclass

X<newclass opcode (PASM)>

  newclass R<DEST>, R<NAME>

Create a new class with the given name.

I<Arguments: P, S>

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

=head3 noop

X<noop opcode (PASM)>

  noop

Do nothing.

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

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

=head3 open

X<open opcode (PASM)>

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

Open a file in the specified mode ("r", "w", etc.) and return
a filehandle. Without the mode it defaults to read/write.

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

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

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

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

=head3 peek_pad

X<peek_pad opcode (PASM)>

  peek_pad R<DEST>

Store the current lexical scope pad in a PMC.

I<Arguments: P>

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

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

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

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

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

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

=head3 printerr

X<printerr opcode (PASM)>

  printerr R<VAL>

Print a value to C<stderr>.

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

=head3 profile

X<profile opcode (PASM)>

  profile R<INT>

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

I<Arguments: I>

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

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

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

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

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

=head3 readline

X<readline opcode (PASM)>

  readline R<DEST>, R<IO>

Read a line from a Parrot I/O object.

I<Arguments: SR, P>

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

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

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

=head3 restoretop

X<restoretop opcode (PASM)>

  restoretop

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

See also: C<savetop>.

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

=head3 rethrow

X<rethrow opcode (PASM)>

  rethrow R<EXCEPTION>

Rethrow an exception. Only valid inside an exception handler.

I<Arguments: P>

See also: C<throw>

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

=head3 sec

X<sec opcode (PASM)>

  sec R<DEST>, R<VAL>

The secant of R<VAL> in radians.

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

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

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

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

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

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

=head3 set_chartype

X<set_chartype opcode (PASM)>

  set_chartype R<STRING>, R<CHARTYPE>

Set the chartype of a string.

I<Arguments: S, I>

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

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

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

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

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

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

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

=head3 sin

X<sin opcode (PASM)>

  sin R<DEST>, R<VAL>

The sine of R<VAL> in radians.

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

=head3 singleton

X<singleton opcode (PASM)>

  singleton R<DEST>

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

I<Arguments: P>

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

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

=head3 sleep

X<sleep opcode (PASM)>

  sleep R<SECONDS>

Sleep for the given number of seconds.

I<Arguments: I or N>

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

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

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

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

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

=head3 string_chartype

X<string_chartype opcode (PASM)>

  string_chartype R<DEST>, R<STRING>

Return the chartype of the string.

I<Arguments: IR, S>

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

=head3 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-10-TABLE-2>Table 11-2.

=begin table picture Stringinfo arguments

Z<CHP-10-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>

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

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

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


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

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

=head3 sweepoff

X<sweepoff opcode (PASM)>

  sweepoff

Disable DOD sweeps (nestable).

=head3 sweepon

X<sweepon opcode (PASM)>

  sweepon

Re-enable DOD sweeps.

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

=head3 tan

X<tan opcode (PASM)>

  tan R<DEST>, R<VAL>

The tangent of R<VAL> in radians.

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

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

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

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

=head3 throw

X<throw opcode (PASM)>

  throw R<EXCEPTION>

Throw an exception.

I<Arguments: P>

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

=head3 time

X<time opcode (PASM)>

  time R<DEST>

Return the current system time.

I<Arguments: IR or NR>

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

=head3 trace

X<trace opcode (PASM)>

  trace R<INT>

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

I<Arguments: I>

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

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

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

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

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

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

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

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

I<Arguments: IR, I>

=head3 vers

X<vers opcode (PASM)>

  vers R<DEST>, R<VAL>

The versine of R<VAL> in radians.

I<Arguments: NR, N>

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

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

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

=head2 PIR Directives

Z<CHP-10-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.


=head3 .arg

X<.arg directive>

  .arg R<VAL>

pass a value to a subroutine according to PCC.

=head3 .const

X<.const directive>

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

Define a named constant.

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

=head3 .emit

X<.emit directive>

  .emit

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

=head3 .end

X<.end directive>

  .end

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

=head3 .endm

X<.endm directive>

  .endm

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

=head3 .eom

X<.eom directive>

  .eom

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

=head3 .flatten_arg

X<.flatten_arg directive>

  .flatten_arg R<PArray>

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

=head3 .globalconst

X<.cglobalonst directive>

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

Define a named, file visible constant.

=head3 .include

X<.include directive>

  .include " R<FILENAME> "

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

=head3 .invocant

X<.invocant directive>

  .invocant R<OBJ>

Set the invocant for a method call.

=head3 .local

X<.local directive>

  .local R<TYPE>R<NAME>

Define a local named variable.

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

=head3 .meth_call

X<.meth_call directive>

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

Create a method call.

=head3 .namespace

X<.namespace directive>

  .namespace R< [ "namespace" ] >

Define a namespace.

=head3 .nci_call

X<.nci_call directive>

  .nci_call R<SUB>

Create an NCI call.

=head3 .param

X<.param directive>

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

Define a subroutine parameter.

=head3 .begin_call

X<.begin_call directive>

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

=head3 .begin_return

X<.begin_return directive>

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

=head3 .begin_yield

X<.begin_yield directive>

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

=head3 .call

X<.call directive>

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

Create a subroutine call.

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

=head3 .result

X<.result directive>

  .result R<DEST>

Get a return value according to PCC.

=head3 .return

X<.return directive>

  .return R<VAL>

Return a value to the calling subroutine according to PCC.

=head3 .sub

X<.sub directive>

  .sub R<NAME>

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

=head3 .sym

X<.sym directive>

  .sym R<TYPE> R<NAME>

Same as C<.local>.

=head2 PIR Instructions

Z<CHP-10-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>.

=head3 =

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

  R<DEST> = R<VAL>

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

=head3 +, +=

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.

=head3 -, -=

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.

=head3 *, *=

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.

=head3 /, /=

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

=head3 **

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

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

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

=head3 %, %=

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.

=head3 ., .=

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.

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

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

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

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

=head3 ==

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

=head3 !=

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

=head3 &&

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

=head3 ||

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

=head3 ~~

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.

=head3 !

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

  R<DEST> = ! R<VAL>

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

=head3 &, &=

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.

=head3 |, |=

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.

=head3 ~, ~=

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.

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

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

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

=head3 [  ]

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.

=head3 call

X<call instruction (PIR)>

  call R<NAME>

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

=head3 global

X<global instruction (PIR)>

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

Access a global variable for read or write.

=head3 goto

X<goto command (PIR)>

  goto R<NAME>

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

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

=head3 unless

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

  unless R<VAL> goto R<NAME>

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


=head2 Parrot Command-Line Options

Z<CHP-10-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>.

=head3 General Usage

Z<CHP-10-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.

=head3 Assembler Options

Z<CHP-10-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-10-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-10-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-10-TABLE-4>Table 11-4.

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

=begin table picture Optimizations

Z<CHP-10-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

=head3 Bytecode Interpreter Options

Z<CHP-10-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

##########################################################################
#                              PSEUDOPOD LEGEND
#
#  Interior Sequences
#  ..................
#  A<>         link anchor (source)
#  B<>         bold text
#  C<>         monospace text
#  E<>         named character
#  F<>         file name
#  G<>         superscript
#  H<>         subscript
#  I<>         italicized text
#  L<>         link to other manpage (see A<>)
#  M<>         firstterm
#  N<>         footnote
#  Q<>         quoted text
#  R<>         replaceable item
#  S<>         text with non-breaking spaces
#  T<>         cited title for book, etc.
#  U<>         URL
#  X<>         a single index term of the form:
#                    primary:sortas;secondary:sortas;tertiary:sortas;;ETC
#                    where ETC is either (see term) or (see also term)
#                    only primary term is required
#  Z<>         link anchor (destination)
#
#  Heads
#  .....
#  head0                    chapter title
#  head{1-4}                section title (4 levels)
#
#  Command Paragraphs (begin/end Blocks)
#  .....................................
#  blockquote               quotation
#  comment                  ignored text
#  caution                  admonition
#  epigraph                 quotation
#  example                  container
#  figure CAPTION           figure
#  important                admonition
#  note                     admonition
#  programlisting           literal text
#  screen                   literal text
#  sidebar                  container
#  table html [CAPTION]     table rendered in HTML
#  table picture [CAPTION]  table rendered in plain text
#  tip                      admonition
#  warning                  admonition
#
#
#  Command Paragraphs (for Blocks)
#  ...............................
#  This structure will be used only for comments. For example:
#
#    =for editor
#    Check my spelling on this.
#    =end
#
#  This will be rendered as a visible comment in the final output
#  with a label at the top addressing it to "editor". The exception is
#  =for ignore which will always be ignored by the parser.
#
#  Tables
#  ......
#  A 2x2 table with top header row looks like this:
#  
#  =begin table An Example Table
#  =headrow
#  =row
#  =cell Header for first column (row 1, col 1)
#  =cell Header for 2nd column (row 1, col 2)
#  =bodyrows
#  =cell Cell for row 2, col 1
#  =cell Cell for row 2, col 2
#  =end table
#
#  For more information on PSEUDOPOD, write to tools@oreilly.com
##########################################################################

# Local variables:
#   c-file-style: "parrot"
# End:
# vim: expandtab shiftwidth=4: