"Fossies" - the Fresh Open Source Software Archive

Member "RPerl-5.002000/docs/magic_plan.txt" (30 Aug 2019, 5605 Bytes) of package /linux/misc/RPerl-5.002000.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. For more information about "magic_plan.txt" see the Fossies "Dox" file reference documentation.

    1 RPerl Magic Plan
    2 Requirements & Design, Medium-Magic & High-Magic RPerl
    3 Last Updated 20170304 2017.063
    4 
    5 0.  BUSINESS ITEMS:
    6 
    7     0a.  Before work begins, the following assignment agreement must be notarized & fully executed:
    8         https://github.com/wbraswell/rperl/raw/master/ASSIGNMENT.pdf
    9 
   10     0b.  This project is split into 4 phases of roughly equal complexity.
   11 
   12 
   13 1.  PHASE 1, MEDIUM-MAGIC RPERL GRAMMAR
   14 
   15     1a.  Input: Perl 5 Source Code, Medium Magic, Statically Analyzable
   16     1b.  Output: RPerl Abstract Syntax Tree, Medium Magic
   17     1c.  Mechanism: Parse::Eyapp File, In lib/RPerl/GrammarMedium.eyp
   18     1d.  Tests: Parse Only, All Low-Magic RPerl Tests & Subset Of Perl 5 Tests, In lib/RPerl/TestMedium/
   19 
   20 
   21 2.  PHASE 2, MEDIUM-MAGIC C++ GENERATOR
   22 
   23     2a.  Input: RPerl Abstract Syntax Tree, Medium Magic
   24     2b.  Output: C++ Source Code, CPPOPS_CPPTYPES Mode, Statically Compilable Without libperl
   25     2c.  Mechanism: ast_to_cpp__generate__CPPOPS_CPPTYPES_medium() Subroutines, In Existing .pm Files When Possible
   26     2d.  Tests: Parse & Generate, All Low-Magic RPerl Tests & Subset Of Perl 5 Tests, In lib/RPerl/TestMedium/
   27 
   28 
   29 3.  PHASE 3, HIGH-MAGIC RPERL GRAMMAR
   30 
   31     3a.  Input: Perl 5 Source Code, High Magic, All Possible Perl 5 Syntax
   32     3b.  Output: RPerl Abstract Syntax Tree, High Magic
   33     3c.  Mechanism: Parse::Eyapp File, In lib/RPerl/GrammarHigh.eyp
   34     3d.  Tests: Parse Only, All Low-Magic RPerl Tests & All Perl 5 Tests, In lib/RPerl/TestHigh/
   35 
   36 
   37 4.  PHASE 4, HIGH-MAGIC C++ GENERATOR
   38 
   39     4a.  Input: RPerl Abstract Syntax Tree, High Magic
   40     4b.  Output: C++ Source Code, CPPOPS_PERLTYPES Mode, Dynamically Linked To libperl
   41     4c.  Mechanism: ast_to_cpp__generate__CPPOPS_CPPTYPES_high() Subroutines, In Existing & New .pm Files
   42     4d.  Tests: Parse & Generate, All Low-Magic RPerl Tests & All Perl 5 Tests, In lib/RPerl/TestHigh/
   43 
   44 
   45 5.  REQUIREMENTS & DESIGN:
   46 
   47     5a.  No PERLOPS_PERLTYPES C/C++ output code is to be generated by any phase of this project,
   48         with the sole exception of direct calls to the existing Perl 5 regular expression engine;
   49         the regular expression engine is complex and fast enough to be left as-is instead of being rewritten.
   50         (For reference, B::C generates PERLOPS_PERLTYPES C output code; 
   51         RPerl's current data type tests and hand-compiled tests utilize CPPOPS_PERLTYPES C++ output code; and
   52         RPerl's low-magic compiled output generates CPPOPS_CPPTYPES C++ output code.)
   53         
   54 
   55     5b.  The existing low-magic RPerl tests are in the lib/RPerl/Test/ directory.
   56 
   57     5c.  All work is to be done in the perl11/rperl repository on GitHub,
   58         which is itself to be kept up-to-date daily with the master branch of the wbraswell/rperl repository.
   59 
   60     5d.  The C++ generation routines are to be appended to existing RPerl .pm files wherever possible,
   61         and most new .pm files should be created only in phase 4, 
   62         with the exception of operator files in lib/RPerl/Operation/Expression/Operator/ & lib/RPerl/Operation/Statement/OperatorVoid/,
   63         many of which have not yet been created for the low-magic CPPOPS_CPPTYPES mode and must thus be created as we go;
   64         implementation of the low-magic operator code is not part of this project and will be handled separately.
   65 
   66     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.
   67 
   68     5f.  All code written in this project must conform to low-magic RPerl syntax specifications when possible,
   69         so that RPerl will eventually be able to bootstrap and compile itself.
   70 
   71     5g.  Both the medium-magic grammar and high-magic grammar must use Parse::Eyapp, 
   72         and must be based directly on the existing low-magic RPerl grammar contained in lib/RPerl/Grammar.eyp;
   73         the low-magic grammar has already been copied into the file lib/RPerl/GrammarMedium.eyp,
   74         which may now be modified and expanded as appropriate.
   75 
   76     5h.  Instructions for compiling & updating grammar are inside lib/RPerl/GrammarMedium.eyp file,
   77         under the heading "Map from abstract syntax tree to classes"; files involved include 
   78         script/development/grammar_recompile.sh & script/development/grammar_increment.pl & script/development/grammar_decrement.pl;
   79         talk to me before you go through this process, because it will require some updates to not interfere with the low-magic grammar.
   80 
   81     5i.  Upon completion of phase 1, RPerl must correctly parse all parts of Perl 5 
   82         which can be statically analyzed at compile time by Parse::Eyapp & associated subroutines,
   83         and which may be generated into C++ code in CPPOPS_CPPTYPES mode (no dynamic features or use of libperl).
   84 
   85     5j.  Upon completion of phase 2, RPerl must correctly compile & execute all parts of Perl 5 parsed by phase 1.
   86 
   87     5k.  Upon completion of phase 3, RPerl must correctly parse all existing Perl 5 code,
   88         including all existing CPAN modules, all XS code, and any private Perl 5 code available for testing.
   89 
   90     5l.  Upon completion of phase 4, RPerl must correctly compile & execute all existing Perl 5 code, as parsed by phase 3.
   91 
   92     5m.  Upon completion of phase 4, RPerl must be capable of fully replacing any existing Perl 5 compiler,
   93         including any implementation or distribution of the B::C and B::CC compilers.
   94 
   95     5n.  Upon completion of phase 4, RPerl must be capable of fully replacing any existing Perl 5 interpreter,
   96         starting with any implementation or distribution of Perl v5.10.1 through the latest release of Perl v5.26.
   97