=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