[svn:parrot] r37611 - trunk/docs/user/pir
coke at svn.parrot.org
coke at svn.parrot.org
Fri Mar 20 18:23:37 UTC 2009
Author: coke
Date: Fri Mar 20 18:23:35 2009
New Revision: 37611
URL: https://trac.parrot.org/parrot/changeset/37611
Log:
[t/docs] test more sample PIR.
Modified:
trunk/docs/user/pir/exceptions.pod
trunk/docs/user/pir/intro.pod
trunk/docs/user/pir/objects.pod
trunk/docs/user/pir/pmcs.pod
Modified: trunk/docs/user/pir/exceptions.pod
==============================================================================
--- trunk/docs/user/pir/exceptions.pod Fri Mar 20 14:15:52 2009 (r37610)
+++ trunk/docs/user/pir/exceptions.pod Fri Mar 20 18:23:35 2009 (r37611)
@@ -88,13 +88,17 @@
Here's an example of a sub that catches only error exceptions and prints
an appropriate log message before exiting.
+=begin PIR
+
+ .include 'include/except_severity.pasm'
+
.sub 'dostuff'
.local pmc eh
eh = new 'ExceptionHandler'
set_addr eh, handler
eh.'min_severity'(.EXCEPT_ERROR)
push_eh eh
- ... # stuff that might throw an error
+ # ... stuff that might throw an error
pop_eh
.return (1)
handler:
@@ -106,3 +110,7 @@
say ex
exit 1
.end
+
+=end PIR
+
+=cut
Modified: trunk/docs/user/pir/intro.pod
==============================================================================
--- trunk/docs/user/pir/intro.pod Fri Mar 20 14:15:52 2009 (r37610)
+++ trunk/docs/user/pir/intro.pod Fri Mar 20 18:23:35 2009 (r37611)
@@ -81,10 +81,14 @@
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:
@@ -177,6 +181,8 @@
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
@@ -185,10 +191,14 @@
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")
@@ -201,6 +211,9 @@
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,
@@ -224,6 +237,8 @@
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
@@ -241,6 +256,8 @@
.return ($I2)
.end
+=cut
+
This example also shows that PIR subroutines may be recursive just as in
a high-level language.
@@ -267,6 +284,8 @@
Note that with named arguments, you may rearrange the order of your
parameters at will.
+=begin PIR
+
.sub foo
.param string "name" => a
.param int "age" => b
@@ -274,6 +293,8 @@
# ...
.end
+=end PIR
+
This subroutine may be called in any of the following ways:
foo( "Fred", 35, "m" )
@@ -285,12 +306,16 @@
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:
.sub main
Modified: trunk/docs/user/pir/objects.pod
==============================================================================
--- trunk/docs/user/pir/objects.pod Fri Mar 20 14:15:52 2009 (r37610)
+++ trunk/docs/user/pir/objects.pod Fri Mar 20 18:23:35 2009 (r37611)
@@ -37,6 +37,8 @@
=head3 Example 1:
+=begin PIR
+
.namespace [ "Person" ]
.sub run
@@ -49,6 +51,8 @@
say "Running process #53"
.end
+=end PIR
+
As you might guess, the C<.namespace> directive tells Parrot
what namespace to group subroutines under. A namespace ends when
another C<.namespace> directive changes the namespace or when
@@ -76,12 +80,16 @@
=head3 Example 2: A classic Dog
+=begin PIR
+
.sub _ :main
$P0 = newclass 'Dog'
.local pmc spot
spot = new 'Dog'
.end
+=end PIR
+
You may notice that I didn't use the return value of
C<newclass>. That's only because this is a simple example. :-)
I'll talk about what to do with the return value of C<newclass>
@@ -101,6 +109,8 @@
=head3 Example 3: Barnyard animals
+=begin PIR
+
.namespace [ "Cow" ]
.sub speak :method
@@ -137,6 +147,8 @@
porky.'speak'()
.end
+=end PIR
+
It's important to note that even though I've declared the
namespaces and put subroutines in them, this does not
automatically create classes. The C<newclass> declarations
@@ -161,6 +173,8 @@
=head3 Example 4: variable methods
+=begin PIR
+
.namespace [ 'Foo' ]
.sub foo :method
@@ -185,6 +199,8 @@
f.m()
.end
+=end PIR
+
=head2 But where do I store my stuff?
So far I've talked about namespaces and creating classes
@@ -210,6 +226,8 @@
=head3 Example 5: Naming my animals
+=begin PIR
+
.namespace [ "Dog" ]
.sub name :method
@@ -240,6 +258,8 @@
print "!\n"
.end
+=end PIR
+
Whew! There's a lot of new stuff in this code. I'll take them
starting from the top of the program and working towards the
bottom.
@@ -336,6 +356,8 @@
=head3 Example 6: Full barnyard listing
+=begin PIR
+
.namespace [ "Animal" ]
.sub setname :method
@@ -401,4 +423,6 @@
pig.'speak'()
.end
+=end PIR
+
=cut
Modified: trunk/docs/user/pir/pmcs.pod
==============================================================================
--- trunk/docs/user/pir/pmcs.pod Fri Mar 20 14:15:52 2009 (r37610)
+++ trunk/docs/user/pir/pmcs.pod Fri Mar 20 18:23:35 2009 (r37611)
@@ -84,6 +84,8 @@
=head3 Example 2: reading command line arguments, take 1
+=begin PIR
+
.sub _ :main
.param pmc args
loop:
@@ -95,6 +97,8 @@
end_loop:
.end
+=end PIR
+
The C<.param> directive tells parrot that I want this
subroutine to accept a single parameter and that parameter
is some sort of PMC that I've named C<args>. Since this is
@@ -116,6 +120,8 @@
=head3 Example 3: reading command line arguments, take 2
+=begin PIR
+
.sub _ :main
.param pmc args
.local int argc
@@ -133,6 +139,8 @@
end_loop:
.end
+=end PIR
+
Line 4 shows something interesting about aggregates. Similar
to perl, when you assign an aggregate to an integer thing
(whether it be a register or local variable, but as was explained
@@ -163,6 +171,8 @@
=head3 Example 4: Typing the C<args> PMC
+=begin PIR
+
.sub _ :main
.param pmc args
$S0 = typeof args
@@ -170,6 +180,8 @@
print "\n"
.end
+=end PIR
+
When you run this program it should output
"ResizableStringArray". If you assign the result of the
C<typeof> opcode to a string thing, you get the name of the
@@ -208,6 +220,8 @@
=head3 Example 5: output environment
+=begin PIR
+
.sub _ :main
.local pmc env, iter
.local string key, value
@@ -226,6 +240,8 @@
iterend:
.end
+=end PIR
+
Lines 3 and 4 create my new PMCs. Line 3 creates a new
C<Env> PMC which at the moment of its existence contains a
hash of all of the environment variables currently in the
@@ -252,6 +268,8 @@
=head3 Example 6: reading command line arguments, take 3
+=begin PIR
+
.sub _ :main
.param pmc args
.local pmc cmdline
@@ -265,6 +283,8 @@
end_loop:
.end
+=end PIR
+
Notice how this code approaches the simplicity of the
original that destructively iterated the C<args> PMC. Using
indexes can quickly become complicated by comparison.
@@ -287,6 +307,8 @@
=head3 Example 7: Output random numbers
+=begin PIR
+
.sub _ :main
$P0 = new 'Random'
$N0 = $P0
@@ -297,16 +319,24 @@
print "\n"
.end
+=end PIR
+
=head3 Example 8: Triggering an exception
+=begin PIR
+
.sub _ :main
$P0 = new 'Exception'
$P0 = "The sky is falling!"
throw $P0
.end
+=end PIR
+
=head3 Example 9: Setting a timer
+=begin PIR
+
.include "timer.pasm" # for the timer constants
.sub expired
@@ -332,6 +362,7 @@
goto loop
.end
+=end PIR
=head2 Author
More information about the parrot-commits
mailing list