=pod 

=head0 Parrot Intermediate Representation

Z<CHP-3>

X<Parrot Intermediate Representation;;(see PIR)>
X<PIR (Parrot intermediate representation)>
The Parrot intermediate representation (PIR) is an overlay on top of the
Parrot assembly language (PASM). PIR provides some simplifications and
high-level constructs to simplify programming tasks above what an
assembly language like PASM typically would have. It has many
high-level features that will be familiar to programmers, but
it still isn't considered to be a high-level language by itself. In fact,
the Parrot developers specifically want to keep in that way for a
number of reasons. PASM, the Parrot assembly language on which PIR is
based, is discussed in more detail in A<CHP-5>Chapter 5.

X<.pir files> As a convention, files containing pure PIR code generally 
have a F<.pir> extension. Parrot will treat a file with any other
extension, besides F<.pasm> as a PIR file in mixed mode. This means that
the file can contain PIR and PASM code interchangably, with a few caveats
that will be discussed later.

X<PIR (Parrot intermediate representation);documentation>
PIR is well documented, both in traditional documentation and in
instructional code examples. The documentation for the PIR compiler IMCC
in F<imcc/docs/> or the project documentation in F<docs/> are good
sources for information about the current syntax, semantics, and
implementation. The other PIR compiler, PIRC, has it's own documentation
that is slowly maturing. This is a useful source of information too. The
test suite in F<imcc/t> shows examples of proper working code. In fact,
the test suite is the definitive PIR resource, because it shows how PIR
I<actually works>, even when the documentation may be out of date. 

=head1 Statements

Z<CHP-3-SECT-1>

