# One first version of this article was published on TPR 2.3 # # Please feel free to edit it to suit latest parrot developments, # and to be a good starting point for beginners. =head1 Writing PIR PIR (Parrot Intermediate Representation) is a way to program the parrot virtual machine that is easier to use than PASM (Parrot Assembler). PASM notation is like any other assembler-like format and can be used directly, but it is more verbose and gives too much power to the user. PIR abstracts common operations and conventions into a syntax that more closely resembles a high-level language. PIR allows the programmer to write code that more naturally expresses their intent without worrying about setting up the exact details that PASM requires to function properly. This article will show the basics on programming in PIR. More advanced topics will appear in later articles. =head2 Getting Parrot In order to test the PIR and PASM code in this article, a parrot virtual machine is needed (henceforth just "parrot"). Parrot is available from L<http://parrot.org>. Just download the latest release, or checkout the current development version from the Git repository. The programs in this article were tested with Parrot 0.8.1. Parrot is very easy to compile on unix-like and Microsoft Windows operating systems: just run C<perl Configure.pl && make> in the root directory of the parrot source and, if everything works correctly, a C<parrot> executable should appear. At the moment of writing, the C<make install> target does not work properly, so in this and other articles it is assumed that the parrot executable is invoked from the parrot root directory. If you do not want to compile your own Parrot you can download a pre-compiled binary from http://www.parrot.org/source.html. =head2 Parrot Virtual Machine overview Before we get started with the examples, here's a quick overview of parrot's architecture. Parrot is a register-based virtual machine. It provides 4 types of registers. The register types are: =over 4 =item I - integer =item N - floating point =item S - string =item P - polymorphic container (PMC) =back In order to designate a register in PASM, use the character indicating the type (C<I>, C<N>, C<S> or C<P>) and the register number. For instance, in order to use register 10 of type integer, you'd write C<I10>. In this series of articles, we will mainly focus on programming PIR. In PIR, you would type the C<$> character in front of the register, to indicate a I<virtual> register. For instance, the integer registers are C<$I0>, C<$I1> and so on. The PMC registers hold arbitrary data objects and are parrot's mechanism for implementing more complex behavior than the ones that can be expressed using the other 3 register types alone. A virtual register is mapped to an actual register by the register allocator. You can use as many registers as you want, and the register allocator will allocate them as needed. PMCs will be covered in more detail in a future article. Examples in this article will focus on the first 3 register types. =head2 Simple Operators Let me start with a simple and typical example: =begin PIR .sub main :main print "hello world\n" .end =end PIR To run it, save the code in a C<hello.pir> file and pass it to the parrot virtual machine: ./parrot hello.pir Note that I am using a relative path to parrot given that I didn't install it into the system. The keywords starting with a dot (C<.sub> and C<.end>) are PIR directives. They are used together to define subroutines. After the C<.sub> keyword I use the name of the subroutine. The keyword that starts with a colon (C<:main>) is a pragma that tells parrot that this is the main body of the program and that it should start by executing this subroutine. By the way, I could use C<.sub foo :main> and Parrot will use the C<foo> subroutine as the main body of the program. The actual name of the subroutine does not matter as long as it has the C<:main> pragma. If you don't specify the <:main> pragma on any subroutine, then parrot will start executing the first subroutine in the source file. The full set of pragmas are defined in L<docs/pdds/pdd19_pir.pod>. Before going into more details about subroutines and calling conventions, let's compare some PIR syntax to the equivalent PASM. If I want to add two integer registers using PASM I would use the Parrot C<set> opcode to put values into registers, and the C<add> opcode to add them, like this: =begin PIR_FRAGMENT set $I1, 5 set $I2, 3 add $I0, $I1, $I2 # $I0 yields 5+3 =end PIR_FRAGMENT PIR includes infix operators for these common opcodes. I could write this same code as =begin PIR_FRAGMENT $I1 = 5 $I2 = 3 $I0 = $I1 + $I2 =end PIR_FRAGMENT There are the four arithmetic operators as you should be expecting, as well as the six different comparison operators, which return a boolean value: =begin PIR_FRAGMENT $I1 = 5 $I2 = 3 $I0 = $I1 <= $I2 # $I0 yields 0 (false) =end PIR_FRAGMENT I can also use the short accumulation-like operators, like C<+=>. Another PIR perk is that local variable names may be declared and used instead of register names. For that I just need to declare the variable using the C<.local> keyword with any of the four data types available on PIR: C<int>, C<string>, C<num> and C<pmc>: =begin PIR_FRAGMENT .local int size size = 5 =end PIR_FRAGMENT Note that all registers, both numbered and named, are consolidated by the Parrot register allocator, assigning these "virtual registers" to actual registers as needed. The register allocator even coalesces two virtual names onto the same physical register when it can prove that they have non-overlapping lifetimes, so there is no need to be stingy with register names. To see the actual registers used, use C<pbc_disassemble> on the C<*.pbc> output. You can generate a Parrot Byte Code (PBC) file as follows: ./parrot -o foo.pbc --output-pbc foo.pir Then, use C<pbc_disassemble> in order to disassemble it: ./pbc_disassemble foo.pbc =head2 Branching Another simplification of PASM are branches. Basically, when I want to test a condition and jump to another place in the code, I would write the following PASM code: =begin PASM le I1, I2, LESS_EQ # ... LESS_EQ: =end PASM Meaning, if C<$I1> is less or equal than C<$I2>, jump to label C<LESS_EQ>. In PIR I would write it in a more legible way: =begin PIR_FRAGMENT if $I1 <= $I2 goto LESS_EQ # ... LESS_EQ: =end PIR_FRAGMENT PIR includes the C<unless> keyword as well. =head2 Calling Functions Subroutines can easily be created using the C<.sub> keyword shown before. If you do not need parameters, it is just as simple as I show in the following code: =begin PIR .sub main :main hello() .end .sub hello print "Hello World\n" .end =end PIR Now, I want to make my C<hello> subroutine a little more useful, such that I can greet other people. For that I will use the C<.param> keyword to define the parameters C<hello> can handle: =begin PIR .sub main :main hello("leo") hello("chip") .end .sub hello .param string person print "Hello " print person print "\n" .end =end PIR If I need more parameters I just need to add more C<.param> lines. To return values from PIR subroutines I use the C<.return> keyword, followed by one or more arguments, just like this: =begin PIR .sub _ .return (10, 20, 30) .end =end PIR The calling subroutine can accept these values. If you want to retrieve only one value (or only the first value, in case multiple values are returned), write this: =begin PIR_FRAGMENT $I0 = compute_it($I8, $I9) =end PIR_FRAGMENT To accept multiple values from such a function, use a parenthesized results list: =begin PIR_FRAGMENT ($I1, $I2, $I3) = compute_it($I8, $I9) =end PIR_FRAGMENT =head2 Factorial Example Now, for a little more complicated example, let me show how I would code Factorial subroutine: =begin PIR .sub main :main $I1 = factorial(5) print $I1 print "\n" .end .sub factorial .param int i if i > 1 goto recur .return (1) recur: $I1 = i - 1 $I2 = factorial($I1) $I2 *= i .return ($I2) .end =end PIR This example also shows that PIR subroutines may be recursive just as in a high-level language. =head2 Named Arguments As some other languages as Python and Perl support named arguments, PIR supports them as well. As before, I need to use C<.param> for each named argument, but you need to specify a flag indicating the parameter is named: =begin PIR .sub func .param int a :named("foo") .end =end PIR The subroutine will receive an integer named "foo", and inside of the subroutine that integer will be known as "a". When calling the function, I need to pass the names of the arguments. For that there are two syntaxes: =begin PIR_FRAGMENT func( 10 :named("foo") ) # or func( "foo" => 10 ) =end PIR_FRAGMENT Note that with named arguments, you may rearrange the order of your parameters at will. =begin PIR .sub foo .param string a :named('name') .param int b :named('age') .param string c :named('gender') # ... .end =end PIR This subroutine may be called in any of the following ways: =begin PIR_FRAGMENT foo( "Fred", 35, "m" ) foo( "gender" => "m", "name" => "Fred", "age" => 35 ) foo( "age" => 35, "gender" => "m", "name" => "Fred" ) foo( "m" :named("gender"), 35 :named("age"), "name" => "Fred" ) =end PIR_FRAGMENT and any other permutation you can think of as long as you use the named argument syntax. Note that any positional parameters must be passed before the named parameters. So, the following is allowed: =begin PIR .sub main .param int a .param int b :named("age") # ... .end =end PIR Whereas the following is not: =begin PIR .sub main .param int a :named("name") .param int b # cannot declare positional parameter after a named parameter # ... .end =end PIR It's also possible to use named syntax when returning values from subroutines. Into the C<.return> command I'll use: =begin PIR_FRAGMENT .return ( "bar" => 20, "foo" => 10) =end PIR_FRAGMENT and when calling the function, I will do: =begin PIR_FRAGMENT ("foo" => $I0, "bar" => $I1) = func() =end PIR_FRAGMENT And C<$I0> will yield 10, and C<$I1> will yield 20, as expected. =head2 Concluding To conclude this first article on PIR and to let you test what you learned, let me show you how to do input on PASM (hence, also in PIR). There is a C<read> opcode to read from standard input. Just pass it a string register or variable where you wish the characters read to be placed and the number of characters you wish to read: =begin PIR_FRAGMENT_INVALID .loadlib 'io_ops' ... read $S1, 100 =end PIR_FRAGMENT_INVALID This line will read 100 characters (or until the end of the line) and put the read string into C<$S1>. In case you need a number, just assign the string to the correct register type: =begin PIR_FRAGMENT_INVALID .loadlib 'io_ops' read $S1, 100 ... $I1 = $S1 =end PIR_FRAGMENT_INVALID With the PIR syntax shown in this article you should be able to start writing simple programs. Next article we will look into available Polymorphic Containers (PMCs), and how they can be used. =head2 Author Alberto Simões =head2 Thanks =over 4 =item * Jonathan Scott Duff =back =cut