Author: bernhard
Date: Wed Feb 7 13:31:41 2007
New Revision: 16918
Modified:
trunk/languages/PIR/PROPOSALS
trunk/languages/PIR/docs/pirgrammar.html
trunk/languages/PIR/docs/pirgrammar.pod
Log:
[pirgrammar.pod]
* Fixing errors, misspellings and such
* more examples
* x.y.z version number
Courtesy of Klaas Jan Stol.
Modified: trunk/languages/PIR/PROPOSALS
==============================================================================
--- trunk/languages/PIR/PROPOSALS (original)
+++ trunk/languages/PIR/PROPOSALS Wed Feb 7 13:31:41 2007
@@ -43,17 +43,12 @@
consistent. An optional comma is kinda strange; either demand it,
or not.
-3. PIR vs PASM registers
-
- Since the new calling conventions/register allocation scheme (don't
- know when exactly), subs have as many registers as they need; no
- spilling is needed anymore (IIUC). Therefore, the difference between
- PIR and PASM registers is not necessary anymore.
-
- Proposal: stick to 1 category of registers, either PIR or PASM.
- My preference is to stick with PIR registers, to make a difference
- with .local's or .sym's (which may not start with a '$').
+3. :postcomp and :immediate
+
+ According to the documentation, both flags indicate the same
+ behaviour. This is both unnecessary and unclear to new users.
+ Proposal: deprecate one of these flags and remove it afterwards.
4. Macro parameter list.
@@ -104,6 +99,24 @@
which line is being parsed/assembled. It'd be more consistent with
respect to
other PIR directives ('.include' etc.). The current spelling seems
rather arbitrary.
+8. Parameter and argument flags
+
+ :named without a parameter does not seem to work - ever.
+
+ Proposal: require :named to take a parenthesized identifier.
+
+9. .lex + .local
+
+ When declaring a .lexical like:
+
+ .lex "a", b
+
+ one also needs the declaration:
+
+ .local pmc b
+
+ Proposal: remove the need for .local declaration. Parsing the .lex
declaration
+ expands to including the .local declaration.
NEW FEATURE PROPOSALS GO HERE:
Modified: trunk/languages/PIR/docs/pirgrammar.html
==============================================================================
--- trunk/languages/PIR/docs/pirgrammar.html (original)
+++ trunk/languages/PIR/docs/pirgrammar.html Wed Feb 7 13:31:41 2007
@@ -199,7 +199,7 @@
</p>
<hr />
<h1><a name="version">VERSION</a></h1>
-<p>0.1</p>
+<p>0.1.1</p>
<p>
</p>
<hr />
@@ -444,7 +444,7 @@
.param int argc :optional
.param int has_argc :optional
.param num nParam
- .param pmc argv :slurpy
+ .param pmc argv :slurpy
.param string sParam :named('foo')
.param $P0 :named('bar')
# body
@@ -549,7 +549,7 @@
$P0 = $P1</pre>
<li>
<pre>
- store_lex "$a", $P1</pre>
+ store_lex "i", $P1</pre>
</ul>
<p>Likewise, these two statements also have an identical effect:</p>
<ul>
@@ -558,7 +558,7 @@
$P1 = $P0</pre>
<li>
<pre>
- $P1 = find_lex "$a"</pre>
+ $P1 = find_lex "i"</pre>
</ul>
<p>Instead of a register, one can also specify a local variable, like so:</p>
<pre>
@@ -591,7 +591,7 @@
<pre>
.const int answer = 42</pre>
<p>defines an integer constant by name 'answer', giving it a value of 42.
-Note that the constant type and the value type should match, i.e. you cannot
+Note that the constant type and the value type should match, i.e. you cannot
assign a floating point number to an integer constant. The PIR parser will
check for this.</p>
<p>
@@ -728,7 +728,7 @@
| target keylist "=" simple_expr
| "global" string_constant "=" target
| result_var_list "=" short_sub_call</pre>
-<p>NOTE: the definition of assignment statements is <strong>not</strong>
complete yet.
+<p>NOTE: the definition of assignment statements is <strong>not</strong>
complete yet.
As languages/PIR evolves, this will be completed.</p>
<pre>
keylist:
@@ -873,7 +873,7 @@
.invocant $P0
.meth_call $P1
.pcc_end</pre>
-<p>Passing parameters and retrieving return values is done like this:</p>
+<p>Passing arguments and retrieving return values is done like this:</p>
<pre>
.pcc_begin
.arg 42
@@ -881,9 +881,32 @@
.local int res
.result res
.pcc_end</pre>
-<p>Parameters can take flags:</p>
+<p>Arguments can take flags as well. The following argument flags are
defined:</p>
+<ul>
+<li>
+<pre>
+ :flat</pre>
+<p>Flatten the (aggregate) argument. This argument can only be of type
<code>pmc</code>.</p>
+<li>
+<pre>
+ :named('x')</pre>
+<p>Pass the denoted argument into the named parameter that is denoted by 'x',
like so:</p>
+<pre>
+ .param <type> <identifier> :named('x')</pre>
+</ul>
+<pre>
+ .local pmc arr
+ arr = new .Array
+ arr = 2
+ arr[0] = 42
+ arr[1] = 43
+ .pcc_begin
+ .arg arr :flat
+ .arg $I0 :named('intArg')
+ .pcc_call foo
+ .pcc_end</pre>
<p>The Native Calling Interface (NCI) allows for calling C routines, in order
to talk to the world
-outside of Parrot. Its syntax is a slight variation:</p>
+outside of Parrot. Its syntax is a slight variation; it uses
<code>.nci_call</code> instead of <code>.pcc_call</code>.</p>
<pre>
.pcc_begin
.nci_call $P0
@@ -907,10 +930,20 @@
<p>Or a method call:</p>
<pre>
obj.'toString'() # call the method 'toString'
- obj.x() # call the method whose name is stored in C<x></pre>
+ obj.x() # call the method whose name is stored in 'x'.</pre>
<p>IMCC also allows the "->" instead of a dot, to make it
readable for C++ programmers:</p>
<pre>
obj->'toString'()</pre>
+<p>And of course, using the short version, passing arguments can be done as
well, including all flags that were defined
+for the long version. The same example from the 'long subroutine invocation'
is now shown in its short version:</p>
+<pre>
+ .local pmc arr
+ arr = new .Array
+ arr = 2
+ arr[0] = 42
+ arr[1] = 43
+ foo(arr :flat, $I0 :named('intArg'))</pre>
+<p>Please note that the short subroutine call does <strong>not</strong> allow
for <code>NCI</code> calls.</p>
<p>
</p>
<h2><a name="return_values_from_subroutines">Return values from
subroutines</a></h2>
@@ -932,11 +965,15 @@
<p>
</p>
<h3><a name="example_long_return_statement">Example long return
statement</a></h3>
+<p>Returning values from a subroutine is in fact similar to passing arguments
<em>to</em>
+a subroutine. Therefore, the same flags can be used:</p>
<pre>
.pcc_begin_return
- .return 42
+ .return 42 :named('answer')
.return $P0 :flat
.pcc_end_return</pre>
+<p>In this example, the value <code>42</code> is passed into the return value
that takes the named return value known by <code>'answer'</code>.
+The aggregate value in <code>$P0</code> is flattened, and each of its values
is passed as a return value.</p>
<p>
</p>
<h2><a name="short_return_statement">Short return statement</a></h2>
@@ -949,6 +986,9 @@
<pre>
<span class="operator">.</span><span
class="keyword">return</span><span class="operator">(</span><span
class="variable">myVar</span><span class="operator">,</span> <span
class="string">"hello"</span><span class="operator">,</span> <span
class="number">2.76</span><span class="operator">,</span> <span
class="number">3.14</span><span class="operator">);</span>
</pre>
+<p>Just as the return values in the <code>long return statement</code> could
take flags, the <code>short return statement</code> may as well:</p>
+<pre>
+ .return(42 :named('answer'), $P0 :flat)</pre>
<p>
</p>
<h2><a name="long_yield_statements">Long yield statements</a></h2>
@@ -960,6 +1000,9 @@
<p>
</p>
<h3><a name="example_long_yield_statement">Example long yield
statement</a></h3>
+<p>A <code>yield</code> statement works the same as a normal return value,
except that the point where the subroutine
+was left is stored somewhere, so that the subroutine can be resumed from that
point as soon as the subroutine
+is invoked again. Returning values is identical to <em>normal</em> return
statements.</p>
<pre>
.sub foo
.pcc_begin_yield
@@ -986,6 +1029,7 @@
<p>
</p>
<h3><a name="example_short_yield_statement">Example short yield
statement</a></h3>
+<p>Again, the short version is identical to the short version of the return
statement as well.</p>
<pre>
.yield("hello", 42)</pre>
<p>
@@ -1003,6 +1047,8 @@
<pre>
.local pmc results = foo()
.return(results)</pre>
+<p>The call to <code>foo</code> can be considered a normal function call with
respect to parameters: it can take the exact
+same format using argument flags.</p>
<p>
</p>
<h2><a name="symbol_namespaces">Symbol namespaces</a></h2>
@@ -1032,6 +1078,8 @@
42
43
42</pre>
+<p>Please note that it is <strong>not</strong> necessary to <em>pair</em>
these statements; it is acceptable to open a <code>.namespace</code> without
closing it.
+The scope of the <code>.namespace</code> is limited to the subroutine.</p>
<p>
</p>
<h2><a name="emit_blocks">Emit blocks</a></h2>
@@ -1045,6 +1093,15 @@
<h3><a name="example_emit_block">Example Emit block</a></h3>
<p>An emit block only allows PASM instructions,
not PIR instructions.</p>
+<pre>
+ .emit
+ set I0, 10
+ new P0, .Integer
+ ret
+ _foo:
+ print "This is PASM subroutine "foo"
+ ret
+ .eom</pre>
<p>
</p>
<h2><a name="macros">Macros</a></h2>
@@ -1248,6 +1305,18 @@
</p>
<hr />
<h1><a name="changes">CHANGES</a></h1>
+<p>0.1.1</p>
+<ul>
+<li>
+<p>Switch to x.y.z version number; many fixes will follow.</p>
+</li>
+<li>
+<p>Added more examples.</p>
+</li>
+<li>
+<p>Fixed some errors.</p>
+</li>
+</ul>
<p>0.1</p>
<ul>
<li>
Modified: trunk/languages/PIR/docs/pirgrammar.pod
==============================================================================
--- trunk/languages/PIR/docs/pirgrammar.pod (original)
+++ trunk/languages/PIR/docs/pirgrammar.pod Wed Feb 7 13:31:41 2007
@@ -19,7 +19,7 @@
=head1 VERSION
-0.1
+0.1.1
=head1 LEXICAL CONVENTIONS
@@ -306,7 +306,7 @@
.param int argc :optional
.param int has_argc :optional
.param num nParam
- .param pmc argv :slurpy
+ .param pmc argv :slurpy
.param string sParam :named('foo')
.param $P0 :named('bar')
# body
@@ -321,7 +321,7 @@
:slurpy
The parameter should be of type C<pmc> and acts like a container that
C<slurps> up all remaining arguments.
-Details can be found in PDD03 - Parrot Calling Conventions.
+Details can be found in PDD03 - Parrot Calling Conventions.
=item *
@@ -430,7 +430,7 @@
=item *
- store_lex "$a", $P1
+ store_lex "i", $P1
=back
@@ -444,7 +444,7 @@
=item *
- $P1 = find_lex "$a"
+ $P1 = find_lex "i"
=back
@@ -479,7 +479,7 @@
.const int answer = 42
defines an integer constant by name 'answer', giving it a value of 42.
-Note that the constant type and the value type should match, i.e. you cannot
+Note that the constant type and the value type should match, i.e. you cannot
assign a floating point number to an integer constant. The PIR parser will
check for this.
@@ -620,7 +620,7 @@
| "global" string_constant "=" target
| result_var_list "=" short_sub_call
-NOTE: the definition of assignment statements is B<not> complete yet.
+NOTE: the definition of assignment statements is B<not> complete yet.
As languages/PIR evolves, this will be completed.
keylist:
@@ -770,7 +770,7 @@
.meth_call $P1
.pcc_end
-Passing parameters and retrieving return values is done like this:
+Passing arguments and retrieving return values is done like this:
.pcc_begin
.arg 42
@@ -779,10 +779,40 @@
.result res
.pcc_end
-Parameters can take flags:
+Arguments can take flags as well. The following argument flags are defined:
+
+=over 4
+
+=item *
+
+ :flat
+
+Flatten the (aggregate) argument. This argument can only be of type C<pmc>.
+
+=item *
+
+ :named('x')
+
+Pass the denoted argument into the named parameter that is denoted by 'x',
like so:
+
+ .param <type> <identifier> :named('x')
+
+=back
+
+ .local pmc arr
+ arr = new .Array
+ arr = 2
+ arr[0] = 42
+ arr[1] = 43
+ .pcc_begin
+ .arg arr :flat
+ .arg $I0 :named('intArg')
+ .pcc_call foo
+ .pcc_end
+
The Native Calling Interface (NCI) allows for calling C routines, in order to
talk to the world
-outside of Parrot. Its syntax is a slight variation:
+outside of Parrot. Its syntax is a slight variation; it uses C<.nci_call>
instead of C<.pcc_call>.
.pcc_begin
.nci_call $P0
@@ -808,12 +838,23 @@
Or a method call:
obj.'toString'() # call the method 'toString'
- obj.x() # call the method whose name is stored in C<x>
+ obj.x() # call the method whose name is stored in 'x'.
IMCC also allows the "->" instead of a dot, to make it readable for C++
programmers:
obj->'toString'()
+And of course, using the short version, passing arguments can be done as well,
including all flags that were defined
+for the long version. The same example from the 'long subroutine invocation'
is now shown in its short version:
+
+ .local pmc arr
+ arr = new .Array
+ arr = 2
+ arr[0] = 42
+ arr[1] = 43
+ foo(arr :flat, $I0 :named('intArg'))
+
+Please note that the short subroutine call does B<not> allow for C<NCI> calls.
=head2 Return values from subroutines
@@ -835,11 +876,17 @@
=head3 Example long return statement
+Returning values from a subroutine is in fact similar to passing arguments
I<to>
+a subroutine. Therefore, the same flags can be used:
+
.pcc_begin_return
- .return 42
+ .return 42 :named('answer')
.return $P0 :flat
.pcc_end_return
+In this example, the value C<42> is passed into the return value that takes
the named return value known by C<'answer'>.
+The aggregate value in C<$P0> is flattened, and each of its values is passed
as a return value.
+
=head2 Short return statement
short_return_stat:
@@ -849,6 +896,9 @@
.return(myVar, "hello", 2.76, 3.14);
+Just as the return values in the C<long return statement> could take flags,
the C<short return statement> may as well:
+
+ .return(42 :named('answer'), $P0 :flat)
=head2 Long yield statements
@@ -859,6 +909,10 @@
=head3 Example long yield statement
+A C<yield> statement works the same as a normal return value, except that the
point where the subroutine
+was left is stored somewhere, so that the subroutine can be resumed from that
point as soon as the subroutine
+is invoked again. Returning values is identical to I<normal> return statements.
+
.sub foo
.pcc_begin_yield
.return 42
@@ -883,6 +937,8 @@
=head3 Example short yield statement
+Again, the short version is identical to the short version of the return
statement as well.
+
.yield("hello", 42)
=head2 Tail calls
@@ -899,6 +955,9 @@
.local pmc results = foo()
.return(results)
+The call to C<foo> can be considered a normal function call with respect to
parameters: it can take the exact
+same format using argument flags.
+
=head2 Symbol namespaces
open_namespace:
@@ -907,7 +966,6 @@
close_namespace:
".endnamespace" identifier
-
=head3 Example open/close namespaces
.sub main
@@ -928,6 +986,9 @@
43
42
+Please note that it is B<not> necessary to I<pair> these statements; it is
acceptable to open a C<.namespace> without closing it.
+The scope of the C<.namespace> is limited to the subroutine.
+
=head2 Emit blocks
emit:
@@ -940,6 +1001,14 @@
An emit block only allows PASM instructions,
not PIR instructions.
+ .emit
+ set I0, 10
+ new P0, .Integer
+ ret
+ _foo:
+ print "This is PASM subroutine "foo"
+ ret
+ .eom
=head2 Macros
@@ -1162,6 +1231,24 @@
=head1 CHANGES
+0.1.1
+
+=over 4
+
+=item *
+
+Switch to x.y.z version number; many fixes will follow.
+
+=item *
+
+Added more examples.
+
+=item *
+
+Fixed some errors.
+
+=back
+
0.1
=over 4
