=head1 INTRODUCTION

v6.pm hacking how-to

=head1 Links

=over

=item *

The development repository is:
http://svn.openfoundry.org/pugs/perl5/

=item *

The CPAN distribution is:
http://search.cpan.org/dist/v6-alpha/

=item *

The irc channel for development is:
#perl6 on freenode

=back

=head1 #perl6 jargon

=over

=item *

PCR 
-- the Pugs::Compiler::Rule module - implements Perl 6 parser tools: rule, token, regex, P5 regex, and precedence parser.

=item *

PCP6 or v6.pm or v6 or v6-alpha 
-- the perl6-on-perl6 implementation

=item *

lrep 
-- an older version of v6.pm
-- lrep is still used to compile the Rule grammar in the Pugs::Compiler::Rule module.

=back

=head1 v6 Environment variables

=over

=item *

  V6DUMPAST=1  - tells the code emitter to dump the syntax tree to STDOUT before processing

=item *

  PERL6LIB=dir;dir  - same usage as PERL5LIB

=back

=head1 v6 Compilation cycle

  Source file ->
  Parser -> 
  Emitter ->
  Execute

There is currently no intermediate AST processing phase - the match capture is sent directly to the emitter.

=head1 Implementing new syntax

=over

=item 1.

set the V6DUMPAST environment variable 

=item 2.

try a simple test with the new syntax:

  perl -Ilib lib/v6.pm --compile-only ' say 42 '

=item 3.

if the syntax tree looks ok, the new syntax can be implemented in the emitter file - see the Emitter section below.

=item 4.

in order to implement of fix syntax tree nodes, see the Parsing section for choosing which file to edit.

=back

=head1 Source file processors

=over

=item *

lib/v6.pm

=item *

provides compatibility with other perl 6 implementations, by implementing "use v6-alpha;"

=item *

provides pre-compilation through Module::Compile

=item *

the compiled code is post-processed with Perl::Tidy, if it is available.

=item *

lib/Pugs/Compiler/Perl6

subclasses Pugs::Compiler::Rule to implement the "perl 6 compiler"

=back

=head1 Parsing

The syntax is mostly implemented using perl 6 rules, which are provided by the Pugs::Compiler::Rule module.

A few "terms" are implemented using perl 5 modules, such as Pugs::Grammar::Precedence (called from Expression.pm), and Text::Balanced (called from Term.pm)

lib/Pugs/Grammar/*

=over

=item *

Perl6.pm

=over

=item *

statements

=back

=item *

Term.pm

=over

=item *

number, string, :a<b>

=back

=item *

Expression.pm 

=over

=item *

detects end-of-expresion

=item *

parses some terms, like method calls

=back

=item *

Operator, BaseCategory.pm

=over

=item *

Infrastructure for operator tables

=back

=item *

Infix, Prefix, Postfix, Postcircumfix, Circumfix, Ternary

=over

=item *

operator tables; most of the work is done by Pugs::Grammar::Precedence

=back

=item *

P6Rule.pm

=back

=over

=item *

parser for rules (almost a duplicate of the one in Pugs::Runtime::Rule)

=item *

StatementControl.pm and Pod.pm are currently not used

=back

=head1 Code Emitter

lib/Pugs/Emitter/Perl6/Perl5.pm

=over

=item *

gets a syntax tree and generates Perl5 code

=back

=head1 Execute (Runtime)

lib/Pugs/Runtime/Perl6.pm

=over

=item *

provides routines and objects that help emulate perl 6 semantics.

=back

lib/Pugs/Runtime/Perl6Prelude.pm

=over

=item *

provides runtime routines that can be written in Perl 6

=back

=head1 Writing new tests 

For consistency, we share tests with the Haskell implementation.  Instead of
duplicating the tests in our tree, we copy the tests over when "perl
Makefile.PL" is run. This is done by analyzing the MANIFEST to decide which
files to copy. 

The exceptions are when we need to modify a test script to be different,
perhaps because the feature needs to be marked TODO in this implementation
but not the other. 

As of 07/09/06, this test suite is still in transition to this model.  

=head1 COPYRIGHT

Copyright 2006 by Flavio Soibelmann Glock and others.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.

See L<http://www.perl.com/perl/misc/Artistic.html>

=cut