X<statements (PIR)>
X<PIR (Parrot intermediate representation);statements>
The syntax of statements in PIR is much more flexible then is commonly
found in assembly languages, but is more rigid and "close to the machine"
then some higher-level languages like C are. PIR has a very close
relationship with the Parrot assembly language, PASM. All PASM instructions
are valid PIR instructions. PIR does add some extra syntactic options to
help improve readability and programmability, however. The statement
delimiter for both PIR and PASM is a newline C<\n>. Each statement has to
be on its own line N<This isn't entirely true when you consider things like
macros and heredocs, but we'll tackle those issues when we come to them.>,
but empty whitespace lines between statements are okay. Statements may also
start with a label, for use with jumps and branches. Comments are marked by
a hash sign (C<#>), and continue until the end of the line. POD blocks may
be used for multi-line documentation.

To help with readability, PIR has some high-level constructs, including
symbol operators:

  $I1 = 5                       # set $I1, 5

named variables:

  count = 5

and complex statements built from multiple keywords and symbol
operators:

  if $I1 <= 5 goto LABEL        # le $I1, 5, LABEL

We will get into all of these in more detail as we go. Notice that PIR
does not, and will not, have high-level looping structures like C<while>
or C<for> loops and C<if>/C<then>/C<else> branch structures. Because of
these omissions PIR can become a little bit messy and unweildy for large
programs. Luckily, there are a large group of high-level languages (HLL)
that can be used to program Parrot instead. PIR is used primarily to
write the compilers and libraries for these languages.

=head1 Variables and Constants

Z<CHP-3-SECT-2>

=head2 Parrot Registers

Z<CHP-3-SECT-2.1>

PIR code has a variety of ways to store values while you work with
them. Actually, the only place to store values is in a Parrot register,
but there are multiple ways to work with these registers. Parrot's
register names always start with a dollar sign, followed by a single
character that shows whether it is an integer (I), numeric (N), string
(S), or PMC (P) register, and then the number of the register:

  $S0 = "Hello, Polly.\n"
  print $S0

You can have as many registers of each type as you need, Parrot will
automatically allocate new ones for you. The process is transparent, and
programmers should never have to worry about it.

Parrot registers are allocated in a linear array, and register numbers
are indices into this array. Having more registers means Parrot must
allocate more storage space for them, which can decrease memory efficency
and register allocation/fetch performance. In general, it's better to
keep the number of registers small. However, the number of the register
does not necessarily correspond to the actual storage location where the
register data is held. A memory allocator unit translates register names
in the form "$S0" into an actual fixed memory location. This allocator
can also help to optimize register usage so that existing registers are
reused instead of allocating new ones in memory. The sort version is that
the programmer should never have to worry about register allocation, and
should feel free to use as many as she wants. As with any system, it's
a good idea to be mindful of the things that might impact performance
anyway.



=head2 Constants

X<constants (PIR)>
X<PIR (Parrot intermediate representation);constants>
X<strings;in PIR>
Parrot has four primary data types: integers, floating-point numbers,
strings, and PMCs. Integers and floating-point numbers can be specified
in the code with numeric constants.

  $I0 = 42       # Integers are regular numeric constants
  $I1 = -1       # They can be negative or positive
  $I2 = 0xA5     # They can also be hexadecimal
  $I3 = 046      # ...or octal

  $N0 = 3.14     # Numbers can have a decimal point
  $N1 = 4        # ...or they don't
  $N2 = -1.2e+4  # Numbers can also use scientific notation.
  
String literals are enclosed in single or double-quotes:

  $S0 = "This is a valid literal string"
  $S1 = 'This is also a valid literal string'

Strings in double-quotes accept all sorts of escape sequences using
backslashes. Strings in single-quotes only allow escapes for nested
quotes:

  $S0 = "This string is \n on two lines"
  $S0 = 'This is a \n one-line string with a slash in it'

Or, if you need more flexibility, you can use a heredoc:

  $S2 = << "End_Token"
  
  This is a multi-line string literal. Notice that
  it doesn't use quotation marks. The string continues
  until the ending token (the thing in quotes next to
  the << above) is found.
  
  End_Token

=head2 Named Variables

Z<CHP-3-SECT-2.3>

X<named variables (PIR)>
X<PIR (Parrot intermediate representation);named variables>
Calling a value "$S0" isn't very descriptive, and usually it's a lot
nicer to be able to refer to values using a helpful name. For this
reason Parrot allows registers to be given temporary variable names to
use instead. These named variables can be used anywhere a register
would be used normally  N<...because they actually are registers, but
with fancier names>. They're declared with the C<.local> statement
which requires a variable type and a name:

  .local string hello
  set hello, "Hello, Polly.\n"
  print hello

This snippet defines a string variable named C<hello>, assigns it the
value "Hello, Polly.\n", and then prints the value.

X<types;variable (PIR)>
X<variables;types (PIR)>
The valid types are C<int>, C<num>, C<string>, and C<pmc> or any
Parrot class name (like C<PerlInt> or C<PerlString>). It should come
as no surprise that these are the same divisions as Parrot's four
register types. Named variables are valid from the point of their
definition to the end of the current function.

The name of a variable must be a valid PIR identifier. It can contain
letters, digits, and underscores, but the first character has to be a
letter or underscore. There is no limit to the length of an identifier,
especially since the automatic code generators in use with the various
high-level languages on parrot tend to generate very long identifier
names in some situations. Of course, making huge identifier names could
cause all sorts of memory allocation problems or inefficiencies in
parsing. Push the limits at your own risk.

=head2 PMC variables

Z<CHP-3-SECT-2.4>

PMC registers and variables act much like any integer, floating-point
number, or string register or variable, but you have to instantiate a
new PMC object before you use it. The C<new> instruction creates a new
PMC of a specified type:

  $P0 = new 'PerlString'     # This is how the Perl people do it
  $P0 = "Hello, Polly.\n"
  print $P0

This example creates a C<PerlString> object, stores it in the PMC
register C<$P0>, assigns the value "Hello, Polly.\n" to it, and prints
it.  With named variables the type passed to the C<.local> directive is
either the generic C<pmc> or a type compatible with the type passed to
C<new>:

  .local PerlString hello    # or .local pmc hello
  hello = new PerlString
  hello = "Hello, Polly.\n"
  print hello

PIR is a dynamic language, and that dynamicism is readily displayed in
the way PMC values are handled. Primitive registers like strings,
numbers, and integers perform a special action called I<autoboxing>
when they are assigned to a PMC. Autoboxing is when a primative scalar
type is automatically converted to a PMC object type. There are PMC
classes for String, Number, and Integer which can be quickly converted
to and from primitive int, number, and string types. Notice that the
primative types are in lower-case, while the PMC classes are
capitalized. We will discuss PMCs and all the details of their
interactions in A<CHP-11> Chapter 11.

=head2 Named Constants

Z<CHP-3-SECT-2.5>

X<PIR (Parrot intermediate representation);named constants>
X<named constants (PIR)>
The C<.const> directive declares a named constant. It's very similar
to C<.local>, and requires a type and a name. The value of a constant
must be assigned in the declaration statement. As with named
variables, named constants are visible only within the compilation
unit where they're declared. This example declares a named string
constant C<hello> and prints the value:

  .const string hello = "Hello, Polly.\n"
  print hello

Named constants function in all the same places as literal constants,
but have to be declared beforehand:

  .const int the_answer = 42        # integer constant
  .const string mouse = "Mouse"     # string constant
  .const num pi = 3.14159           # floating point constant

=head1 Symbol Operators

Z<CHP-3-SECT-3>

X<symbol operators in PIR>
PIR has many other symbol operators: arithmetic, concatenation,
comparison, bitwise, and logical. All PIR operators are translated
into one or more PASM opcodes internally, but the details of this
translation stay safely hidden from the programmer. Consider this
example snippet:

  .local int sum
  sum = $I42 + 5
  print sum
  print "\n"

The statement C<sum = $I42 + 5> translates to something like
C<add I16, I17, 5> in PASM. The exact translation isn't too important
N<Unless you're hacking on IMCC or PIRC!>, so we don't have to worry
about it for now. We will talk more about PASM and it's instruction
set in X<CHP-5> Chapter 5.

PIR also provides automatic assignment operators such as C<+=>, C<-=>,
and C<<< >>= >>>. These operators help programmers to peform common
manipulations on a data value in place, and save a few keystrokes while
doing them.

A complete list of PIR operators is available in A<CHP-13> Chapter 13.

=head1 Labels

Z<CHP-3-SECT-4>

X<PIR (Parrot intermediate representation);labels>
X<labels (PIR)>
Any line in PIR can start with a label definition like C<LABEL:>,
but label definitions can also stand on their own line. Labels are like
flags or markers that the program can jump to or return to at different
times. Labels and jump operations (which we will discuss a little bit
later) are one of the primary methods to change control flow in PIR, so
it is well worth understanding.

PIR code can contain both local and global labels. Global labels start 
with an underscore. The name of a global label has to be unique since 
it can be called at any point in the program. Local labels start with a
letter. A local label is accessible only in the function where it is
defined. The name has to be unique within that function, but the same
name can be reused in other functions without causing a collision.

  branch L1   # local label
  bsr    _L2  # global label

Labels are most often used in branching instructions, which are used
to implement high level control structures by our high-level language
compilers.

=head2 Compilation Units

Z<CHP-3-SECT-4.1>

X<PIR (Parrot intermediate representation);compilation units>
X<compilation units (PIR)>
Compilation units in PIR are roughly equivalent to the subroutines or
methods of a high-level language. Though they will be explained in
more detail later, we introduce them here because all code in a PIR
source file must be defined in a compilation unit. The simplest syntax
for a PIR compilation unit starts with the C<.sub> directive and ends
with the C<.end> directive:

  .sub main
      print "Hello, Polly.\n"
  .end

This example defines a compilation unit named C<main> that prints a
string.The first compilation unit in a file is normally executed
first but you can flag any compilation unit as the first one to
execute with the C<:main> marker. The convention is to name the first
compilation unit C<main>, but the name isn't critical.

  .sub first
      print "Polly want a cracker?\n"
      end
  .end

  .sub main :main
      print "Hello, Polly.\n"
  .end

This code prints out "Hello, Polly." but not "Polly want a cracker?".
This is because the function C<main> has the C<:main> flag, so it is
executed first. The function C<first>, which doesn't have this flag
is never executed. However, if we change around this example a little:

  .sub first :main
      print "Polly want a cracker?\n"
      end
  .end

  .sub main
      print "Hello, Polly.\n"
  .end

The output now is "Polly want a cracker?". Execution in PIR starts
at the main function and continues until the end of that function only.
If you want to do more stuff if your program, you will need to call
other functions explicitly.

A<CHP-04>Chapter 4 goes into much more detail about compilation units 
and their uses.

=head1 Flow Control

Z<CHP-3-SECT-5>

X<PIR (Parrot intermediate representation);flow control>
X<flow control;in PIR>
Flow control in PIR is done entirely with conditional and
unconditional branches. This may seem simplistic and primitive, but
remember that PIR is a thin overlay on the assembly language of a
virtual processor. High level control structures are invariably linked
to the language in which they are used, so any attempt by Parrot to
provide these structures would work for some languages but not by
others. The only way to make sure all languages and their control
structures can be equally accomdated is to simply give them the most
simple and fundamental building blocks to work with. Language
agnosticism is an important design goal in Parrot. 

X<goto instruction (PIR)>
The most basic branching instruction is the unconditional branch:
C<goto>.

  .sub _main
      goto L1
      print "never printed"
  L1:
      print "after branch\n"
      end
  .end

The first C<print> statement never runs because the C<goto> always
skips over it to the label C<L1>.

The conditional branches combine C<if> or C<unless> with C<goto>.

  .sub _main
      $I0 = 42
      if $I0 goto L1
      print "never printed"
  L1: print "after branch\n"
      end
  .end

X<if (conditional);instruction (PIR)>
X<unless (conditional);instruction (PIR)>
In this example, the C<goto> branches to the label C<L1> only if the
value stored in C<$I0> is true. The C<unless> statement is quite
similar, but branches when the tested value is false. An undefined
value, 0, or an empty string are all false values. Any other values
are considered to be true values.

The comparison operators (C<E<lt>>, C<E<lt>=>, C<==>, C<!=>, C<E<gt>>,
C<E<gt>=>) can combine with C<if ...  goto>. These branch when the
comparison is true:

  .sub _main
      $I0 = 42
      $I1 = 43
      if $I0 < $I1 goto L1
      print "never printed"
  L1:
      print "after branch\n"
      end
  .end

This example compares C<$I0> to C<$I1> and branches to the label C<L1>
if C<$I0> is less than C<$I1>. The C<if $I0 E<lt> $I1 goto L1>
statement translates directly to the PASM C<lt> branch operation.

The rest of the comparison operators are summarized in
A<CHP-13-SECT-3>"PIR Instructions" in Chapter 11.

X<loops;PIR>
X<PIR (Parrot intermediate representation);loop constructs>
PIR has no special loop constructs. A combination of conditional and
unconditional branches handle iteration:

  .sub _main
      $I0 = 1               # product
      $I1 = 5               # counter

  REDO:                     # start of loop
      $I0 = $I0 * $I1
      dec $I1
      if $I1 > 0 goto REDO  # end of loop

      print $I0
      print "\n"
      end
  .end

X<do-while style loop;(PIR)>
This example calculates the factorial C<5!>. Each time through the
loop it multiplies C<$I0> by the current value of the counter C<$I1>,
decrements the counter, and then branches to the start of the loop.
The loop ends when C<$I1> counts down to 0 so that the C<if> doesn't
branch to C<REDO>. This is a I<do while>-style loop with the condition
test at the end, so the code always runs the first time through.

X<while-style loop (PIR)>
For a I<while>-style loop with the condition test at the start, use a
conditional branch together with an unconditional branch:

  .sub _main
      $I0 = 1               # product
      $I1 = 5               # counter

  REDO:                     # start of loop
      if $I1 <= 0 goto LAST
      $I0 = $I0 * $I1
      dec $I1
      goto REDO
  LAST:                     # end of loop

      print $I0
      print "\n"
      end
  .end

This example tests the counter C<$I1> at the start of the loop. At the
end of the loop, it unconditionally branches back to the start of the
loop and tests the condition again. The loop ends when the counter
C<$I1> reaches 0 and the C<if> branches to the C<LAST> label.  If the
counter isn't a positive number before the loop, the loop never
executes.

Any high-level flow control construct can be built from conditional
and unconditional branches.

Fortunately, libraries of macros have been developed that can implement
more familiar syntax for many of these control structures. We will discuss
these libraries in more detail in A<CHP-6> "PIR Standard Library".

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