Author: kjs
Date: Mon Mar 12 14:49:15 2007
New Revision: 17452
Added:
trunk/languages/PIR/docs/PROPOSALS
trunk/languages/PIR/docs/ROADMAP.pod
trunk/languages/PIR/docs/TODO.pod
Removed:
trunk/languages/PIR/PROPOSALS
trunk/languages/PIR/ROADMAP.pod
trunk/languages/PIR/TODO
Modified:
trunk/languages/PIR/docs/pirgrammar.pod
Log:
languages/PIR
* Moved some files to docs directory
* updated docs/pirgrammar.pod
* todo file is now in pod format (and updates to this file)
Added: trunk/languages/PIR/docs/PROPOSALS
==============================================================================
--- (empty file)
+++ trunk/languages/PIR/docs/PROPOSALS Mon Mar 12 14:49:15 2007
@@ -0,0 +1,220 @@
+PROPOSALS FOR PIR GRAMMAR
+-------------------------
+
+This document lists peculiarities of the current PIR implementation
+in IMCC while implementing it using PGE.
+IMHO, it'd be nice to clean up some of these before the 1.0 release
+of Parrot, in order to prevend 'backward compatibilty' features.
+
+Also, I propose some extensions to PIR, which may or may not
+be accepted. These new features are prefixed with "NEW:".
+The rationale for them is included. The proposals for the extensions
+have an ID starting at 100, so they can be listed together, separate
+from the clean-up proposals.
+
+This document is intended to start discussion of the listed
+features. That way, the grammar of PIR can be cleaned up and
+made more user-friendly.
+
+Please note that these are just *proposals*, not an attempt to
+extend PIR with non-features.
+
+
+
+1. ".emit/.eom" directives to put PASM instructions in PIR files.
+ Do we still need these? What use-case do they have? If any,
+ can't they use .sub <id> :anon :load or whatever?
+
+ Proposal: remove them.
+
+2. The optional comma between sub pragmas.
+ Sub definitions allow for pragmas after the sub id, like so:
+
+ .sub main :main :load :init
+ .end
+
+ However, the pragmas *may* be separated by a comma, like so:
+
+ .sub main :main, :load, :init
+ .end
+
+ Proposal: remove the optional comma from the grammar. Parameter
+ flags are not separated by commas neither, so it would look more
+ consistent. An optional comma is kinda strange; either demand it,
+ or not.
+
+3. :postcomp and :immediate
+
+ According to the documentation, both flags indicate the same
+ behaviour. This is both unnecessary and unclear to new users.
+
+ Proposal: deprecate one of these flags and remove it afterwards.
+
+4. Macro parameter list.
+
+ Macro definitions may have parameters. However, if they don't take
+ parameters, the parentheses are optional. So either of these examples
+ are allowed:
+
+ # 1
+ .macro doIt
+ .endm
+
+ # 2
+ .macro doIt()
+ .endm
+
+ Currently, IMCC differentiates between these 2: if the macro was
+ declared like #1, then it needs to be called *without* parentheses
+ (which is, arguably, consistent). However, if it's defined like #2,
+ then the empty parentheses are needed in the macro 'invocation' (i.e.
+ expansion).
+
+ Proposal: Always demand parentheses. This way, macro expansions always
+ have parentheses, even if there are no parameters. This looks more
+ uniform than having both forms in the PIR source code.
+
+
+5. .pcc_sub vs .sub
+
+ What's the difference? Are both directives needed? Are there clear
+ advantages to have both?
+
+ Proposal: remove '.pcc_sub', and stick to '.sub'
+
+6. Disallow .pcc_begin_yield + .pcc_end_return
+
+ Currently, IMCC allows:
+
+ .pcc_begin_yield
+ .return 1
+ .pcc_end_return
+
+ It would be more consistent to demand '.pcc_begin_yield' to match
'.pcc_end_yield'.
+
+7. Change #line into .line
+
+ IMHO, it would be nicer to have the #line directive spelled as
".line". This way,
+ it's more clear it's not a comment but rather a directive saying to
the assembler
+ 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.
+
+
+
+
+NEW FEATURE PROPOSALS GO HERE:
+
+
+100. NEW: Allow nested subs.
+
+ With the reimplementation of PIR in PGE it'd be *very* easy to allow
+ for nested subs. This would prevent the need for the :outer() flag,
+ and would make code generation for *many* languages targeting Parrot
+ much easier.
+
+ So, instead of:
+
+ sub foo {
+ sub bar {
+ }
+ }
+
+ to translate to:
+
+ .sub foo
+ .end
+
+ .sub bar :outer('foo')
+ .end
+
+ have it translate to:
+
+ .sub foo
+ .sub bar
+ .end
+ .end
+
+101. NEW: Allow for ".class" directive.
+
+ Sometimes, you just want to have some class defined in the HLL source
+ to be just there, when the code starts running. Currently, this can be
+ solved like:
+
+ .sub _create_classes :anon :load :init
+ $P0 = newclass "MyClass"
+ addattribute $P0, "x"
+ .end
+
+ .namespace ["MyClass"]
+
+ .sub sayHello :method
+ print "Hello"
+ .end
+
+ This feature is so common, why not have a .class/.end pair for this?
It would
+ make code generation for languages a bit easier, I think.
+
+ This would allow for writing:
+
+ .class MyClass
+ .attribute x
+
+ # .sub could be used to specify a "Class method" (i.e.
static method in Java)
+ # or, maybe, allow for ".method sayHello :static" or
":class" to
+ # indicate class methods. Or, just use the ".sub <id>
:method" syntax.
+ .method sayHello
+ print "Hello"
+ .end
+
+ .end
+
+ Of course, as classes may be nested in several namespaces, the
use of the .namespace
+ directive may still be needed, like:
+
+ .namespace ['PIR';'Grammar']
+
+ could become:
+
+ .namespace ['PIR']
+
+ .class Grammar
+ .end
+
+ This feature could easily be built "on top" of PIR, i.e. just
have it translated to the
+ current scheme. (using an anonymous :load/:init sub creating
the class).
+
+
+
+102. NEW: Allow for .try/.catch blocks
+
+ Instead of writing:
+
+ ...
+ push_eh on_error
+ # do some scary stuff
+ clear_eh
+ goto after_handler
+on_error:
+ # exception handling
+ .local pmc Exc
+ .get_results "()", Exc # get the exception object.
+after_handler:
+ ...
+
+ One could have the labels stuff generated by PIR:
+
+ .try # no need for some label, it's done for you!
+ # do some scary stuff
+ .catch Exc # some id for the exception object
+ # exception handling
+ .end
+
+ Not only is the programmer freed of handling the labels, it
+ just looks neater and cleaner!
+
+
+103. NEW: '.yield' instead of '.return' in '.pcc_begin_yield/.pcc_end_yield'
+
+ Currently, IMCC demands '.return' directives in a
.pcc_begin_yield/.pcc_end_yield
+ block. It might be more clear to introduce a '.yield'
directive, to make it
+ very clear that it's a yield, not a plain return.
\ No newline at end of file
Added: trunk/languages/PIR/docs/ROADMAP.pod
==============================================================================
--- (empty file)
+++ trunk/languages/PIR/docs/ROADMAP.pod Mon Mar 12 14:49:15 2007
@@ -0,0 +1,78 @@
+# $Id: ROADMAP.pod 17096 2007-02-20 20:20:48Z paultcochrane $
+
+=head1 Title
+
+Roadmap for languages/PIR
+
+=head1 Intro
+
+This document describes a roadmap for languages/PIR, the PIR
+implementation using the Parrot Compiler Tools: PGE and TGE.
+
+This document does NOT describe IMCC, the current implementation
+of Parrot Intermediate Representation (PIR) used by Parrot.
+
+Neither does this document describe a TODO list; you can find
+that list in the, you guess it, TODO file.
+
+=head1 What's the goal of languages/PIR?
+
+The goal is to have a PIR implementation in PIR itself :-)
+
+Just like most C compilers are implemented in C, it'd be nice to
+define PIR in PIR itself. Moreover, this is a good test-case of the
+Parrot Compiler Tools Suite (PCTS), consisting of PGE (for parsers) and TGE
+(for tree transformations).
+
+Besides PIR, Perl6 and a number of other languages is being implemented
+using the PCTS.
+
+Another, secondary, goal is to *define* PIR; there is not yet a
+final description that precisely states the grammar of PIR. (The
+Yacc input file is big and hard to read). This also gives the opportunity
+to clean up the grammar, and present a nice and clean grammar for
+Parrot 1.0.
+
+
+=head1 Where is languages/PIR now?
+
+Currently, work is being done on the PIR parser. The parser is being
+implemented using the Parrot Grammar Engine (PGE), that implements
+the subsystem of Parrot that will process Perl6 regex-es and rules.
+
+
+=head1 Where is languages/PIR going?
+
+As soon as the parser is done, there should be a simple processing
+pass that reads the parse-tree and emits PIR instructions. That's right,
+it will be a PIR->PIR compiler. This works, because currently PIR
+is already implemented by IMCC, using Lex and Yacc.
+
+Then after that, *and* if there is an API to emit bytecode, (or at least
+a way to call into Parrot to do the stuff it's supposed to do), the
+Real Parrot Bytecode can be emitted, so that IMCC can be skipped altogether.
+
+
+
+=head1 What main tasks need to be done?
+
+This is only a top-level view (a.k.a. ROADMAP), for a detailed list, see TODO.
+
+=over 4
+
+=item Finish and TEST the parser
+
+=item Implement a first back-end: emit PIR
+
+=item Implement a second back-end: call the bytecode API
+
+=back
+
+
+=head1 Author
+
+Klaas-Jan Stol <[EMAIL PROTECTED]>
+
+January 2007
+
+=cut
Added: trunk/languages/PIR/docs/TODO.pod
==============================================================================
--- (empty file)
+++ trunk/languages/PIR/docs/TODO.pod Mon Mar 12 14:49:15 2007
@@ -0,0 +1,43 @@
+
+=head1 NAME
+
+TODO.pod - A ToDo list for PIR language using Parrot Compiler Tools
+
+=head1 DESCRIPTION
+
+Languages/PIR is an attempt to implement a compiler for Parrot Intermediate
+Representation (PIR). This is B<not> the reference implementation of PIR,
+which is compilers/IMCC. Languages/PIR does try to be as close as possible.
+
+=head1 TODO LIST
+
+=over 4
+
+=item *
+
+Add more tests.
+
+=item *
+
+Add support for Heredoc parsing. Not complete yet.
+
+=item *
+
+Fix Parrot instruction parsing (arguments)
+
+=item *
+
+Use <% .. > construct for Parrot instructions as soon as PGE supports it.
+This will hugely improve compilation speed of larger scripts (now it has
+to check each alternative until it matches an instruction).
+
+=back
+
+=head1 AUTHOR
+
+Klaas-Jan Stol
+
+=cut
+
+
+
Modified: trunk/languages/PIR/docs/pirgrammar.pod
==============================================================================
--- trunk/languages/PIR/docs/pirgrammar.pod (original)
+++ trunk/languages/PIR/docs/pirgrammar.pod Mon Mar 12 14:49:15 2007
@@ -25,7 +25,7 @@
=head1 VERSION
-0.1.3
+0.1.4
=head1 LEXICAL CONVENTIONS
@@ -123,7 +123,7 @@
global_def
| sub_def
| const_def
- | macro_def
+ | expansion
| pragma
| emit
@@ -578,50 +578,20 @@
=head2 Operators
relational_op:
- "=="
- | "!="
- | "<="
- | "<"
- | <"="
- | <""
+ "==" | "!=" | "<=" | "<" | <"=" | <""
binary_op:
- "+"
- | "-"
- | "/"
- | "**"
- | "*"
- | "%"
- | "<<"
- | <">>"
- | <">"
- | "&&"
- | "||"
- | "~~"
- | "|"
- | "&"
- | "~"
- | "."
-
+ "+" | "-" | "/" | "**"
+ | "*" | "%" | "<<" | <">>"
+ | <">" | "&&" | "||" | "~~"
+ | "|" | "&" | "~" | "."
assign_op:
- "+="
- | "-="
- | "/="
- | "%="
- | "*="
- | ".="
- | "&="
- | "|="
- | "~="
- | "<<="
- | <">="
- | <">>="
+ "+=" | "-=" | "/=" | "%=" | "*=" | ".="
+ | "&=" | "|=" | "~=" | "<<=" | <">=" | <">>="
unary_op:
- "!"
- | "-"
- | "~"
+ "!" | "-" | "~"
=head2 Expressions
@@ -766,7 +736,7 @@
foo(<<'STR1', <<'STR2')
- argument 1
+ argument 1
STR1
argument 2
STR2
@@ -1113,6 +1083,22 @@
ret
.eom
+=head2 Expansions
+
+ expansion:
+ macro_def
+ | include
+ | pasm_constant
+
+
+ include:
+ ".include" string_constant
+
+ pasm_constant:
+ ".constant" identifier [ constant_value | register ]
+
+
+
=head2 Macros
macro_def:
@@ -1159,18 +1145,13 @@
=head2 PIR Pragmas
pragma:
- include
- | new_operators
+ new_operators
| loadlib
| namespace
| hll_mapping
| hll_specifier
| source_info
-
- include:
- ".include" string_constant
-
new_operators:
".pragma" "n_operators" int_constant
@@ -1365,6 +1346,21 @@
=head1 CHANGES
+0.1.4
+
+=over 4
+
+=item *
+
+Added C<expansion> rule, moved C<include> and C<macro_def> rules to that rule.
+Added C<pasm_constant> definition.
+
+=item *
+
+Removed newlines in operator definition to save some lines for readability.
+
+=back
+
0.1.3
=over 4
