RPerl Magic Plan
Requirements & Design, Medium-Magic & High-Magic RPerl
Last Updated 20170304 2017.063

0.  BUSINESS ITEMS:

    0a.  Before work begins, the following assignment agreement must be notarized & fully executed:
        https://github.com/wbraswell/rperl/raw/master/ASSIGNMENT.pdf

    0b.  This project is split into 4 phases of roughly equal complexity.


1.  PHASE 1, MEDIUM-MAGIC RPERL GRAMMAR

    1a.  Input: Perl 5 Source Code, Medium Magic, Statically Analyzable
    1b.  Output: RPerl Abstract Syntax Tree, Medium Magic
    1c.  Mechanism: Parse::Eyapp File, In lib/RPerl/GrammarMedium.eyp
    1d.  Tests: Parse Only, All Low-Magic RPerl Tests & Subset Of Perl 5 Tests, In lib/RPerl/TestMedium/


2.  PHASE 2, MEDIUM-MAGIC C++ GENERATOR

    2a.  Input: RPerl Abstract Syntax Tree, Medium Magic
    2b.  Output: C++ Source Code, CPPOPS_CPPTYPES Mode, Statically Compilable Without libperl
    2c.  Mechanism: ast_to_cpp__generate__CPPOPS_CPPTYPES_medium() Subroutines, In Existing .pm Files When Possible
    2d.  Tests: Parse & Generate, All Low-Magic RPerl Tests & Subset Of Perl 5 Tests, In lib/RPerl/TestMedium/


3.  PHASE 3, HIGH-MAGIC RPERL GRAMMAR

    3a.  Input: Perl 5 Source Code, High Magic, All Possible Perl 5 Syntax
    3b.  Output: RPerl Abstract Syntax Tree, High Magic
    3c.  Mechanism: Parse::Eyapp File, In lib/RPerl/GrammarHigh.eyp
    3d.  Tests: Parse Only, All Low-Magic RPerl Tests & All Perl 5 Tests, In lib/RPerl/TestHigh/


4.  PHASE 4, HIGH-MAGIC C++ GENERATOR

    4a.  Input: RPerl Abstract Syntax Tree, High Magic
    4b.  Output: C++ Source Code, CPPOPS_PERLTYPES Mode, Dynamically Linked To libperl
    4c.  Mechanism: ast_to_cpp__generate__CPPOPS_CPPTYPES_high() Subroutines, In Existing & New .pm Files
    4d.  Tests: Parse & Generate, All Low-Magic RPerl Tests & All Perl 5 Tests, In lib/RPerl/TestHigh/


5.  REQUIREMENTS & DESIGN:

    5a.  No PERLOPS_PERLTYPES C/C++ output code is to be generated by any phase of this project,
        with the sole exception of direct calls to the existing Perl 5 regular expression engine;
        the regular expression engine is complex and fast enough to be left as-is instead of being rewritten.
        (For reference, B::C generates PERLOPS_PERLTYPES C output code; 
        RPerl's current data type tests and hand-compiled tests utilize CPPOPS_PERLTYPES C++ output code; and
        RPerl's low-magic compiled output generates CPPOPS_CPPTYPES C++ output code.)
        

    5b.  The existing low-magic RPerl tests are in the lib/RPerl/Test/ directory.

    5c.  All work is to be done in the perl11/rperl repository on GitHub,
        which is itself to be kept up-to-date daily with the master branch of the wbraswell/rperl repository.

    5d.  The C++ generation routines are to be appended to existing RPerl .pm files wherever possible,
        and most new .pm files should be created only in phase 4, 
        with the exception of operator files in lib/RPerl/Operation/Expression/Operator/ & lib/RPerl/Operation/Statement/OperatorVoid/,
        many of which have not yet been created for the low-magic CPPOPS_CPPTYPES mode and must thus be created as we go;
        implementation of the low-magic operator code is not part of this project and will be handled separately.

    5e.  Talk to me before creating any new .pm files, because it is quite likely that a .pm file already exists to hold your new code.

    5f.  All code written in this project must conform to low-magic RPerl syntax specifications when possible,
        so that RPerl will eventually be able to bootstrap and compile itself.

    5g.  Both the medium-magic grammar and high-magic grammar must use Parse::Eyapp, 
        and must be based directly on the existing low-magic RPerl grammar contained in lib/RPerl/Grammar.eyp;
        the low-magic grammar has already been copied into the file lib/RPerl/GrammarMedium.eyp,
        which may now be modified and expanded as appropriate.

    5h.  Instructions for compiling & updating grammar are inside lib/RPerl/GrammarMedium.eyp file,
        under the heading "Map from abstract syntax tree to classes"; files involved include 
        script/development/grammar_recompile.sh & script/development/grammar_increment.pl & script/development/grammar_decrement.pl;
        talk to me before you go through this process, because it will require some updates to not interfere with the low-magic grammar.

    5i.  Upon completion of phase 1, RPerl must correctly parse all parts of Perl 5 
        which can be statically analyzed at compile time by Parse::Eyapp & associated subroutines,
        and which may be generated into C++ code in CPPOPS_CPPTYPES mode (no dynamic features or use of libperl).

    5j.  Upon completion of phase 2, RPerl must correctly compile & execute all parts of Perl 5 parsed by phase 1.

    5k.  Upon completion of phase 3, RPerl must correctly parse all existing Perl 5 code,
        including all existing CPAN modules, all XS code, and any private Perl 5 code available for testing.

    5l.  Upon completion of phase 4, RPerl must correctly compile & execute all existing Perl 5 code, as parsed by phase 3.

    5m.  Upon completion of phase 4, RPerl must be capable of fully replacing any existing Perl 5 compiler,
        including any implementation or distribution of the B::C and B::CC compilers.

    5n.  Upon completion of phase 4, RPerl must be capable of fully replacing any existing Perl 5 interpreter,
        starting with any implementation or distribution of Perl v5.10.1 through the latest release of Perl v5.26.