Roadmap
=======

The following files may be of interest to someone new to the compiler:

perl6			driver program
ChangeLog		development history, including outstanding
			issues
doc/*			(some) useful documentation
P6C/Addcontext.pm	Context propagation (type checking)
P6C/Builtins.pm		"built-in" function code and prototypes
P6C/Context.pm		evaluation context structure
P6C/IMCC.pm		code generation utilities; generation for
			common types
P6C/IMCC/*.pm		code generation for less common types
P6C/Nodes.pm		parse tree node types
P6C/Parser.pm		the grammar
t/builtins		builtin function tests
t/compiler		compiler tests
t/rx			regex tests
examples/*		simple example programs

Notes
=====

Before you begin, make sure that parrot (../../parrot) is compiled.
Typing "make" in the root directory should do this.

Also, if you have updated from CVS (rather than doing a fresh checkout), you
should remove Perl6grammar.pm to force the compiler to re-compile the grammar
file.

All the compiler test cases pass on my machine (except where noted in
ChangeLog), and compile in less than five seconds each.

Take a look at t/* and examples for an idea of the kinds of operations
currently supported.  For more internal details, see the POD
documentation in P6C/*.pm, especially P6C/Nodes.pm.

Many functions are loaded on demand with SelfLoader, leading to
uninformative error messages like "error in eval 267, line 3".  For
more informative messages, you should comment out the "use SelfLoader"
statement and the "__DATA__" marker in the candidate .pm file.

Overview
========

The compiler currently operates in four passes.  The first (Parser.pm)
takes the source and produces a very raw parse tree.  The second
(Tree.pm) turns this data structure into a more manageable parse tree.
The third pass (Addcontext.pm) figures out context information,
storing it in the parse tree nodes.  The final pass (IMCC.pm) uses
this context to emit IMCC code (higher-level than assembler).

The resulting code is then run through imcc (parrot/languages/imcc), which
handles register allocation and spilling, and then finally assembled
by the parrot assembler (parrot/assembler.pl).

If you want to get started in parser development, you should probably
start by reading doc/overview.pod.  If you're not sure where to go
from there, you can look for "XXX:" in the code, which is used to mark
things that need fixing.  If you're interested in getting involved,
drop Sean an email.

Features
========

While the following is intended to be a fairly comprehensive list of
what is and is not implemented, the only fully accurate documentation
is, of course, the tests and the code.

- control structures

  - control-y functions:
    - while/until
    - for
    - foreach
    - if/unless
    - try
    - given/when
      - NOT full smart-matching (see =~ operator)
    - return
    - next/last/break/redo/skip/continue
    - NOT exception-safe
    - NOT using control exceptions
  - exceptions
    - NOT exception objects
  - anonymous subs
    - NOT closures

- operators

  - smart matching (=~, !~) (see Table 1 in Apocalypse 4)
    - hash/scalar
    - array/regex
    - array/number
    - expr/{regex, number, string}
      - NOT boolean, undef, subst, expr
  - NOT array 'x'
  - NOT lazy ranges
  - NOT s///
  - NOT tr///
  - single and interpolated quotes
    - NOT user-defined quotes
  - simple binary operators
  - hyper operators
    - NOT assignment versions (e.g. "^+=")

- (ir)regular expressions

  - alternation
    - array literal alternation (@array)
  - repetition
    - both greedy and stingy
    - NOT negated
  - scalar literals
  - embedded code
  - '\x' sequences
    - escaped metacharacters
    - NOT "\n"-as-logical-newline
  - <...> assertions
    - <'literal string'>
    - <(code assertion)>
    - call to rules (<$anon_rule>) and (<named_rule>)
    - call arguments
      - <rule:string>
      - <rule(@args)>
      - NOT <rule pattern>
      - character classes (<[blah]>)
	- NOT character-class arithmetic
	- NOT named character classes
    - NOT unicode
  - other assertions
    - ^ and $
    - NOT ^^ and $$
  - cut operators
    - NOT ':::' or '<cut>'
  - NOT modifiers
  - NOT capturing
  - NOT "match result objects"

- builtin functions

  - string
    - substr
    - length
    - index
    - join
  - array
    - reverse
  - I/O
    - print (STDOUT only)
  - miscellaneous
    - warn
    - die
    - exit
    - sleep
    - time


Contributors
============

John Kingsley		Numerous bug fixes to the parser, parser
			tests, parse error messages.

Sean O'Rourke		Initial development.  Primary contact. Bugs.
  seano@cpan.org

Joseph Ryan		Compiler overview doc, builtin functions.

Allison Randal		Conversion to CPS subroutine calling.

Leopold Toetsch		5.005_03 compatibility fixes, test driver
			cleanup, new driver program, many bug fixes.
