Index: languages/PIR/docs/pirgrammar.html
===================================================================
--- languages/PIR/docs/pirgrammar.html	(revision 16915)
+++ languages/PIR/docs/pirgrammar.html	(working copy)
@@ -1,1260 +1,1329 @@
-<?xml version="1.0" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<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:" />
-</head>
-
-<body style="background-color: white">
-
-<p><a name="__index__"></a></p>
-<!-- INDEX BEGIN -->
-
-<ul>
-
-	<li><a href="#name">NAME</a></li>
-	<li><a href="#description">DESCRIPTION</a></li>
-	<li><a href="#status">STATUS</a></li>
-	<li><a href="#version">VERSION</a></li>
-	<li><a href="#lexical_conventions">LEXICAL CONVENTIONS</a></li>
-	<ul>
-
-		<li><a href="#pir_directives">PIR Directives</a></li>
-		<li><a href="#registers">Registers</a></li>
-		<li><a href="#constants">Constants</a></li>
-		<li><a href="#identifiers">Identifiers</a></li>
-		<li><a href="#labels">Labels</a></li>
-		<li><a href="#macro_identifiers">Macro identifiers</a></li>
-	</ul>
-
-	<li><a href="#grammar_rules">GRAMMAR RULES</a></li>
-	<ul>
-
-		<li><a href="#compilation_units">Compilation Units</a></li>
-		<li><a href="#subroutine_definitions">Subroutine definitions</a></li>
-		<ul>
-
-			<li><a href="#examples_subroutine">Examples subroutine</a></li>
-		</ul>
-
-		<li><a href="#pir_instructions">PIR instructions</a></li>
-		<li><a href="#local_declarations">Local declarations</a></li>
-		<ul>
-
-			<li><a href="#examples_local_declarations">Examples local declarations</a></li>
-		</ul>
-
-		<li><a href="#lexical_declarations">Lexical declarations</a></li>
-		<ul>
-
-			<li><a href="#example_lexical_declarations">Example lexical declarations</a></li>
-		</ul>
-
-		<li><a href="#global_definitions">Global definitions</a></li>
-		<ul>
-
-			<li><a href="#example_global_declarations">Example global declarations</a></li>
-		</ul>
-
-		<li><a href="#constant_definitions">Constant definitions</a></li>
-		<ul>
-
-			<li><a href="#example_constant_definitions">Example constant definitions</a></li>
-		</ul>
-
-		<li><a href="#conditional_statements">Conditional statements</a></li>
-		<ul>
-
-			<li><a href="#examples_conditional_statements">Examples conditional statements</a></li>
-		</ul>
-
-		<li><a href="#branching_statements">Branching statements</a></li>
-		<ul>
-
-			<li><a href="#examples_branching_statements">Examples branching statements</a></li>
-		</ul>
-
-		<li><a href="#operators">Operators</a></li>
-		<li><a href="#expressions">Expressions</a></li>
-		<ul>
-
-			<li><a href="#example_expressions">Example expressions</a></li>
-		</ul>
-
-		<li><a href="#assignments">Assignments</a></li>
-		<ul>
-
-			<li><a href="#examples_assignment_statements">Examples assignment statements</a></li>
-		</ul>
-
-		<li><a href="#heredoc">Heredoc</a></li>
-		<ul>
-
-			<li><a href="#example_heredoc">Example Heredoc</a></li>
-		</ul>
-
-		<li><a href="#invoking_subroutines_and_methods">Invoking subroutines and methods</a></li>
-		<ul>
-
-			<li><a href="#example_long_subroutine_call">Example long subroutine call</a></li>
-		</ul>
-
-		<li><a href="#short_subroutine_invocation">Short subroutine invocation</a></li>
-		<ul>
-
-			<li><a href="#example_short_subroutine_call">Example short subroutine call</a></li>
-		</ul>
-
-		<li><a href="#return_values_from_subroutines">Return values from subroutines</a></li>
-		<ul>
-
-			<li><a href="#example_long_return_statement">Example long return statement</a></li>
-		</ul>
-
-		<li><a href="#short_return_statement">Short return statement</a></li>
-		<ul>
-
-			<li><a href="#example_short_return_statement">Example short return statement</a></li>
-		</ul>
-
-		<li><a href="#long_yield_statements">Long yield statements</a></li>
-		<ul>
-
-			<li><a href="#example_long_yield_statement">Example long yield statement</a></li>
-		</ul>
-
-		<li><a href="#short_yield_statements">Short yield statements</a></li>
-		<ul>
-
-			<li><a href="#example_short_yield_statement">Example short yield statement</a></li>
-		</ul>
-
-		<li><a href="#tail_calls">Tail calls</a></li>
-		<ul>
-
-			<li><a href="#example_tail_call">Example tail call</a></li>
-		</ul>
-
-		<li><a href="#symbol_namespaces">Symbol namespaces</a></li>
-		<ul>
-
-			<li><a href="#example_open_close_namespaces">Example open/close namespaces</a></li>
-		</ul>
-
-		<li><a href="#emit_blocks">Emit blocks</a></li>
-		<ul>
-
-			<li><a href="#example_emit_block">Example Emit block</a></li>
-		</ul>
-
-		<li><a href="#macros">Macros</a></li>
-		<ul>
-
-			<li><a href="#example_macros">Example Macros</a></li>
-		</ul>
-
-		<li><a href="#pir_pragmas">PIR Pragmas</a></li>
-		<ul>
-
-			<li><a href="#examples_pragmas">Examples pragmas</a></li>
-		</ul>
-
-		<li><a href="#tokens__types_and_targets">Tokens, types and targets</a></li>
-		<ul>
-
-			<li><a href="#notes_on_tokens__types_and_targets">Notes on Tokens, types and targets</a></li>
-		</ul>
-
-	</ul>
-
-	<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 -->
-
-<hr />
-<p>
-</p>
-<h1><a name="name">NAME</a></h1>
-<p>PIR.pod - The Grammar of languages/PIR</p>
-<p>
-</p>
-<hr />
-<h1><a name="description">DESCRIPTION</a></h1>
-<p>This document provides a more readable grammar of languages/PIR. The actual specification
-for PIR is a bit more complex. This grammar for humans does not contain error
-handling and some other issues unimportant for this PIR reference.</p>
-<p>
-</p>
-<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 <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>0.1</p>
-<p>
-</p>
-<hr />
-<h1><a name="lexical_conventions">LEXICAL CONVENTIONS</a></h1>
-<p>
-</p>
-<h2><a name="pir_directives">PIR Directives</a></h2>
-<p>PIR has a number of directives. All directives start with a dot. Macro identifiers
-(when using a macro, on expansion) also start with a dot (see below). Therefore,
-it is important not to use any of the PIR directives as a macro identifier. The
-PIR directives are:</p>
-<pre>
-  .arg            .invocant          .pcc_call
-  .const          .lex               .pcc_end_return
-  .emit           .line              .pcc_end_yield
-  .end            .loadlib           .pcc_end
-  .endnamespace   .local             .pcc_sub
-  .eom            .meth_call         .pragma
-  .get_results    .namespace         .return
-  .global         .nci_call          .result
-  .HLL_map        .param             .sub
-  .HLL            .pcc_begin_return  .sym
-  .immediate      .pcc_begin_yield   .yield
-  .include        .pcc_begin</pre>
-<p>
-</p>
-<h2><a name="registers">Registers</a></h2>
-<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>Symbolic, or temporary registers are written like:</p>
-<pre>
-  $[S|N|I|P]n, where n is a positive integer.</pre>
-<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: <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: <code>1.1</code>, <code>42.567</code></p>
-<p>A string constant is a single or double quoted series of characters.
-Examples: <code>'hello world'</code>, <code>&quot;Parrot&quot;</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
-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: <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:  <code>.myMacro</code></p>
-<p>
-</p>
-<hr />
-<h1><a name="grammar_rules">GRAMMAR RULES</a></h1>
-<p>
-</p>
-<h2><a name="compilation_units">Compilation Units</a></h2>
-<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 &quot;nl&quot;). Moreover, compilation units are always separated
-by a newline. Each of the different compilation units are discussed in this
-document.</p>
-<pre>
-  program:
-    compilation_unit [ nl compilation_unit ]*</pre>
-<pre>
-  compilation_unit:
-      global_def
-    | sub_def
-    | const_def
-    | macro_def
-    | pragma
-    | emit</pre>
-<p>
-</p>
-<h2><a name="subroutine_definitions">Subroutine definitions</a></h2>
-<pre>
-  sub_def:
-    [ &quot;.sub&quot; | &quot;.pcc_sub&quot; ] sub_id sub_pragmas nl body</pre>
-<pre>
-  sub_id:
-    identifier | string_constant</pre>
-<pre>
-  sub_pragmas:
-    sub_pragma [ &quot;,&quot;? sub_pragma ]*</pre>
-<pre>
-  sub_pragma:
-      &quot;:load&quot;
-    | &quot;:init&quot;
-    | &quot;:immediate&quot;
-    | &quot;:postcomp&quot;
-    | &quot;:main&quot;
-    | &quot;:anon&quot;
-    | &quot;:lex&quot;
-    | wrap_pragma
-    | vtable_pragma
-    | multi_pragma
-    | outer_pragma</pre>
-<pre>
-  wrap_pragma:
-    &quot;:wrap&quot; parenthesized_string</pre>
-<pre>
-  vtable_pragma:
-    &quot;:vtable&quot; parenthesized_string?</pre>
-<pre>
-  parenthesized_string:
-    &quot;(&quot; string_constant &quot;)&quot;</pre>
-<pre>
-  multi_pragma:
-    &quot;:multi&quot; &quot;(&quot; multi_types? &quot;)&quot;</pre>
-<pre>
-  outer_pragma:
-    &quot;:outer&quot; &quot;(&quot; sub_id &quot;)&quot;</pre>
-<pre>
-  multi_tyes:
-    multi_type [ &quot;,&quot; multi_type ]*</pre>
-<pre>
-  multi_type:
-      type
-    | &quot;_&quot;
-    | keylist
-    | identifier
-    | string_constant</pre>
-<pre>
-  body:
-    param_decl*
-    labeled_pir_instr*
-    &quot;.end&quot;</pre>
-<pre>
-  param_decl:
-    &quot;.param&quot;  [ [ type identifier ] | register ] get_flags? nl</pre>
-<pre>
-  get_flags:
-    [ &quot;:slurpy&quot;
-    | &quot;:optional&quot;
-    | &quot;:opt_flag&quot;
-    | named_flag
-    ]+</pre>
-<pre>
-  named_flag:
-    &quot;:named&quot; parenthesized_string?</pre>
-<p>
-</p>
-<h3><a name="examples_subroutine">Examples subroutine</a></h3>
-<p>The simplest example for a subroutine definition looks like:</p>
-<pre>
-        .sub foo
-        # PIR instructions go here
-        .end</pre>
-<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>
-<ul>
-<li>
-<pre>
- :load</pre>
-<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>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>This subroutine is executed immediately after being compiled. (Analagous to
-<code>BEGIN</code> in perl5.)</p>
-<li>
-<pre>
- :main</pre>
-<p>Indicates that the sub being defined is the entry point of the program. It can be compared to the main function in C.</p>
-<li>
-<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).
-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(type [, type]*)</pre>
-<p>Engage in multiple dispatch with the listed types.</p>
-<li>
-<pre>
- :outer('bar')</pre>
-<p>Indicates the sub being defined is lexically nested within the subroutine 'bar'.</p>
-<li>
-<pre>
- :anon</pre>
-<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. 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 &quot;bar&quot;. That means
-that when &quot;bar&quot; 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
-not necessary. The subroutine name can also be a string instead of a bareword, as is shown in this
-example:</p>
-<pre>
-        .sub 'foo' :load, :init :anon
-        # PIR body
-        .end</pre>
-<p>Parameter definitions have the following syntax:</p>
-<pre>
-        .sub main
-          .param int argc :optional
-          .param int has_argc :optional
-          .param num nParam
-          .param pmc argv :slurpy         
-          .param string sParam :named('foo')
-          .param $P0 :named('bar')
-          # body
-        .end</pre>
-<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>
-<p>Indicates the parameter being defined is optional.</p>
-<li>
-<pre>
- :opt_flag</pre>
-<p>This flag can be given to a parameter defined <em>after</em> an optional parameter. During runtime,
-the parameter is automatically given a value, and is <em>not</em> passed by the caller. The value
-of this parameter indicates whether the previous (optional) parameter was present.</p>
-</ul>
-<p>The correct order of the parameters depends on the flag they have.</p>
-<p>
-</p>
-<h2><a name="pir_instructions">PIR instructions</a></h2>
-<pre>
-  labeled_pir_instr:
-    label? instr nl</pre>
-<pre>
-  labeled_pasm_instr:
-    label? pasm_instr nl</pre>
-<pre>
-  instr:
-    pir_instr | pasm_instr</pre>
-<p>NOTE: the rule 'pasm_instr' is not included in this reference grammar. pasm_instr
-defines the syntax for pure PASM instructions.</p>
-<pre>
-  pir_instr:
-      local_decl
-    | lexical_decl
-    | const_def
-    | conditional_stat
-    | assignment_stat
-    | open_namespace
-    | close_namespace
-    | return_stat
-    | sub_invocation
-    | macro_invocation
-    | jump_stat
-    | source_info</pre>
-<p>
-</p>
-<h2><a name="local_declarations">Local declarations</a></h2>
-<pre>
-  local_decl:
-    [ &quot;.local&quot; | &quot;.sym&quot; ] type local_id_list</pre>
-<pre>
-  local_id_list:
-    local_id [ &quot;,&quot; local_id ]*</pre>
-<pre>
-  local_id:
-    identifier &quot;:unique_reg&quot;?</pre>
-<p>
-</p>
-<h3><a name="examples_local_declarations">Examples local declarations</a></h3>
-<p>Local temporary variables can be declared by the directives <code>.local</code> or <code>.sym</code>. There is no
-difference between these directives, except within macro definitions. (See Macros).</p>
-<pre>
-        .local int i
-        .local num a, b, c
-        .sym string s1, s2
-        .sym pmc obj</pre>
-<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>
-<pre>
-  lexical_decl:
-    &quot;.lex&quot; string_constant &quot;,&quot; target</pre>
-<p>
-</p>
-<h3><a name="example_lexical_declarations">Example lexical declarations</a></h3>
-<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'.
-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 &quot;$a&quot;, $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 &quot;$a&quot;</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>
-<p>
-</p>
-<h2><a name="global_definitions">Global definitions</a></h2>
-<pre>
-  global_def:
-    &quot;.global&quot; identifier</pre>
-<p>
-</p>
-<h3><a name="example_global_declarations">Example global declarations</a></h3>
-<p>This syntax is defined in the parser of IMCC, but its functionality is not implemented. The goal is
-to allow for global definitions outside of subroutines. That way, the variable can be accessed by
-all subroutines without doing a global lookup. It is unclear whether this feature will be implemented.</p>
-<p>An example is:</p>
-<pre>
-        .global my_global_var</pre>
-<p>
-</p>
-<h2><a name="constant_definitions">Constant definitions</a></h2>
-<pre>
-  const_def:
-    &quot;.const&quot; type identifier &quot;=&quot; constant_expr</pre>
-<p>
-</p>
-<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.
-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>
-<pre>
-  conditional_stat:
-      [ &quot;if&quot; | &quot;unless&quot; ]
-    [ [ &quot;null&quot; target &quot;goto&quot; identifier ]
-    | [ simple_expr [ relational_op simple_expr ]? ]
-    ] &quot;goto&quot; identifier</pre>
-<p>
-</p>
-<h3><a name="examples_conditional_statements">Examples conditional statements</a></h3>
-<p>The syntax for <code>if</code> and <code>unless</code> statements is the same, except for the keyword itself.
-Therefore the examples will use either.</p>
-<pre>
-        if null $P0 goto L1</pre>
-<p>Checks whether $P0 is <code>null</code>, if it is, flow of control jumps to label L1</p>
-<pre>
-        unless $P0 goto L2
-        unless x   goto L2
-        unless 1.1 goto L2</pre>
-<p>Unless $P0, x or 1.1 are 'true', flow of control jumps to L2. When the argument is a PMC (like
-the first example), true-ness depends on the PMC itself. For instance, in some languages, the number
-0 is defined as 'true', in others it is considered 'false' (like C).</p>
-<pre>
-        if x &lt; y goto L1
-        if y != z  goto L1</pre>
-<p>are examples that check for the logical expression after <code>if</code>. Any of the <em>relational</em> operators may
-be used here.</p>
-<p>
-</p>
-<h2><a name="branching_statements">Branching statements</a></h2>
-<pre>
-  jump_stat:
-    &quot;goto&quot; identifier</pre>
-<p>
-</p>
-<h3><a name="examples_branching_statements">Examples branching statements</a></h3>
-<pre>
-        goto MyLabel</pre>
-<p>The program will continue running at label 'MyLabel:'.</p>
-<p>
-</p>
-<h2><a name="operators">Operators</a></h2>
-<pre>
-  relational_op:
-      &quot;==&quot;
-    | &quot;!=&quot;
-    | &quot;&lt;=&quot;
-    | &quot;&lt;&quot;
-    | &lt;&quot;=&quot;
-    | &lt;&quot;&quot;</pre>
-<pre>
-  binary_op:
-      &quot;+&quot;
-    | &quot;-&quot;
-    | &quot;/&quot;
-    | &quot;**&quot;
-    | &quot;*&quot;
-    | &quot;%&quot;
-    | &quot;&lt;&lt;&quot;
-    | &lt;&quot;&gt;&gt;&quot;
-    | &lt;&quot;&gt;&quot;
-    | &quot;&amp;&amp;&quot;
-    | &quot;||&quot;
-    | &quot;~~&quot;
-    | &quot;|&quot;
-    | &quot;&amp;&quot;
-    | &quot;~&quot;
-    | &quot;.&quot;</pre>
-<pre>
-  assign_op:
-      &quot;+=&quot;
-    | &quot;-=&quot;
-    | &quot;/=&quot;
-    | &quot;%=&quot;
-    | &quot;*=&quot;
-    | &quot;.=&quot;
-    | &quot;&amp;=&quot;
-    | &quot;|=&quot;
-    | &quot;~=&quot;
-    | &quot;&lt;&lt;=&quot;
-    | &lt;&quot;&gt;=&quot;
-    | &lt;&quot;&gt;&gt;=&quot;</pre>
-<pre>
-  unary_op:
-      &quot;!&quot;
-    | &quot;-&quot;
-    | &quot;~&quot;</pre>
-<p>
-</p>
-<h2><a name="expressions">Expressions</a></h2>
-<pre>
-  expression:
-      simple_expr
-    | simple_expr binary_op simple_expr
-    | unary_op simple_expr</pre>
-<pre>
-  simple_expr:
-      float_constant
-    | int_constant
-    | string_constant
-    | target</pre>
-<p>
-</p>
-<h3><a name="example_expressions">Example expressions</a></h3>
-<pre>
-        42
-        42 + x
-        1.1 / 0.1
-        &quot;hello&quot; . &quot;world&quot;
-        str1 . str2
-        -100
-        ~obj
-        !isSomething</pre>
-<p>Arithmetic operators are only allowed on floating-point numbers and integer values (or variables of that type).
-Likewise, string concatenation (&quot;.&quot;) 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>
-<pre>
-  assignment_stat:
-      target &quot;=&quot; short_sub_call
-    | target &quot;=&quot; target keylist
-    | target &quot;=&quot; expression
-    | target &quot;=&quot; &quot;new&quot; [ int_constant | string_constant | macro_id ]
-    | target &quot;=&quot; &quot;new&quot; keylist
-    | target &quot;=&quot; &quot;find_type&quot; [ string_constant | string_reg | id ]
-    | target &quot;=&quot; heredoc
-    | target &quot;=&quot; &quot;global&quot; string_constant
-    | target assign_op simple_expr
-    | target keylist &quot;=&quot; simple_expr
-    | &quot;global&quot; string_constant &quot;=&quot; target
-    | result_var_list &quot;=&quot; 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:
-    &quot;[&quot; keys &quot;]&quot;</pre>
-<pre>
-  keys:
-    key [ sep key ]*</pre>
-<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 &quot;..&quot;
-    | &quot;..&quot; simple_expr
-    | simple_expr &quot;..&quot; simple_expr</pre>
-<pre>
-  result_var_list:
-    &quot;(&quot; result_vars &quot;)&quot;</pre>
-<pre>
-  result_vars:
-    result_var [ &quot;,&quot; 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]
-        $I0 = $P0[&quot;Hello&quot;]
-        $P0 = new 42 # but this is really not very clear, better use identifiers</pre>
-<pre>
-        $S0 = &lt;&lt;'HELLO'
-        ...
-        HELLO</pre>
-<pre>
-        $P0 = global &quot;X&quot;
-        global &quot;X&quot; = $P0</pre>
-<pre>
-        .local int a, b, c
-        (a, b, c) = foo()</pre>
-<p>
-</p>
-<h2><a name="heredoc">Heredoc</a></h2>
-<p>NOTE: the heredoc rules are not complete or tested. Some work is required here.</p>
-<pre>
-  heredoc:
-    &quot;&lt;&lt;&quot; string_constant nl
-    heredoc_string
-    heredoc_label</pre>
-<pre>
-  heredoc_label:
-    ^^ identifier</pre>
-<pre>
-  heredoc_string:
-    [ \N | \n ]*</pre>
-<p>
-</p>
-<h3><a name="example_heredoc">Example Heredoc</a></h3>
-<pre>
-        .local string str
-        str = &lt;&lt;'ENDOFSTRING'
-          this text
-               is stored in the
-                     variable
-            named 'str'. Whitespace and newlines
-          are                  stored as well.
-        ENDOFSTRING</pre>
-<p>Note that the Heredoc identifier should be at the beginning of the line, no
-whitespace in front of it is allowed. Printing <code>str</code> would print:</p>
-<pre>
-    this text
-               is stored in the
-                     variable
-            named 'str'. Whitespace and newlines
-          are                  stored as well.</pre>
-<p>
-</p>
-<h2><a name="invoking_subroutines_and_methods">Invoking subroutines and methods</a></h2>
-<pre>
-  sub_invocation:
-    long_sub_call | short_sub_call</pre>
-<pre>
-  long_sub_call:
-    &quot;.pcc_begin&quot; nl
-    arguments
-    [ method_call | non_method_call] target nl
-    [ local_decl nl ]*
-    result_values
-    &quot;.pcc_end&quot;</pre>
-<pre>
-  non_method_call:
-    &quot;.pcc_call&quot; | &quot;.nci_call&quot;</pre>
-<pre>
-  method_call:
-    &quot;.invocant&quot; target nl
-    &quot;.meth_call&quot;</pre>
-<pre>
-  parenthesized_args:
-    &quot;(&quot; args &quot;)&quot;</pre>
-<pre>
-  args:
-    arg [ &quot;,&quot; arg ]</pre>
-<pre>
-  arg:
-    [ float_constant
-    | int_constant
-    | string_constant [ &quot;=&gt;&quot; target ]?
-    | target
-    ]
-    set_flags?</pre>
-<pre>
-  arguments:
-    [ &quot;.arg&quot; simple_expr set_flags? nl ]*</pre>
-<pre>
-  result_values:
-    [ &quot;.result&quot; target get_flags? nl ]*</pre>
-<pre>
-  set_flags:
-    [ &quot;:flat&quot;
-    | named_flag
-    ]+</pre>
-<p>
-</p>
-<h3><a name="example_long_subroutine_call">Example long subroutine call</a></h3>
-<p>The long subroutine call syntax is very suitable to be generated by a language compiler
-targeting Parrot. Its syntax is rather verbose, but easy to read. The minimal invocation
-looks like this:</p>
-<pre>
-        .pcc_begin
-        .pcc_call $P0
-        .pcc_end</pre>
-<p>Invoking instance methods is a simple variation:</p>
-<pre>
-        .pcc_begin
-        .invocant $P0
-        .meth_call $P1
-        .pcc_end</pre>
-<p>Passing parameters and retrieving return values is done like this:</p>
-<pre>
-        .pcc_begin
-        .arg 42
-        .pcc_call $P0
-        .local int res
-        .result res
-        .pcc_end</pre>
-<p>Parameters can take flags:</p>
-<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>
-<pre>
-        .pcc_begin
-        .nci_call $P0
-        .pcc_end</pre>
-<p>
-</p>
-<h2><a name="short_subroutine_invocation">Short subroutine invocation</a></h2>
-<pre>
-  short_sub_call:
-    invocant? [ target | string_constant ] parenthesized_args</pre>
-<pre>
-  invocant:
-    [ target&quot;.&quot; | target &quot;-&gt;&quot; ]</pre>
-<p>
-</p>
-<h3><a name="example_short_subroutine_call">Example short subroutine call</a></h3>
-<p>The short subroutine call syntax is useful when manually writing PIR code.
-Its simplest form is:</p>
-<pre>
-        foo()</pre>
-<p>Or a method call:</p>
-<pre>
-        obj.'toString'() # call the method 'toString'
-        obj.x() # call the method whose name is stored in C&lt;x&gt;</pre>
-<p>IMCC also allows the &quot;-&gt;&quot; instead of a dot, to make it readable for C++ programmers:</p>
-<pre>
-        obj-&gt;'toString'()</pre>
-<p>
-</p>
-<h2><a name="return_values_from_subroutines">Return values from subroutines</a></h2>
-<pre>
-  return_stat:
-      long_return_stat
-    | short_return_stat
-    | long_yield_stat
-    | short_yield_stat
-    | tail_call</pre>
-<pre>
-  long_return_stat:
-    &quot;.pcc_begin_return&quot; nl
-    return_directive*
-    &quot;.pcc_end_return&quot;</pre>
-<pre>
-  return_directive:
-    &quot;.return&quot; simple_expr set_flags? nl</pre>
-<p>
-</p>
-<h3><a name="example_long_return_statement">Example long return statement</a></h3>
-<pre>
-        .pcc_begin_return
-        .return 42
-        .return $P0 :flat
-        .pcc_end_return</pre>
-<p>
-</p>
-<h2><a name="short_return_statement">Short return statement</a></h2>
-<pre>
-  short_return_stat:
-    &quot;.return&quot; parenthesized_args</pre>
-<p>
-</p>
-<h3><a name="example_short_return_statement">Example short return statement</a></h3>
-<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>
-<pre>
-  long_yield_stat:
-    &quot;.pcc_begin_yield&quot; nl
-    return_directive*
-    &quot;.pcc_end_yield&quot;</pre>
-<p>
-</p>
-<h3><a name="example_long_yield_statement">Example long yield statement</a></h3>
-<pre>
-        .sub foo
-          .pcc_begin_yield
-          .return 42
-          .pcc_end_yield</pre>
-<pre>
-          <span class="comment"># and later in the sub, one could return another value:</span>
-</pre>
-<pre>
-          .pcc_begin_yield
-          .return 43
-          .pcc_end_yield
-        .end</pre>
-<pre>
-        # when invoking twice:
-        foo() # returns 42
-        foo() # returns 43</pre>
-<p>
-</p>
-<h2><a name="short_yield_statements">Short yield statements</a></h2>
-<pre>
-  short_yield_stat:
-    &quot;.yield&quot; parenthesized_args</pre>
-<p>
-</p>
-<h3><a name="example_short_yield_statement">Example short yield statement</a></h3>
-<pre>
-        .yield(&quot;hello&quot;, 42)</pre>
-<p>
-</p>
-<h2><a name="tail_calls">Tail calls</a></h2>
-<pre>
-  tail_call:
-    &quot;.return&quot; short_sub_call</pre>
-<p>
-</p>
-<h3><a name="example_tail_call">Example tail call</a></h3>
-<pre>
-        .return foo()</pre>
-<p>Returns the return values from <code>foo</code>. This is implemented by a tail call, which is more efficient than:</p>
-<pre>
-        .local pmc results = foo()
-        .return(results)</pre>
-<p>
-</p>
-<h2><a name="symbol_namespaces">Symbol namespaces</a></h2>
-<pre>
-  open_namespace:
-    &quot;.namespace&quot; identifier</pre>
-<pre>
-  close_namespace:
-    &quot;.endnamespace&quot; identifier</pre>
-<p>
-</p>
-<h3><a name="example_open_close_namespaces">Example open/close namespaces</a></h3>
-<pre>
-        .sub main
-          .local int x
-          x = 42
-          say x
-          .namespace NESTED
-          .local int x
-          x = 43
-          say x
-          .endnamespace NESTED
-          say x
-        .end</pre>
-<p>Will print:</p>
-<pre>
-        42
-        43
-        42</pre>
-<p>
-</p>
-<h2><a name="emit_blocks">Emit blocks</a></h2>
-<pre>
-  emit:
-    &quot;.emit&quot; nl
-    labeled_pasm_instr*
-    &quot;.eom&quot;</pre>
-<p>
-</p>
-<h3><a name="example_emit_block">Example Emit block</a></h3>
-<p>An emit block only allows PASM instructions,
-not PIR instructions.</p>
-<p>
-</p>
-<h2><a name="macros">Macros</a></h2>
-<pre>
-  macro_def:
-    &quot;.macro&quot; identifier macro_parameters? nl
-    macro_body</pre>
-<pre>
-  macro_parameters:
-    &quot;(&quot; id_list? &quot;)&quot;</pre>
-<pre>
-  macro_body:
-    .*?
-    &quot;.endm&quot; nl</pre>
-<pre>
-  macro_invocation:
-    macro_id parenthesized_args?</pre>
-<p>
-</p>
-<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 &quot;.endm&quot; are 'matched'.</p>
-<p>
-</p>
-<h2><a name="pir_pragmas">PIR Pragmas</a></h2>
-<pre>
-  pragma:
-      include
-    | new_operators
-    | loadlib
-    | namespace
-    | hll_mapping
-    | hll_specifier
-    | source_info</pre>
-<pre>
-  include:
-    &quot;.include&quot; string_constant</pre>
-<pre>
-  new_operators:
-    &quot;.pragma&quot; &quot;n_operators&quot; int_constant</pre>
-<pre>
-  loadlib:
-    &quot;.loadlib&quot; string_constant</pre>
-<pre>
-  namespace:
-    &quot;.namespace&quot; [ &quot;[&quot; namespace_id &quot;]&quot; ]?</pre>
-<pre>
-  hll_specifier:
-    &quot;.HLL&quot; string_constant &quot;,&quot; string_constant</pre>
-<pre>
-  hll_mapping:
-    &quot;.HLL_map&quot; int_constant &quot;,&quot; int_constant</pre>
-<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:
-    &quot;.line&quot; int_constant [ &quot;,&quot; string_constant ]?</pre>
-<pre>
-  id_list:
-    identifier [ &quot;,&quot; identifier ]*</pre>
-<p>
-</p>
-<h3><a name="examples_pragmas">Examples pragmas</a></h3>
-<pre>
-        .include &quot;myLib.pir&quot;</pre>
-<p>includes the source from the file &quot;myLib.pir&quot; 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>
-<pre>
-        $P1 = new .Integer
-        $P2 = new .Integer
-        $P1 = 42
-        $P2 = 43
-        $P0 = $P1 * $P2
-        # now, $P0 is automatically assigned a newly created PMC.</pre>
-<pre>
-        .line 100
-        .line 100, &quot;myfile.pir&quot;</pre>
-<p>NOTE: currently, the line directive is implemented in IMCC as #line.
-See the PROPOSALS document for more information on this.</p>
-<pre>
-        <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
-namespaces without doing OO-programming.</p>
-<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 &quot;Lua&quot;, &quot;lua_group&quot;</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 &quot;myLib&quot;</pre>
-<p>is a shortcut for telling Parrot that the library &quot;myLib&quot; should be loaded when running the program. In fact,
-it is a shortcut for:</p>
-<pre>
-        .sub _load :load :anon
-          loadlib &quot;myLib&quot;
-        .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>
-<pre>
-  string_constant:
-    charset_specifier?  quoted_string</pre>
-<pre>
-  charset_specifier:
-      &quot;ascii:&quot;
-    | &quot;binary:&quot;
-    | &quot;unicode:&quot;
-    | &quot;iso-8859-1:&quot;</pre>
-<pre>
-  type:
-      &quot;int&quot;
-    | &quot;num&quot;
-    | &quot;pmc&quot;
-    | &quot;object&quot;
-    | &quot;string&quot;
-    | &quot;Array&quot;
-    | &quot;Hash&quot;</pre>
-<pre>
-  target:
-    identifier | register</pre>
-<p>
-</p>
-<h3><a name="notes_on_tokens__types_and_targets">Notes on Tokens, types and targets</a></h3>
-<p>A string constant can be written like:</p>
-<pre>
-        &quot;Hello world&quot;</pre>
-<p>but if desirable, the character set can be specified:</p>
-<pre>
-        unicode:&quot;Hello world&quot;</pre>
-<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>
-<p>A <code>target</code> is something that can be assigned to, it is an L-value (but of course may be read just like
-an R-value). It is either an identifier or a register.</p>
-<p>
-</p>
-<hr />
-<h1><a name="author">AUTHOR</a></h1>
-<p>Klaas-Jan Stol <a href="mailto:[parrotcode@gmail.com]">[parrotcode@gmail.com]</a></p>
-<p>
-</p>
-<hr />
-<h1><a name="known_issues_and_bugs">KNOWN ISSUES AND BUGS</a></h1>
-<p>Some work should be done on:</p>
-<ul>
-<li>
-<p>Macro parsing</p>
-</li>
-<li>
-<p>Heredoc parsing</p>
-</li>
-<li>
-<p>The rule 'type' does currently not include custom types (user defined).
-Probably it needs an alternative &quot;identifier&quot;. 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 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>
-
-</html>
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<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:" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+	<li><a href="#name">NAME</a></li>
+	<li><a href="#description">DESCRIPTION</a></li>
+	<li><a href="#status">STATUS</a></li>
+	<li><a href="#version">VERSION</a></li>
+	<li><a href="#lexical_conventions">LEXICAL CONVENTIONS</a></li>
+	<ul>
+
+		<li><a href="#pir_directives">PIR Directives</a></li>
+		<li><a href="#registers">Registers</a></li>
+		<li><a href="#constants">Constants</a></li>
+		<li><a href="#identifiers">Identifiers</a></li>
+		<li><a href="#labels">Labels</a></li>
+		<li><a href="#macro_identifiers">Macro identifiers</a></li>
+	</ul>
+
+	<li><a href="#grammar_rules">GRAMMAR RULES</a></li>
+	<ul>
+
+		<li><a href="#compilation_units">Compilation Units</a></li>
+		<li><a href="#subroutine_definitions">Subroutine definitions</a></li>
+		<ul>
+
+			<li><a href="#examples_subroutine">Examples subroutine</a></li>
+		</ul>
+
+		<li><a href="#pir_instructions">PIR instructions</a></li>
+		<li><a href="#local_declarations">Local declarations</a></li>
+		<ul>
+
+			<li><a href="#examples_local_declarations">Examples local declarations</a></li>
+		</ul>
+
+		<li><a href="#lexical_declarations">Lexical declarations</a></li>
+		<ul>
+
+			<li><a href="#example_lexical_declarations">Example lexical declarations</a></li>
+		</ul>
+
+		<li><a href="#global_definitions">Global definitions</a></li>
+		<ul>
+
+			<li><a href="#example_global_declarations">Example global declarations</a></li>
+		</ul>
+
+		<li><a href="#constant_definitions">Constant definitions</a></li>
+		<ul>
+
+			<li><a href="#example_constant_definitions">Example constant definitions</a></li>
+		</ul>
+
+		<li><a href="#conditional_statements">Conditional statements</a></li>
+		<ul>
+
+			<li><a href="#examples_conditional_statements">Examples conditional statements</a></li>
+		</ul>
+
+		<li><a href="#branching_statements">Branching statements</a></li>
+		<ul>
+
+			<li><a href="#examples_branching_statements">Examples branching statements</a></li>
+		</ul>
+
+		<li><a href="#operators">Operators</a></li>
+		<li><a href="#expressions">Expressions</a></li>
+		<ul>
+
+			<li><a href="#example_expressions">Example expressions</a></li>
+		</ul>
+
+		<li><a href="#assignments">Assignments</a></li>
+		<ul>
+
+			<li><a href="#examples_assignment_statements">Examples assignment statements</a></li>
+		</ul>
+
+		<li><a href="#heredoc">Heredoc</a></li>
+		<ul>
+
+			<li><a href="#example_heredoc">Example Heredoc</a></li>
+		</ul>
+
+		<li><a href="#invoking_subroutines_and_methods">Invoking subroutines and methods</a></li>
+		<ul>
+
+			<li><a href="#example_long_subroutine_call">Example long subroutine call</a></li>
+		</ul>
+
+		<li><a href="#short_subroutine_invocation">Short subroutine invocation</a></li>
+		<ul>
+
+			<li><a href="#example_short_subroutine_call">Example short subroutine call</a></li>
+		</ul>
+
+		<li><a href="#return_values_from_subroutines">Return values from subroutines</a></li>
+		<ul>
+
+			<li><a href="#example_long_return_statement">Example long return statement</a></li>
+		</ul>
+
+		<li><a href="#short_return_statement">Short return statement</a></li>
+		<ul>
+
+			<li><a href="#example_short_return_statement">Example short return statement</a></li>
+		</ul>
+
+		<li><a href="#long_yield_statements">Long yield statements</a></li>
+		<ul>
+
+			<li><a href="#example_long_yield_statement">Example long yield statement</a></li>
+		</ul>
+
+		<li><a href="#short_yield_statements">Short yield statements</a></li>
+		<ul>
+
+			<li><a href="#example_short_yield_statement">Example short yield statement</a></li>
+		</ul>
+
+		<li><a href="#tail_calls">Tail calls</a></li>
+		<ul>
+
+			<li><a href="#example_tail_call">Example tail call</a></li>
+		</ul>
+
+		<li><a href="#symbol_namespaces">Symbol namespaces</a></li>
+		<ul>
+
+			<li><a href="#example_open_close_namespaces">Example open/close namespaces</a></li>
+		</ul>
+
+		<li><a href="#emit_blocks">Emit blocks</a></li>
+		<ul>
+
+			<li><a href="#example_emit_block">Example Emit block</a></li>
+		</ul>
+
+		<li><a href="#macros">Macros</a></li>
+		<ul>
+
+			<li><a href="#example_macros">Example Macros</a></li>
+		</ul>
+
+		<li><a href="#pir_pragmas">PIR Pragmas</a></li>
+		<ul>
+
+			<li><a href="#examples_pragmas">Examples pragmas</a></li>
+		</ul>
+
+		<li><a href="#tokens__types_and_targets">Tokens, types and targets</a></li>
+		<ul>
+
+			<li><a href="#notes_on_tokens__types_and_targets">Notes on Tokens, types and targets</a></li>
+		</ul>
+
+	</ul>
+
+	<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 -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>PIR.pod - The Grammar of languages/PIR</p>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>This document provides a more readable grammar of languages/PIR. The actual specification
+for PIR is a bit more complex. This grammar for humans does not contain error
+handling and some other issues unimportant for this PIR reference.</p>
+<p>
+</p>
+<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 <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>0.1.1</p>
+<p>
+</p>
+<hr />
+<h1><a name="lexical_conventions">LEXICAL CONVENTIONS</a></h1>
+<p>
+</p>
+<h2><a name="pir_directives">PIR Directives</a></h2>
+<p>PIR has a number of directives. All directives start with a dot. Macro identifiers
+(when using a macro, on expansion) also start with a dot (see below). Therefore,
+it is important not to use any of the PIR directives as a macro identifier. The
+PIR directives are:</p>
+<pre>
+  .arg            .invocant          .pcc_call
+  .const          .lex               .pcc_end_return
+  .emit           .line              .pcc_end_yield
+  .end            .loadlib           .pcc_end
+  .endnamespace   .local             .pcc_sub
+  .eom            .meth_call         .pragma
+  .get_results    .namespace         .return
+  .global         .nci_call          .result
+  .HLL_map        .param             .sub
+  .HLL            .pcc_begin_return  .sym
+  .immediate      .pcc_begin_yield   .yield
+  .include        .pcc_begin</pre>
+<p>
+</p>
+<h2><a name="registers">Registers</a></h2>
+<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>Symbolic, or temporary registers are written like:</p>
+<pre>
+  $[S|N|I|P]n, where n is a positive integer.</pre>
+<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: <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: <code>1.1</code>, <code>42.567</code></p>
+<p>A string constant is a single or double quoted series of characters.
+Examples: <code>'hello world'</code>, <code>&quot;Parrot&quot;</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
+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: <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:  <code>.myMacro</code></p>
+<p>
+</p>
+<hr />
+<h1><a name="grammar_rules">GRAMMAR RULES</a></h1>
+<p>
+</p>
+<h2><a name="compilation_units">Compilation Units</a></h2>
+<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 &quot;nl&quot;). Moreover, compilation units are always separated
+by a newline. Each of the different compilation units are discussed in this
+document.</p>
+<pre>
+  program:
+    compilation_unit [ nl compilation_unit ]*</pre>
+<pre>
+  compilation_unit:
+      global_def
+    | sub_def
+    | const_def
+    | macro_def
+    | pragma
+    | emit</pre>
+<p>
+</p>
+<h2><a name="subroutine_definitions">Subroutine definitions</a></h2>
+<pre>
+  sub_def:
+    [ &quot;.sub&quot; | &quot;.pcc_sub&quot; ] sub_id sub_pragmas nl body</pre>
+<pre>
+  sub_id:
+    identifier | string_constant</pre>
+<pre>
+  sub_pragmas:
+    sub_pragma [ &quot;,&quot;? sub_pragma ]*</pre>
+<pre>
+  sub_pragma:
+      &quot;:load&quot;
+    | &quot;:init&quot;
+    | &quot;:immediate&quot;
+    | &quot;:postcomp&quot;
+    | &quot;:main&quot;
+    | &quot;:anon&quot;
+    | &quot;:lex&quot;
+    | wrap_pragma
+    | vtable_pragma
+    | multi_pragma
+    | outer_pragma</pre>
+<pre>
+  wrap_pragma:
+    &quot;:wrap&quot; parenthesized_string</pre>
+<pre>
+  vtable_pragma:
+    &quot;:vtable&quot; parenthesized_string?</pre>
+<pre>
+  parenthesized_string:
+    &quot;(&quot; string_constant &quot;)&quot;</pre>
+<pre>
+  multi_pragma:
+    &quot;:multi&quot; &quot;(&quot; multi_types? &quot;)&quot;</pre>
+<pre>
+  outer_pragma:
+    &quot;:outer&quot; &quot;(&quot; sub_id &quot;)&quot;</pre>
+<pre>
+  multi_tyes:
+    multi_type [ &quot;,&quot; multi_type ]*</pre>
+<pre>
+  multi_type:
+      type
+    | &quot;_&quot;
+    | keylist
+    | identifier
+    | string_constant</pre>
+<pre>
+  body:
+    param_decl*
+    labeled_pir_instr*
+    &quot;.end&quot;</pre>
+<pre>
+  param_decl:
+    &quot;.param&quot;  [ [ type identifier ] | register ] get_flags? nl</pre>
+<pre>
+  get_flags:
+    [ &quot;:slurpy&quot;
+    | &quot;:optional&quot;
+    | &quot;:opt_flag&quot;
+    | named_flag
+    ]+</pre>
+<pre>
+  named_flag:
+    &quot;:named&quot; parenthesized_string?</pre>
+<p>
+</p>
+<h3><a name="examples_subroutine">Examples subroutine</a></h3>
+<p>The simplest example for a subroutine definition looks like:</p>
+<pre>
+        .sub foo
+        # PIR instructions go here
+        .end</pre>
+<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>
+<ul>
+<li>
+<pre>
+ :load</pre>
+<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>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>This subroutine is executed immediately after being compiled. (Analagous to
+<code>BEGIN</code> in perl5.)</p>
+<li>
+<pre>
+ :main</pre>
+<p>Indicates that the sub being defined is the entry point of the program. It can be compared to the main function in C.</p>
+<li>
+<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).
+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(type [, type]*)</pre>
+<p>Engage in multiple dispatch with the listed types.</p>
+<li>
+<pre>
+ :outer('bar')</pre>
+<p>Indicates the sub being defined is lexically nested within the subroutine 'bar'.</p>
+<li>
+<pre>
+ :anon</pre>
+<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. 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 &quot;bar&quot;. That means
+that when &quot;bar&quot; 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
+not necessary. The subroutine name can also be a string instead of a bareword, as is shown in this
+example:</p>
+<pre>
+        .sub 'foo' :load, :init :anon
+        # PIR body
+        .end</pre>
+<p>Parameter definitions have the following syntax:</p>
+<pre>
+        .sub main
+          .param int argc :optional
+          .param int has_argc :optional
+          .param num nParam
+          .param pmc argv :slurpy
+          .param string sParam :named('foo')
+          .param $P0 :named('bar')
+          # body
+        .end</pre>
+<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>
+<p>Indicates the parameter being defined is optional.</p>
+<li>
+<pre>
+ :opt_flag</pre>
+<p>This flag can be given to a parameter defined <em>after</em> an optional parameter. During runtime,
+the parameter is automatically given a value, and is <em>not</em> passed by the caller. The value
+of this parameter indicates whether the previous (optional) parameter was present.</p>
+</ul>
+<p>The correct order of the parameters depends on the flag they have.</p>
+<p>
+</p>
+<h2><a name="pir_instructions">PIR instructions</a></h2>
+<pre>
+  labeled_pir_instr:
+    label? instr nl</pre>
+<pre>
+  labeled_pasm_instr:
+    label? pasm_instr nl</pre>
+<pre>
+  instr:
+    pir_instr | pasm_instr</pre>
+<p>NOTE: the rule 'pasm_instr' is not included in this reference grammar. pasm_instr
+defines the syntax for pure PASM instructions.</p>
+<pre>
+  pir_instr:
+      local_decl
+    | lexical_decl
+    | const_def
+    | conditional_stat
+    | assignment_stat
+    | open_namespace
+    | close_namespace
+    | return_stat
+    | sub_invocation
+    | macro_invocation
+    | jump_stat
+    | source_info</pre>
+<p>
+</p>
+<h2><a name="local_declarations">Local declarations</a></h2>
+<pre>
+  local_decl:
+    [ &quot;.local&quot; | &quot;.sym&quot; ] type local_id_list</pre>
+<pre>
+  local_id_list:
+    local_id [ &quot;,&quot; local_id ]*</pre>
+<pre>
+  local_id:
+    identifier &quot;:unique_reg&quot;?</pre>
+<p>
+</p>
+<h3><a name="examples_local_declarations">Examples local declarations</a></h3>
+<p>Local temporary variables can be declared by the directives <code>.local</code> or <code>.sym</code>. There is no
+difference between these directives, except within macro definitions. (See Macros).</p>
+<pre>
+        .local int i
+        .local num a, b, c
+        .sym string s1, s2
+        .sym pmc obj</pre>
+<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>
+<pre>
+  lexical_decl:
+    &quot;.lex&quot; string_constant &quot;,&quot; target</pre>
+<p>
+</p>
+<h3><a name="example_lexical_declarations">Example lexical declarations</a></h3>
+<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'.
+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 &quot;i&quot;, $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 &quot;i&quot;</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>
+<p>
+</p>
+<h2><a name="global_definitions">Global definitions</a></h2>
+<pre>
+  global_def:
+    &quot;.global&quot; identifier</pre>
+<p>
+</p>
+<h3><a name="example_global_declarations">Example global declarations</a></h3>
+<p>This syntax is defined in the parser of IMCC, but its functionality is not implemented. The goal is
+to allow for global definitions outside of subroutines. That way, the variable can be accessed by
+all subroutines without doing a global lookup. It is unclear whether this feature will be implemented.</p>
+<p>An example is:</p>
+<pre>
+        .global my_global_var</pre>
+<p>
+</p>
+<h2><a name="constant_definitions">Constant definitions</a></h2>
+<pre>
+  const_def:
+    &quot;.const&quot; type identifier &quot;=&quot; constant_expr</pre>
+<p>
+</p>
+<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.
+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>
+<pre>
+  conditional_stat:
+      [ &quot;if&quot; | &quot;unless&quot; ]
+    [ [ &quot;null&quot; target &quot;goto&quot; identifier ]
+    | [ simple_expr [ relational_op simple_expr ]? ]
+    ] &quot;goto&quot; identifier</pre>
+<p>
+</p>
+<h3><a name="examples_conditional_statements">Examples conditional statements</a></h3>
+<p>The syntax for <code>if</code> and <code>unless</code> statements is the same, except for the keyword itself.
+Therefore the examples will use either.</p>
+<pre>
+        if null $P0 goto L1</pre>
+<p>Checks whether $P0 is <code>null</code>, if it is, flow of control jumps to label L1</p>
+<pre>
+        unless $P0 goto L2
+        unless x   goto L2
+        unless 1.1 goto L2</pre>
+<p>Unless $P0, x or 1.1 are 'true', flow of control jumps to L2. When the argument is a PMC (like
+the first example), true-ness depends on the PMC itself. For instance, in some languages, the number
+0 is defined as 'true', in others it is considered 'false' (like C).</p>
+<pre>
+        if x &lt; y goto L1
+        if y != z  goto L1</pre>
+<p>are examples that check for the logical expression after <code>if</code>. Any of the <em>relational</em> operators may
+be used here.</p>
+<p>
+</p>
+<h2><a name="branching_statements">Branching statements</a></h2>
+<pre>
+  jump_stat:
+    &quot;goto&quot; identifier</pre>
+<p>
+</p>
+<h3><a name="examples_branching_statements">Examples branching statements</a></h3>
+<pre>
+        goto MyLabel</pre>
+<p>The program will continue running at label 'MyLabel:'.</p>
+<p>
+</p>
+<h2><a name="operators">Operators</a></h2>
+<pre>
+  relational_op:
+      &quot;==&quot;
+    | &quot;!=&quot;
+    | &quot;&lt;=&quot;
+    | &quot;&lt;&quot;
+    | &lt;&quot;=&quot;
+    | &lt;&quot;&quot;</pre>
+<pre>
+  binary_op:
+      &quot;+&quot;
+    | &quot;-&quot;
+    | &quot;/&quot;
+    | &quot;**&quot;
+    | &quot;*&quot;
+    | &quot;%&quot;
+    | &quot;&lt;&lt;&quot;
+    | &lt;&quot;&gt;&gt;&quot;
+    | &lt;&quot;&gt;&quot;
+    | &quot;&amp;&amp;&quot;
+    | &quot;||&quot;
+    | &quot;~~&quot;
+    | &quot;|&quot;
+    | &quot;&amp;&quot;
+    | &quot;~&quot;
+    | &quot;.&quot;</pre>
+<pre>
+  assign_op:
+      &quot;+=&quot;
+    | &quot;-=&quot;
+    | &quot;/=&quot;
+    | &quot;%=&quot;
+    | &quot;*=&quot;
+    | &quot;.=&quot;
+    | &quot;&amp;=&quot;
+    | &quot;|=&quot;
+    | &quot;~=&quot;
+    | &quot;&lt;&lt;=&quot;
+    | &lt;&quot;&gt;=&quot;
+    | &lt;&quot;&gt;&gt;=&quot;</pre>
+<pre>
+  unary_op:
+      &quot;!&quot;
+    | &quot;-&quot;
+    | &quot;~&quot;</pre>
+<p>
+</p>
+<h2><a name="expressions">Expressions</a></h2>
+<pre>
+  expression:
+      simple_expr
+    | simple_expr binary_op simple_expr
+    | unary_op simple_expr</pre>
+<pre>
+  simple_expr:
+      float_constant
+    | int_constant
+    | string_constant
+    | target</pre>
+<p>
+</p>
+<h3><a name="example_expressions">Example expressions</a></h3>
+<pre>
+        42
+        42 + x
+        1.1 / 0.1
+        &quot;hello&quot; . &quot;world&quot;
+        str1 . str2
+        -100
+        ~obj
+        !isSomething</pre>
+<p>Arithmetic operators are only allowed on floating-point numbers and integer values (or variables of that type).
+Likewise, string concatenation (&quot;.&quot;) 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>
+<pre>
+  assignment_stat:
+      target &quot;=&quot; short_sub_call
+    | target &quot;=&quot; target keylist
+    | target &quot;=&quot; expression
+    | target &quot;=&quot; &quot;new&quot; [ int_constant | string_constant | macro_id ]
+    | target &quot;=&quot; &quot;new&quot; keylist
+    | target &quot;=&quot; &quot;find_type&quot; [ string_constant | string_reg | id ]
+    | target &quot;=&quot; heredoc
+    | target &quot;=&quot; &quot;global&quot; string_constant
+    | target assign_op simple_expr
+    | target keylist &quot;=&quot; simple_expr
+    | &quot;global&quot; string_constant &quot;=&quot; target
+    | result_var_list &quot;=&quot; 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:
+    &quot;[&quot; keys &quot;]&quot;</pre>
+<pre>
+  keys:
+    key [ sep key ]*</pre>
+<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 &quot;..&quot;
+    | &quot;..&quot; simple_expr
+    | simple_expr &quot;..&quot; simple_expr</pre>
+<pre>
+  result_var_list:
+    &quot;(&quot; result_vars &quot;)&quot;</pre>
+<pre>
+  result_vars:
+    result_var [ &quot;,&quot; 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]
+        $I0 = $P0[&quot;Hello&quot;]
+        $P0 = new 42 # but this is really not very clear, better use identifiers</pre>
+<pre>
+        $S0 = &lt;&lt;'HELLO'
+        ...
+        HELLO</pre>
+<pre>
+        $P0 = global &quot;X&quot;
+        global &quot;X&quot; = $P0</pre>
+<pre>
+        .local int a, b, c
+        (a, b, c) = foo()</pre>
+<p>
+</p>
+<h2><a name="heredoc">Heredoc</a></h2>
+<p>NOTE: the heredoc rules are not complete or tested. Some work is required here.</p>
+<pre>
+  heredoc:
+    &quot;&lt;&lt;&quot; string_constant nl
+    heredoc_string
+    heredoc_label</pre>
+<pre>
+  heredoc_label:
+    ^^ identifier</pre>
+<pre>
+  heredoc_string:
+    [ \N | \n ]*</pre>
+<p>
+</p>
+<h3><a name="example_heredoc">Example Heredoc</a></h3>
+<pre>
+        .local string str
+        str = &lt;&lt;'ENDOFSTRING'
+          this text
+               is stored in the
+                     variable
+            named 'str'. Whitespace and newlines
+          are                  stored as well.
+        ENDOFSTRING</pre>
+<p>Note that the Heredoc identifier should be at the beginning of the line, no
+whitespace in front of it is allowed. Printing <code>str</code> would print:</p>
+<pre>
+    this text
+               is stored in the
+                     variable
+            named 'str'. Whitespace and newlines
+          are                  stored as well.</pre>
+<p>
+</p>
+<h2><a name="invoking_subroutines_and_methods">Invoking subroutines and methods</a></h2>
+<pre>
+  sub_invocation:
+    long_sub_call | short_sub_call</pre>
+<pre>
+  long_sub_call:
+    &quot;.pcc_begin&quot; nl
+    arguments
+    [ method_call | non_method_call] target nl
+    [ local_decl nl ]*
+    result_values
+    &quot;.pcc_end&quot;</pre>
+<pre>
+  non_method_call:
+    &quot;.pcc_call&quot; | &quot;.nci_call&quot;</pre>
+<pre>
+  method_call:
+    &quot;.invocant&quot; target nl
+    &quot;.meth_call&quot;</pre>
+<pre>
+  parenthesized_args:
+    &quot;(&quot; args &quot;)&quot;</pre>
+<pre>
+  args:
+    arg [ &quot;,&quot; arg ]</pre>
+<pre>
+  arg:
+    [ float_constant
+    | int_constant
+    | string_constant [ &quot;=&gt;&quot; target ]?
+    | target
+    ]
+    set_flags?</pre>
+<pre>
+  arguments:
+    [ &quot;.arg&quot; simple_expr set_flags? nl ]*</pre>
+<pre>
+  result_values:
+    [ &quot;.result&quot; target get_flags? nl ]*</pre>
+<pre>
+  set_flags:
+    [ &quot;:flat&quot;
+    | named_flag
+    ]+</pre>
+<p>
+</p>
+<h3><a name="example_long_subroutine_call">Example long subroutine call</a></h3>
+<p>The long subroutine call syntax is very suitable to be generated by a language compiler
+targeting Parrot. Its syntax is rather verbose, but easy to read. The minimal invocation
+looks like this:</p>
+<pre>
+        .pcc_begin
+        .pcc_call $P0
+        .pcc_end</pre>
+<p>Invoking instance methods is a simple variation:</p>
+<pre>
+        .pcc_begin
+        .invocant $P0
+        .meth_call $P1
+        .pcc_end</pre>
+<p>Passing arguments and retrieving return values is done like this:</p>
+<pre>
+        .pcc_begin
+        .arg 42
+        .pcc_call $P0
+        .local int res
+        .result res
+        .pcc_end</pre>
+<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 &lt;type&gt; &lt;identifier&gt; :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; it uses <code>.nci_call</code> instead of <code>.pcc_call</code>.</p>
+<pre>
+        .pcc_begin
+        .nci_call $P0
+        .pcc_end</pre>
+<p>
+</p>
+<h2><a name="short_subroutine_invocation">Short subroutine invocation</a></h2>
+<pre>
+  short_sub_call:
+    invocant? [ target | string_constant ] parenthesized_args</pre>
+<pre>
+  invocant:
+    [ target&quot;.&quot; | target &quot;-&gt;&quot; ]</pre>
+<p>
+</p>
+<h3><a name="example_short_subroutine_call">Example short subroutine call</a></h3>
+<p>The short subroutine call syntax is useful when manually writing PIR code.
+Its simplest form is:</p>
+<pre>
+        foo()</pre>
+<p>Or a method call:</p>
+<pre>
+        obj.'toString'() # call the method 'toString'
+        obj.x() # call the method whose name is stored in 'x'.</pre>
+<p>IMCC also allows the &quot;-&gt;&quot; instead of a dot, to make it readable for C++ programmers:</p>
+<pre>
+        obj-&gt;'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>
+<pre>
+  return_stat:
+      long_return_stat
+    | short_return_stat
+    | long_yield_stat
+    | short_yield_stat
+    | tail_call</pre>
+<pre>
+  long_return_stat:
+    &quot;.pcc_begin_return&quot; nl
+    return_directive*
+    &quot;.pcc_end_return&quot;</pre>
+<pre>
+  return_directive:
+    &quot;.return&quot; simple_expr set_flags? nl</pre>
+<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 :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>
+<pre>
+  short_return_stat:
+    &quot;.return&quot; parenthesized_args</pre>
+<p>
+</p>
+<h3><a name="example_short_return_statement">Example short return statement</a></h3>
+<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>
+<pre>
+  long_yield_stat:
+    &quot;.pcc_begin_yield&quot; nl
+    return_directive*
+    &quot;.pcc_end_yield&quot;</pre>
+<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
+          .return 42
+          .pcc_end_yield</pre>
+<pre>
+          <span class="comment"># and later in the sub, one could return another value:</span>
+</pre>
+<pre>
+          .pcc_begin_yield
+          .return 43
+          .pcc_end_yield
+        .end</pre>
+<pre>
+        # when invoking twice:
+        foo() # returns 42
+        foo() # returns 43</pre>
+<p>
+</p>
+<h2><a name="short_yield_statements">Short yield statements</a></h2>
+<pre>
+  short_yield_stat:
+    &quot;.yield&quot; parenthesized_args</pre>
+<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(&quot;hello&quot;, 42)</pre>
+<p>
+</p>
+<h2><a name="tail_calls">Tail calls</a></h2>
+<pre>
+  tail_call:
+    &quot;.return&quot; short_sub_call</pre>
+<p>
+</p>
+<h3><a name="example_tail_call">Example tail call</a></h3>
+<pre>
+        .return foo()</pre>
+<p>Returns the return values from <code>foo</code>. This is implemented by a tail call, which is more efficient than:</p>
+<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>
+<pre>
+  open_namespace:
+    &quot;.namespace&quot; identifier</pre>
+<pre>
+  close_namespace:
+    &quot;.endnamespace&quot; identifier</pre>
+<p>
+</p>
+<h3><a name="example_open_close_namespaces">Example open/close namespaces</a></h3>
+<pre>
+        .sub main
+          .local int x
+          x = 42
+          say x
+          .namespace NESTED
+          .local int x
+          x = 43
+          say x
+          .endnamespace NESTED
+          say x
+        .end</pre>
+<p>Will print:</p>
+<pre>
+        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>
+<pre>
+  emit:
+    &quot;.emit&quot; nl
+    labeled_pasm_instr*
+    &quot;.eom&quot;</pre>
+<p>
+</p>
+<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 &quot;This is PASM subroutine &quot;foo&quot;
+           ret
+         .eom</pre>
+<p>
+</p>
+<h2><a name="macros">Macros</a></h2>
+<pre>
+  macro_def:
+    &quot;.macro&quot; identifier macro_parameters? nl
+    macro_body</pre>
+<pre>
+  macro_parameters:
+    &quot;(&quot; id_list? &quot;)&quot;</pre>
+<pre>
+  macro_body:
+    .*?
+    &quot;.endm&quot; nl</pre>
+<pre>
+  macro_invocation:
+    macro_id parenthesized_args?</pre>
+<p>
+</p>
+<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 &quot;.endm&quot; are 'matched'.</p>
+<p>
+</p>
+<h2><a name="pir_pragmas">PIR Pragmas</a></h2>
+<pre>
+  pragma:
+      include
+    | new_operators
+    | loadlib
+    | namespace
+    | hll_mapping
+    | hll_specifier
+    | source_info</pre>
+<pre>
+  include:
+    &quot;.include&quot; string_constant</pre>
+<pre>
+  new_operators:
+    &quot;.pragma&quot; &quot;n_operators&quot; int_constant</pre>
+<pre>
+  loadlib:
+    &quot;.loadlib&quot; string_constant</pre>
+<pre>
+  namespace:
+    &quot;.namespace&quot; [ &quot;[&quot; namespace_id &quot;]&quot; ]?</pre>
+<pre>
+  hll_specifier:
+    &quot;.HLL&quot; string_constant &quot;,&quot; string_constant</pre>
+<pre>
+  hll_mapping:
+    &quot;.HLL_map&quot; int_constant &quot;,&quot; int_constant</pre>
+<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:
+    &quot;.line&quot; int_constant [ &quot;,&quot; string_constant ]?</pre>
+<pre>
+  id_list:
+    identifier [ &quot;,&quot; identifier ]*</pre>
+<p>
+</p>
+<h3><a name="examples_pragmas">Examples pragmas</a></h3>
+<pre>
+        .include &quot;myLib.pir&quot;</pre>
+<p>includes the source from the file &quot;myLib.pir&quot; 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>
+<pre>
+        $P1 = new .Integer
+        $P2 = new .Integer
+        $P1 = 42
+        $P2 = 43
+        $P0 = $P1 * $P2
+        # now, $P0 is automatically assigned a newly created PMC.</pre>
+<pre>
+        .line 100
+        .line 100, &quot;myfile.pir&quot;</pre>
+<p>NOTE: currently, the line directive is implemented in IMCC as #line.
+See the PROPOSALS document for more information on this.</p>
+<pre>
+        <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
+namespaces without doing OO-programming.</p>
+<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 &quot;Lua&quot;, &quot;lua_group&quot;</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 &quot;myLib&quot;</pre>
+<p>is a shortcut for telling Parrot that the library &quot;myLib&quot; should be loaded when running the program. In fact,
+it is a shortcut for:</p>
+<pre>
+        .sub _load :load :anon
+          loadlib &quot;myLib&quot;
+        .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>
+<pre>
+  string_constant:
+    charset_specifier?  quoted_string</pre>
+<pre>
+  charset_specifier:
+      &quot;ascii:&quot;
+    | &quot;binary:&quot;
+    | &quot;unicode:&quot;
+    | &quot;iso-8859-1:&quot;</pre>
+<pre>
+  type:
+      &quot;int&quot;
+    | &quot;num&quot;
+    | &quot;pmc&quot;
+    | &quot;object&quot;
+    | &quot;string&quot;
+    | &quot;Array&quot;
+    | &quot;Hash&quot;</pre>
+<pre>
+  target:
+    identifier | register</pre>
+<p>
+</p>
+<h3><a name="notes_on_tokens__types_and_targets">Notes on Tokens, types and targets</a></h3>
+<p>A string constant can be written like:</p>
+<pre>
+        &quot;Hello world&quot;</pre>
+<p>but if desirable, the character set can be specified:</p>
+<pre>
+        unicode:&quot;Hello world&quot;</pre>
+<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>
+<p>A <code>target</code> is something that can be assigned to, it is an L-value (but of course may be read just like
+an R-value). It is either an identifier or a register.</p>
+<p>
+</p>
+<hr />
+<h1><a name="author">AUTHOR</a></h1>
+<p>Klaas-Jan Stol <a href="mailto:[parrotcode@gmail.com]">[parrotcode@gmail.com]</a></p>
+<p>
+</p>
+<hr />
+<h1><a name="known_issues_and_bugs">KNOWN ISSUES AND BUGS</a></h1>
+<p>Some work should be done on:</p>
+<ul>
+<li>
+<p>Macro parsing</p>
+</li>
+<li>
+<p>Heredoc parsing</p>
+</li>
+<li>
+<p>The rule 'type' does currently not include custom types (user defined).
+Probably it needs an alternative &quot;identifier&quot;. 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 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.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>
+<p>Initial version having a version number.</p>
+</li>
+</ul>
+
+</body>
+
+</html>
Index: languages/PIR/docs/pirgrammar.pod
===================================================================
--- languages/PIR/docs/pirgrammar.pod	(revision 16915)
+++ languages/PIR/docs/pirgrammar.pod	(working copy)
@@ -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,13 +838,24 @@
 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,7 +896,10 @@
 
 	.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
 
   long_yield_stat:
@@ -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
Index: languages/PIR/PROPOSALS
===================================================================
--- languages/PIR/PROPOSALS	(revision 16915)
+++ languages/PIR/PROPOSALS	(working copy)
@@ -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.
+3. :postcomp and :immediate
 	 
-	 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 '$').
+	 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,8 +99,26 @@
 	 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:	 
 	 
 	 
