Index: docs/book/ch03_pir_basics.pod =================================================================== --- docs/book/ch03_pir_basics.pod (revision 32143) +++ docs/book/ch03_pir_basics.pod (working copy) @@ -1,6 +1,6 @@ =pod -=head1 Parrot Intermediate Representation +=head0 Parrot Intermediate Representation Z @@ -22,21 +22,22 @@ X<.pasm files> A file with a F<.pasm> extension is treated as pure PASM code by Parrot, as is any file run with the C<-a> command-line option. This mode is mainly used for running pure PASM tests, and is not likely -to be useful for most developers. Parrot treats any extension other than -F<.pasm> as a PIR file in mixed mode. X<.pir files> As a convention, files -containing pure PIR code generally have a F<.pir> extension. +to be useful for most developers. Parrot will treat a file with any +extension other than F<.pasm> as a PIR file in mixed mode. +X<.pir files> As a convention, files containing pure PIR code generally +have a F<.pir> extension. X -PIR is well documented, both in traditional documentation but also in +PIR is well documented, both in traditional documentation and in instructional code examples. The documentation for the PIR compiler IMCC in F or the project documentation in F are good sources for information. The test suite in F shows examples of proper working code as it should be. These are all good starting points for digging deeper into the PIR syntax and functionality. -=head2 Statements +=head1 Statements -Z +Z X X @@ -64,9 +65,9 @@ We will get into all of these in more detail as we go. -=head2 Variables and Constants +=head1 Variables and Constants -Z +Z X X @@ -75,9 +76,9 @@ and floating-point numbers are numeric literals and strings are enclosed in quotes. PIR strings use the same escape sequences as PASM. -=head3 Parrot Registers +=head2 Parrot Registers -Z +Z PIR code has a variety of ways to store values while you work with them. The most basic way is to use Parrot registers directly. PASM @@ -99,13 +100,13 @@ memory management situation, fewer allocations translates directly to improved performance. -=head3 Temporary Registers +=head2 Temporary Register Variables -Z +Z -X<$ (dollar sign);for temporary registers (PIR)> -X -X +X<$ (dollar sign);for temporary register variables (PIR)> +X +X PIR provides an easier way to work with Parrot registers. The temporary register variables are named like the PASM registers--with a single character for the type of register and a number--but they start @@ -146,7 +147,7 @@ Parrot actually uses in these situations is based on a large number of factors. -Parrot allocates temporary registersN to Parrot registers in ascending order based on their I. The score is used to determine whether a register is being actively used, and whether it can be reused for @@ -196,11 +197,11 @@ to see resulting PASM on I. You'll find more details on these options and many others in -A"Parrot Command-Line Options" in Chapter 11. +A"Parrot Command-Line Options" in Chapter 13. -=head3 Named Variables +=head2 Named Variables -Z +Z X X @@ -230,9 +231,9 @@ opcode names are normally not allowed as variable names, though there are some exceptions. -=head3 PMC variables +=head2 PMC variables -Z +Z PMC registers and variables act much like any integer, floating-point number, or string register or variable, but you have to instantiate a @@ -260,9 +261,9 @@ hello = "Hello, Polly.\n" print hello -=head3 Named Constants +=head2 Named Constants -Z +Z X X @@ -283,9 +284,9 @@ .const string mouse = "Mouse" # string constant .const num pi = 3.14159 # floating point constant -=head3 Register Spilling +=head2 Register Spilling -Z +Z X X @@ -341,9 +342,9 @@ on the hashed value of the variable name. Parrot randomizes the seed to the hash function to guarantee you never get a consistent order. -=head2 Symbol Operators +=head1 Symbol Operators -Z +Z X You probably noticed the C<=> assignment operator in some of the @@ -354,7 +355,7 @@ Standing alone, it's the same as the PASM C opcode. In fact, if you run F in bytecode debugging mode (as in -A"Assembler Options" in Chapter 11), you'll see it +A"Assembler Options" in Chapter 11), you'll see it really is just a C opcode underneath. PIR has many other symbol operators: arithmetic, concatenation, @@ -384,22 +385,20 @@ $P0 = newclass "Foo" ... -A complete list of PIR operators is available in AChapter 11. -We'll discuss the comparison operators in A"Symbol -Operators" later in this chapter. +A complete list of PIR operators is available in AChapter 13. -=head2 Labels +=head1 Labels -Z +Z X X Like PASM, any line can start with a label definition like C, but label definitions can also stand on their own line. -PIR code has 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 +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 compilation unit where it's defined.N The name has to be unique there, but it can be reused in a different @@ -413,7 +412,7 @@ =head2 Compilation Units -Z +Z X X @@ -432,7 +431,7 @@ This example defines a compilation unit named C<_main> that prints a string. The name is actually a global label for this piece of code. If you generate a PASM file from the PIR code (see the end of the -A"Temporary Registers" section earlier in this +A"Temporary Register Variables" section earlier in this chapter), you'll see that the name translates to an ordinary label: _main: @@ -457,12 +456,12 @@ This code prints out "Hello, Polly." but not "Polly want a cracker?": -The A"Subroutines" section later in this chapter goes -into much more detail about compilation units and their uses. +AChapter 4 goes into much more detail about compilation units +and their uses. -=head2 Flow Control +=head1 Flow Control -Z +Z X X @@ -526,7 +525,7 @@ statement translates directly to the PASM C branch operation. The rest of the comparison operators are summarized in -A"PIR Instructions" in Chapter 11. +A"PIR Instructions" in Chapter 11. X X