Author: bernhard Date: Tue Feb 6 12:40:58 2007 New Revision: 16912 Modified: trunk/languages/PIR/docs/pirgrammar.html trunk/languages/PIR/docs/pirgrammar.pod
Log: Revert r16911 and apply more recent patch from Klaas Jan Stol. Changes: * added examples * it now has a version no.: 0.1 * added descriptions of all flags * updated grammar (added :postcomp) Courtesy of Klaas Jan Stol. Modified: trunk/languages/PIR/docs/pirgrammar.html ============================================================================== --- trunk/languages/PIR/docs/pirgrammar.html (original) +++ trunk/languages/PIR/docs/pirgrammar.html Tue Feb 6 12:40:58 2007 @@ -4,7 +4,7 @@ <head> <title>PIR.pod - The Grammar of languages/PIR</title> <meta http-equiv="content-type" content="text/html; charset=utf-8" /> -<link rev="made" href="mailto:[EMAIL PROTECTED]" /> +<link rev="made" href="mailto:"; /> </head> <body style="background-color: white"> @@ -171,6 +171,8 @@ <li><a href="#author">AUTHOR</a></li> <li><a href="#known_issues_and_bugs">KNOWN ISSUES AND BUGS</a></li> + <li><a href="#references">REFERENCES</a></li> + <li><a href="#changes">CHANGES</a></li> </ul> <!-- INDEX END --> @@ -191,14 +193,13 @@ <hr /> <h1><a name="status">STATUS</a></h1> <p>For a bugs and issues, see the section KNOWN ISSUES AND BUGS.</p> -<p>The grammar includes some constructs that *are* in the IMCC parser, -but are not implemented. An example of this is the ``.global'' directive.</p> +<p>The grammar includes some constructs that <strong>are</strong> in the IMCC parser, +but are not implemented. An example of this is the <code>.global</code> directive.</p> <p> </p> <hr /> <h1><a name="version">VERSION</a></h1> -<p>Version: Sunday Feb. 4th 2007. -(not a version number yet, as many improvements are to be expected at this point).</p> +<p>0.1</p> <p> </p> <hr /> @@ -226,44 +227,44 @@ <p> </p> <h2><a name="registers">Registers</a></h2> -<p>PIR has two types of registers: real registers and virtual or temporary registers. +<p>PIR has two types of registers: real registers and symbolic or temporary registers. Real registers are actual registers in the Parrot VM, and are written like:</p> <pre> [S|N|I|P]n, where n is a number between 0 to, but not including, 100.</pre> -<p>Virtual, or temporary registers are written like:</p> +<p>Symbolic, or temporary registers are written like:</p> <pre> $[S|N|I|P]n, where n is a positive integer.</pre> -<p>Virtual registers can be thought of local variable identifiers that don't need a declaration. +<p>Symbolic registers can be thought of local variable identifiers that don't need a declaration. This prevents you from writing <code>.local</code> directives if you're in a hurry. Of course, it would make the code more self-documenting if <code>.local</code>s would be used.</p> <p> </p> <h2><a name="constants">Constants</a></h2> <p>An integer constant is a string of one or more digits. -Examples: 0, 42.</p> +Examples: <code>0</code>, <code>42</code>.</p> <p>A floatin-point constant is a string of one or more digits, followed by a dot -and one or more digits. Examples: 1.1, 42.567.</p> +and one or more digits. Examples: <code>1.1</code>, <code>42.567</code></p> <p>A string constant is a single or double quoted series of characters. -Examples: 'hello world', ``Parrot''.</p> +Examples: <code>'hello world'</code>, <code>"Parrot"</code>.</p> <p>TODO: PMC constants.</p> <p> </p> <h2><a name="identifiers">Identifiers</a></h2> <p>An identifier starts with a character from [_a-zA-Z], followed by -a character from [_a-zA-Z0-9].</p> -<p>Examples: x, x1, _foo.</p> +zero or more characters from [_a-zA-Z0-9].</p> +<p>Examples: <code>x</code>, <code>x1</code>, <code>_foo</code></p> <p> </p> <h2><a name="labels">Labels</a></h2> <p>A label is an identifier with a colon attached to it.</p> -<p>Examples: LABEL:</p> +<p>Examples: <code>LABEL:</code></p> <p> </p> <h2><a name="macro_identifiers">Macro identifiers</a></h2> <p>A macro identifier is an identifier prefixed with an dot. A macro identifier is used when <em>expanding</em> the macro (on usage), not in the macro definition.</p> -<p>Examples: .Macro</p> +<p>Examples: <code>.myMacro</code></p> <p> </p> <hr /> @@ -274,7 +275,7 @@ <p>A PIR program consists of one or more compilation units. A compilation unit is a global, sub, constant or macro definition, or a pragma or emit block. PIR is a line oriented language, which means that each statement ends in a -newline (indicated as ``nl''). Moreover, compilation units are always separated +newline (indicated as "nl"). Moreover, compilation units are always separated by a newline. Each of the different compilation units are discussed in this document.</p> <pre> @@ -305,6 +306,7 @@ ":load" | ":init" | ":immediate" + | ":postcomp" | ":main" | ":anon" | ":lex" @@ -366,20 +368,29 @@ <p>The body of the subroutine can contain PIR instructions. The subroutine can be given one or more flags, indicating the sub should behave in a special way. Below is a list of these flags and their meaning:</p> -<p>TODO: complete this</p> <ul> <li> <pre> :load</pre> -<p>Indicates the sub being defined</p> +<p>Run this subroutine during the <strong>load_library</strong> opcode. +<strong>:load</strong> is ignored, if another subroutine in that file is marked with +<strong>:main</strong>. If multiple subs have the <strong>:load</strong> pragma, the subs are +run in source code order.</p> <li> <pre> :init</pre> -<p>Indicates the sub being defined</p> +<p>Run the subroutine when the program is run directly (that is, not loaded as a +module). This is different from <strong>:load</strong>, which runs a subroutine when a +library is being loaded. To get both behaviours, use <strong>:init :load</strong>.</p> +<li> +<pre> + :postcomp</pre> +<p>Same as <code>:immediate</code>.</p> <li> <pre> :immediate</pre> -<p>Indicates the sub being defined</p> +<p>This subroutine is executed immediately after being compiled. (Analagous to +<code>BEGIN</code> in perl5.)</p> <li> <pre> :main</pre> @@ -388,15 +399,16 @@ <pre> :method</pre> <p>Indicates the sub being defined is an instance method. The method belongs to the class whose namespace is -currently active. (so, to define a method for a class 'Foo', the 'Foo' namespace should be currently active).</p> +currently active. (so, to define a method for a class 'Foo', the 'Foo' namespace should be currently active). +In the method body, the object PMC can be referred to with <code>self</code>.</p> <li> <pre> :vtable or vtable('x')</pre> <p>Indicates the sub being defined replaces a vtable entry. This flag can only be used when defining a method.</p> <li> <pre> - :multi(int, string, num, _, pmc)</pre> -<p>Indicates the sub being defined</p> + :multi(type [, type]*)</pre> +<p>Engage in multiple dispatch with the listed types.</p> <li> <pre> :outer('bar')</pre> @@ -404,17 +416,19 @@ <li> <pre> :anon</pre> -<p>Indicates the sub being defined is anonymous; no symbol entry is stored into the global symbol table</p> +<p>Do not install this subroutine in the namespace. Allows the subroutine +name to be reused.</p> <li> <pre> :lex</pre> <p>Indicates the sub being defined needs to store lexical variables. This flag is not necessary if any lexical -declarations are done (see below), the PIR compiler will figure this out by itself.</p> +declarations are done (see below), the PIR compiler will figure this out by itself. The <code>:lex</code> attribute +is necessary to tell Parrot the subroutine will store or find lexicals.</p> <li> <pre> :wrap('bar')</pre> -<p>This flag is not (yet?) implemented in IMCC. It would indicate that this sub is <em>wrapping</em> the sub ``bar''. That means -that when ``bar'' is invoked, this sub is called <em>before</em> and <em>after</em>. It is undecided yet whether this flag will +<p>This flag is not (yet?) implemented in IMCC. It would indicate that this sub is <em>wrapping</em> the sub "bar". That means +that when "bar" is invoked, this sub is called <em>before</em> and <em>after</em>. It is undecided yet whether this flag will be implemented. If so, its syntax may change.</p> </ul> <p>The sub flags are listed after the sub name. They may be separated by a comma, but this is @@ -427,21 +441,25 @@ <p>Parameter definitions have the following syntax:</p> <pre> .sub main - .param int argc - .param pmc argv + .param int argc :optional + .param int has_argc :optional .param num nParam - .param string sParam - .param $P0 + .param pmc argv :slurpy + .param string sParam :named('foo') + .param $P0 :named('bar') # body .end</pre> -<p>Parameter definitions may take flags as well. These flags are listed here:</p> +<p>As shown, parameter definitions may take flags as well. These flags are listed here:</p> <ul> <li> <pre> :slurpy</pre> +<p>The parameter should be of type <code>pmc</code> and acts like a container that <code>slurps</code> up all remaining arguments. +Details can be found in PDD03 - Parrot Calling Conventions.</p> <li> <pre> :named('x')</pre> +<p>The parameter is known in the called sub by name <code>'x'</code>.</p> <li> <pre> :optional</pre> @@ -504,7 +522,10 @@ .local num a, b, c .sym string s1, s2 .sym pmc obj</pre> -<p>The <code>:unique_reg</code> flag indicates ... TODO.</p> +<p>The optional <code>:unique_reg</code> modifier will force the register allocator to associate the identifier +with a unique register for the duration of the compilation unit.</p> +<pre> + .local int j :unique_reg</pre> <p> </p> <h2><a name="lexical_declarations">Lexical declarations</a></h2> @@ -517,8 +538,29 @@ <p>The declaration</p> <pre> .lex 'i', $P0</pre> -<p>indicates that the value in $P0 is stored as a lexical variable, named by 'i'. Instead of a register, -one can also specify a local variable, like so:</p> +<p>indicates that the value in $P0 is stored as a lexical variable, named by 'i'. +Once the above lexical declaration is written, and given the following statement:</p> +<pre> + $P1 = new .Integer</pre> +<p>then the following two statements have an identical effect:</p> +<ul> +<li> +<pre> + $P0 = $P1</pre> +<li> +<pre> + store_lex "$a", $P1</pre> +</ul> +<p>Likewise, these two statements also have an identical effect:</p> +<ul> +<li> +<pre> + $P1 = $P0</pre> +<li> +<pre> + $P1 = find_lex "$a"</pre> +</ul> +<p>Instead of a register, one can also specify a local variable, like so:</p> <pre> .local pmc p .lex 'i', p</pre> @@ -548,7 +590,10 @@ <h3><a name="example_constant_definitions">Example constant definitions</a></h3> <pre> .const int answer = 42</pre> -<p>defines an integer constant by name 'answer', giving it a value of 42.</p> +<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 +assign a floating point number to an integer constant. The PIR parser will +check for this.</p> <p> </p> <h2><a name="conditional_statements">Conditional statements</a></h2> @@ -665,7 +710,7 @@ ~obj !isSomething</pre> <p>Arithmetic operators are only allowed on floating-point numbers and integer values (or variables of that type). -Likewise, string concatenation (``.'') is only allowed on strings. These checks are <strong>not</strong> done by the PIR parser.</p> +Likewise, string concatenation (".") is only allowed on strings. These checks are <strong>not</strong> done by the PIR parser.</p> <p> </p> <h2><a name="assignments">Assignments</a></h2> @@ -678,11 +723,13 @@ | target "=" "new" keylist | target "=" "find_type" [ string_constant | string_reg | id ] | target "=" heredoc - | target "=" "global" <string_constant + | target "=" "global" string_constant | target assign_op simple_expr | 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. +As languages/PIR evolves, this will be completed.</p> <pre> keylist: "[" keys "]"</pre> @@ -690,18 +737,30 @@ keys: key [ sep key ]*</pre> <pre> - sep: - "," | ";"</pre> + <span class="variable">sep</span><span class="operator">:</span> + <span class="string">","</span> <span class="operator">|</span> <span class="string">";"</span> +</pre> <pre> key: simple_expr | simple_expr ".." | ".." simple_expr | simple_expr ".." simple_expr</pre> +<pre> + result_var_list: + "(" result_vars ")"</pre> +<pre> + result_vars: + result_var [ "," result_var ]*</pre> +<pre> + result_var: + target get_flags?</pre> <p> </p> <h3><a name="examples_assignment_statements">Examples assignment statements</a></h3> <pre> + $I1 = 1 + 2 + $I1 += 1 $P0 = foo() $I0 = $P0[1] $I0 = $P0[12.34] @@ -849,22 +908,13 @@ <pre> obj.'toString'() # call the method 'toString' obj.x() # call the method whose name is stored in C<x></pre> -<p>IMCC also allows the ``->'' instead of a dot, to make it readable for C++ programmers:</p> +<p>IMCC also allows the "->" instead of a dot, to make it readable for C++ programmers:</p> <pre> obj->'toString'()</pre> <p> </p> <h2><a name="return_values_from_subroutines">Return values from subroutines</a></h2> <pre> - result_var_list: - "(" result_vars ")"</pre> -<pre> - result_vars: - result_var [ "," result_var ]*</pre> -<pre> - result_var: - target get_flags?</pre> -<pre> return_stat: long_return_stat | short_return_stat @@ -897,7 +947,8 @@ </p> <h3><a name="example_short_return_statement">Example short return statement</a></h3> <pre> - .return(myVar, "hello", 2.76, 3.14);</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> </p> <h2><a name="long_yield_statements">Long yield statements</a></h2> @@ -915,7 +966,8 @@ .return 42 .pcc_end_yield</pre> <pre> - # and later in the sub, one could return another value:</pre> + <span class="comment"># and later in the sub, one could return another value:</span> +</pre> <pre> .pcc_begin_yield .return 43 @@ -1015,7 +1067,7 @@ <h3><a name="example_macros">Example Macros</a></h3> <p>NOTE: the macro definition is not complete, and untested. This should be fixed. For now, all characters up to but not -including ``.endm'' are 'matched'.</p> +including ".endm" are 'matched'.</p> <p> </p> <h2><a name="pir_pragmas">PIR Pragmas</a></h2> @@ -1047,8 +1099,9 @@ hll_mapping: ".HLL_map" int_constant "," int_constant</pre> <pre> - namespace_id: - string_constant [ ";" string_constant ]*</pre> + <span class="variable">namespace_id</span><span class="operator">:</span> + <span class="variable">string_constant</span> <span class="operator">[</span> <span class="string">";"</span> <span class="variable">string_constant</span> <span class="operator">]</span><span class="operator">*</span> +</pre> <pre> source_info: ".line" int_constant [ "," string_constant ]?</pre> @@ -1060,7 +1113,7 @@ <h3><a name="examples_pragmas">Examples pragmas</a></h3> <pre> .include "myLib.pir"</pre> -<p>includes the source from the file ``myLib.pir'' at the point of this directive.</p> +<p>includes the source from the file "myLib.pir" at the point of this directive.</p> <pre> .pragma n_operators 1</pre> <p>makes Parrot automatically create new PMCs when using arithmetic operators, like:</p> @@ -1077,9 +1130,10 @@ <p>NOTE: currently, the line directive is implemented in IMCC as #line. See the PROPOSALS document for more information on this.</p> <pre> - .namespace ['Foo'] # namespace Foo - .namespace ['Object';'Foo'] # nested namespace - + <span class="operator">.</span><span class="variable">namespace</span> <span class="operator">[</span><span class="string">'Foo'</span><span class="operator">]</span> <span class="comment"># namespace Foo</span> + <span class="operator">.</span><span class="variable">namespace</span> <span class="operator">[</span><span class="string">'Object'</span><span class="operator">;</span><span class="string">'Foo'</span><span class="operator">]</span> <span class="comment"># nested namespace</span> +</pre> +<pre> .namespace # no [ id ] means the root namespace is activated</pre> <p>opens the namespace 'Foo'. When doing Object Oriented programming, this would indicate that sub or method definitions belong to the class 'Foo'. Of course, you can also define @@ -1087,26 +1141,22 @@ <p>Please note that this <code>.namespace</code> directive is <em>different</em> from the <code>.namespace</code> directive that is used within subroutines.</p> <pre> - .HLL "Lua", "lua_group" - -is an example of specifying the High Level Language (HLL) for which the PIR is being generated. -It is a shortcut for setting the namespace to 'Lua', and for loading the PMCs in the lua_group library.</pre> -<pre> - .HLL_map .Integer, .LuaNumber - -is a way of telling Parrot, that whenever an Integer is created somewhere in the system (C code), instead -a LuaNumber object is created.</pre> -<pre> - .loadlib "myLib" - -is a shortcut for telling Parrot that the library "myLib" should be loaded when running the program. In fact, -it is a shortcut for:</pre> + .HLL "Lua", "lua_group"</pre> +<p>is an example of specifying the High Level Language (HLL) for which the PIR is being generated. +It is a shortcut for setting the namespace to 'Lua', and for loading the PMCs in the lua_group library.</p> +<pre> + .HLL_map .Integer, .LuaNumber</pre> +<p>is a way of telling Parrot, that whenever an Integer is created somewhere in the system (C code), instead +a LuaNumber object is created.</p> +<pre> + .loadlib "myLib"</pre> +<p>is a shortcut for telling Parrot that the library "myLib" should be loaded when running the program. In fact, +it is a shortcut for:</p> <pre> .sub _load :load :anon - loadlib "myLib" - .end - -TODO: check flags and syntax for this.</pre> + loadlib "myLib" + .end</pre> +<p>TODO: check flags and syntax for this.</p> <p> </p> <h2><a name="tokens__types_and_targets">Tokens, types and targets</a></h2> @@ -1140,7 +1190,6 @@ <p>but if desirable, the character set can be specified:</p> <pre> unicode:"Hello world"</pre> -<p>TODO: is it ``unicode''? or is it UTF8 or something?</p> <p>IMCC currently allows identifiers to be used as types. During the parse, the identifier is checked whether it is a defined class. The built-in types int, num, pmc and string are always available.</p> @@ -1165,18 +1214,46 @@ </li> <li> <p>The rule 'type' does currently not include custom types (user defined). -Probably it needs an alternative ``identifier''. Not sure yet at this point.</p> +Probably it needs an alternative "identifier". Not sure yet at this point.</p> </li> <li> <p>Clean up grammar, remove never-used features.</p> </li> <li> <p>Test. A lot.</p> -<p>Bugs or improvements may be sent to the author, and of course greatly +<p>Bugs or improvements may be sent to the author, and are of course greatly appreciated. Moreover, if you find any missing constructs that are in IMCC, indications of these would be appreciated as well.</p> </li> </ul> +<p> +</p> +<hr /> +<h1><a name="references">REFERENCES</a></h1> +<ul> +<li> +<p>languages/PIR/lib/pir.pg - The actual PIR grammar implementation</p> +</li> +<li> +<p>PDD03 - Parrot Calling Conventions</p> +</li> +<li> +<p>PDD20 - Lexically scoped variables in Parrot</p> +</li> +<li> +<p>docs/imcc/calling_conventions.pod - definition of sub flags (:init etc)</p> +</li> +</ul> +<p> +</p> +<hr /> +<h1><a name="changes">CHANGES</a></h1> +<p>0.1</p> +<ul> +<li> +<p>Initial version having a version number.</p> +</li> +</ul> </body> Modified: trunk/languages/PIR/docs/pirgrammar.pod ============================================================================== --- trunk/languages/PIR/docs/pirgrammar.pod (original) +++ trunk/languages/PIR/docs/pirgrammar.pod Tue Feb 6 12:40:58 2007 @@ -13,15 +13,13 @@ For a bugs and issues, see the section KNOWN ISSUES AND BUGS. -The grammar includes some constructs that *are* in the IMCC parser, -but are not implemented. An example of this is the ".global" directive. +The grammar includes some constructs that B<are> in the IMCC parser, +but are not implemented. An example of this is the C<.global> directive. =head1 VERSION -Version: Sunday Feb. 4th 2007. -(not a version number yet, as many improvements are to be expected at this point). - +0.1 =head1 LEXICAL CONVENTIONS @@ -49,45 +47,45 @@ =head2 Registers -PIR has two types of registers: real registers and virtual or temporary registers. +PIR has two types of registers: real registers and symbolic or temporary registers. Real registers are actual registers in the Parrot VM, and are written like: [S|N|I|P]n, where n is a number between 0 to, but not including, 100. -Virtual, or temporary registers are written like: +Symbolic, or temporary registers are written like: $[S|N|I|P]n, where n is a positive integer. -Virtual registers can be thought of local variable identifiers that don't need a declaration. +Symbolic registers can be thought of local variable identifiers that don't need a declaration. This prevents you from writing C<.local> directives if you're in a hurry. Of course, it would make the code more self-documenting if C<.local>s would be used. =head2 Constants An integer constant is a string of one or more digits. -Examples: 0, 42. +Examples: C<0>, C<42>. A floatin-point constant is a string of one or more digits, followed by a dot -and one or more digits. Examples: 1.1, 42.567. +and one or more digits. Examples: C<1.1>, C<42.567> A string constant is a single or double quoted series of characters. -Examples: 'hello world', "Parrot". +Examples: C<'hello world'>, C<"Parrot">. TODO: PMC constants. =head2 Identifiers An identifier starts with a character from [_a-zA-Z], followed by -a character from [_a-zA-Z0-9]. +zero or more characters from [_a-zA-Z0-9]. -Examples: x, x1, _foo. +Examples: C<x>, C<x1>, C<_foo> =head2 Labels A label is an identifier with a colon attached to it. -Examples: LABEL: +Examples: C<LABEL:> =head2 Macro identifiers @@ -96,7 +94,7 @@ identifier is used when I<expanding> the macro (on usage), not in the macro definition. -Examples: .Macro +Examples: C<.myMacro> @@ -140,6 +138,7 @@ ":load" | ":init" | ":immediate" + | ":postcomp" | ":main" | ":anon" | ":lex" @@ -203,27 +202,37 @@ one or more flags, indicating the sub should behave in a special way. Below is a list of these flags and their meaning: -TODO: complete this - =over 4 =item * :load -Indicates the sub being defined +Run this subroutine during the B<load_library> opcode. +B<:load> is ignored, if another subroutine in that file is marked with +B<:main>. If multiple subs have the B<:load> pragma, the subs are +run in source code order. =item * :init -Indicates the sub being defined +Run the subroutine when the program is run directly (that is, not loaded as a +module). This is different from B<:load>, which runs a subroutine when a +library is being loaded. To get both behaviours, use B<:init :load>. + +=item * + + :postcomp + +Same as C<:immediate>. =item * :immediate -Indicates the sub being defined +This subroutine is executed immediately after being compiled. (Analagous to +C<BEGIN> in perl5.) =item * @@ -237,6 +246,7 @@ Indicates the sub being defined is an instance method. The method belongs to the class whose namespace is currently active. (so, to define a method for a class 'Foo', the 'Foo' namespace should be currently active). +In the method body, the object PMC can be referred to with C<self>. =item * @@ -246,9 +256,9 @@ =item * - :multi(int, string, num, _, pmc) + :multi(type [, type]*) -Indicates the sub being defined +Engage in multiple dispatch with the listed types. =item * @@ -260,14 +270,17 @@ :anon -Indicates the sub being defined is anonymous; no symbol entry is stored into the global symbol table +Do not install this subroutine in the namespace. Allows the subroutine +name to be reused. =item * :lex Indicates the sub being defined needs to store lexical variables. This flag is not necessary if any lexical -declarations are done (see below), the PIR compiler will figure this out by itself. +declarations are done (see below), the PIR compiler will figure this out by itself. The C<:lex> attribute +is necessary to tell Parrot the subroutine will store or find lexicals. + =item * @@ -290,15 +303,16 @@ Parameter definitions have the following syntax: .sub main - .param int argc - .param pmc argv + .param int argc :optional + .param int has_argc :optional .param num nParam - .param string sParam - .param $P0 + .param pmc argv :slurpy + .param string sParam :named('foo') + .param $P0 :named('bar') # body .end -Parameter definitions may take flags as well. These flags are listed here: +As shown, parameter definitions may take flags as well. These flags are listed here: =over 4 @@ -306,10 +320,15 @@ :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. + =item * :named('x') +The parameter is known in the called sub by name C<'x'>. + =item * :optional @@ -380,7 +399,10 @@ .sym string s1, s2 .sym pmc obj -The C<:unique_reg> flag indicates ... TODO. +The optional C<:unique_reg> modifier will force the register allocator to associate the identifier +with a unique register for the duration of the compilation unit. + + .local int j :unique_reg =head2 Lexical declarations @@ -393,8 +415,40 @@ .lex 'i', $P0 -indicates that the value in $P0 is stored as a lexical variable, named by 'i'. Instead of a register, -one can also specify a local variable, like so: +indicates that the value in $P0 is stored as a lexical variable, named by 'i'. +Once the above lexical declaration is written, and given the following statement: + + $P1 = new .Integer + +then the following two statements have an identical effect: + +=over 4 + +=item * + + $P0 = $P1 + +=item * + + store_lex "$a", $P1 + +=back + +Likewise, these two statements also have an identical effect: + +=over 4 + +=item * + + $P1 = $P0 + +=item * + + $P1 = find_lex "$a" + +=back + +Instead of a register, one can also specify a local variable, like so: .local pmc p .lex 'i', p @@ -425,6 +479,9 @@ .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 +assign a floating point number to an integer constant. The PIR parser will +check for this. =head2 Conditional statements @@ -557,12 +614,15 @@ | target "=" "new" keylist | target "=" "find_type" [ string_constant | string_reg | id ] | target "=" heredoc - | target "=" "global" <string_constant + | target "=" "global" string_constant | target assign_op simple_expr | target keylist "=" simple_expr | "global" string_constant "=" target | result_var_list "=" short_sub_call +NOTE: the definition of assignment statements is B<not> complete yet. +As languages/PIR evolves, this will be completed. + keylist: "[" keys "]" @@ -578,9 +638,21 @@ | ".." simple_expr | simple_expr ".." simple_expr + result_var_list: + "(" result_vars ")" + + result_vars: + result_var [ "," result_var ]* + + result_var: + target get_flags? + + =head3 Examples assignment statements + $I1 = 1 + 2 + $I1 += 1 $P0 = foo() $I0 = $P0[1] $I0 = $P0[12.34] @@ -745,14 +817,6 @@ =head2 Return values from subroutines - result_var_list: - "(" result_vars ")" - - result_vars: - result_var [ "," result_var ]* - - result_var: - target get_flags? return_stat: long_return_stat @@ -965,7 +1029,7 @@ .namespace ['Foo'] # namespace Foo .namespace ['Object';'Foo'] # nested namespace - + .namespace # no [ id ] means the root namespace is activated opens the namespace 'Foo'. When doing Object Oriented programming, this would indicate @@ -976,24 +1040,24 @@ that is used within subroutines. .HLL "Lua", "lua_group" - + is an example of specifying the High Level Language (HLL) for which the PIR is being generated. It is a shortcut for setting the namespace to 'Lua', and for loading the PMCs in the lua_group library. .HLL_map .Integer, .LuaNumber - + is a way of telling Parrot, that whenever an Integer is created somewhere in the system (C code), instead a LuaNumber object is created. .loadlib "myLib" - + is a shortcut for telling Parrot that the library "myLib" should be loaded when running the program. In fact, it is a shortcut for: .sub _load :load :anon - loadlib "myLib" + loadlib "myLib" .end - + TODO: check flags and syntax for this. =head2 Tokens, types and targets @@ -1029,8 +1093,6 @@ unicode:"Hello world" -TODO: is it "unicode"? or is it UTF8 or something? - IMCC currently allows identifiers to be used as types. During the parse, the identifier is checked whether it is a defined class. The built-in types int, num, pmc and string are always available. @@ -1070,11 +1132,45 @@ Test. A lot. -Bugs or improvements may be sent to the author, and of course greatly +Bugs or improvements may be sent to the author, and are of course greatly appreciated. Moreover, if you find any missing constructs that are in IMCC, indications of these would be appreciated as well. =back +=head1 REFERENCES + +=over 4 + +=item * + +languages/PIR/lib/pir.pg - The actual PIR grammar implementation + +=item * + +PDD03 - Parrot Calling Conventions + +=item * + +PDD20 - Lexically scoped variables in Parrot + +=item * + +docs/imcc/calling_conventions.pod - definition of sub flags (:init etc) + +=back + +=head1 CHANGES + +0.1 + +=over 4 + +=item * + +Initial version having a version number. + +=back + =cut
