# RPerl Developer Notes 20160115 2016.015

##########################################################################################
# WARNING & ERROR CODES
##########################################################################################

GENERAL CODE LEGEND

W: Warning
E: Error

CV: Code Value
PV: Pointer Value (String)
IV: Integer Value
NV: Number Value (Float)
RV: Reference Value

PA: Parse
IN: Interpret
CO: Compile
EX: Execute
AL: Algorithm

PL: Perl Interpreter
PC: Perl::Critic Analyzer
RP: RPerl Compiler

SO: Sort
BU: Bubble
[NEED ADD MANY MORE HERE]

SPECIFIC CODES

ERROR ECOGEASRP00, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: grammar rule [SOMERULE] found where [SOMERULES] expected, dying
ERROR ECOGEASRP01, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named void operator [SOMEOP] found where [SOMEOPS] expected, dying
ERROR ECOGEASRP02, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Argument count [SOMECOUNT] falls below minimum argument limit [SOMEMIN] for operation [SOMEOP], dying
ERROR ECOGEASRP03, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Argument count [SOMECOUNT] exceeds maximum argument limit [SOMEMAX] for operation [SOMEOP], dying
ERROR ECOGEASRP04, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Attempt to return dereferenced array, please return arrayref instead, dying
ERROR ECOGEASRP05, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Attempt to return dereferenced hash, please return hashref instead, dying
ERROR ECOGEASRP06, CODE GENERATOR, ABSTRACT SYNTAX TO RPerl: C-style for() loop header variable mismatch, initial-condition variable [SOMEVAR] is different than exit-condition variable [SOMEOTHERVAR], dying
ERROR ECOGEASRP07, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: package name [SOMEPACKAGE] must not start with underscore, dying
ERROR ECOGEASRP08, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: subroutine name [SOMESUB] must not start with underscore, dying
ERROR ECOGEASRP09, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: method name [SOMEMETHOD] must not start with underscore, dying
ERROR ECOGEASRP10, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: [NONE]
ERROR ECOGEASRP11, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: [NONE]
ERROR ECOGEASRP12, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named operator [SOMEOP] found where [SOMEOPS] expected, operator may not be properly listed in $RPerl::Operation::Expression::Operator::Named::NAMES, dying
ERROR ECOGEASRP13, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: named operator [SOMEOP] does not accept multiple arguments, dying
ERROR ECOGEASRP14, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: named operator [SOMEOP] does not accept arguments, dying
ERROR ECOGEASRP15, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: named operator [SOMEOP] requires exactly one argument, dying
ERROR ECOGEASRP16, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: named operator [SOMEOP] requires one or more arguments, dying
ERROR ECOGEASRP17, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: named operator [SOMEOP] requires multiple arguments, dying
ERROR ECOGEASRP18, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named operator [SOMEOP] found where [SOMEOPS] expected, dying
ERROR ECOGEASRP19, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: data type mismatch, [SOMETYPE] type is different than [SOMEOTHERTYPE] constructor type, dying
ERROR ECOGEASRP20, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: redundant name mismatch, inner type name [SOMENAME] does not equal OO properties or hash key [SOMEKEY], dying
ERROR ECOGEASRP21, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: redundant name mismatch, inner type name [SOMENAME] does not end with OO properties or hash key [SOMEKEY], dying
[NEED ADD MANY MORE HERE]

##########################################################################################
# PERLTIDY 
##########################################################################################

$ mv /usr/share/perl5/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm \
    /usr/share/perl5/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm.orig
$ ln -s PATH_TO_RPERL/lib/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm \
    /usr/share/perl5/Perl/Critic/Policy/CodeLayout/RequireTidyCode.pm

# MUST HAVE Perltidy v20121207 OR LATER
# All RPerl code is run through Perl::Tidy configured for Perl Best Practices
$ perltidy -pbp --ignore-side-comment-lengths --converge -l=160


##########################################################################################
# PERLCRITIC
##########################################################################################

# MUST HAVE Perl-Critic v1.120 OR LATER
# All RPerl code is run through Perl::Critic severity level 1 (brutal)
$ perlcritic --brutal

# Perl::Critic & Eclipse EPIC Integration Fix
$ cd PATH_TO_CRITIC
$ mv perlcritic perlcritic.old
$ ln -s PATH_TO_RPERL_GITHUB/script/3rd_party_debugging/perlcritic ./perlcritic
# Eclipse -> Window -> Preferences -> Perl EPIC -> Perl::Critic -> Custom Location
# PATH_TO_LAMPUNIVERSITY_GITHUB/bin/perlcritic_eclipse.sh


##########################################################################################
# PERLBREW
##########################################################################################

# see RPerl INSTALL notes file, Step 1B

# do NOT mix local::lib with Perlbrew
$ rm ~/perl5
$ ln -s ~/perl5-perlbrew-5.12.5/ ~/perl5
$ unset PERL5LIB
$ vi ~/.bashrc
    # disable local::lib code
        #if [ -d $HOME/perl5/lib/perl5 ]; then 
        #    eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)
        #fi
    # enable ~/.bashrc Perlbrew code
        source ~/perl5/perlbrew/etc/bashrc
$ source ~/.bashrc
$ perlbrew list
$ perlbrew use 5.xx.yy
$ export PERL5LIB=$PERL5LIB:/home/SOMEUSER/perl5/perlbrew/perls/perl-SOMEVERSION/lib/site_perl/SOMEVERSION/SOMEARCH
$ perl script/rperl -t Foo.pm  # force use of Perlbrew perl


##########################################################################################
# PERLALL
##########################################################################################

# NEED CONTENT


##########################################################################################
# REGULAR EXPRESSIONS 
##########################################################################################

From http://perldoc.perl.org/perlre.html

/m
Treat string as multiple lines. That is, change "^" and "$" from matching the start of the string's first line and the end of its last line to matching the start and end of each line within the string.

/s
Treat string as single line. That is, change "." to match any character whatsoever, even a newline, which normally it would not match.

Used together, as /ms, they let the "." match any character whatsoever, while still allowing "^" and "$" to match, respectively, just after and just before newlines within the string.

/x
/x tells the regular expression parser to ignore most whitespace that is neither backslashed nor within a bracketed character class. You can use this to break up your regular expression into (slightly) more readable parts. Also, the # character is treated as a metacharacter introducing a comment that runs up to the pattern's closing delimiter, or to the end of the current line if the pattern extends onto the next line. Hence, this is very much like an ordinary Perl code comment. (You can include the closing delimiter within the comment only if you precede it with a backslash, so be careful!)
Use of /x means that if you want real whitespace or # characters in the pattern (outside a bracketed character class, which is unaffected by /x), then you'll either have to escape them (using backslashes or \Q...\E ) or encode them using octal, hex, or \N{} escapes. It is ineffective to try to continue a comment onto the next line by escaping the \n with a backslash or \Q .

VIM ONLY, DON'T USE IN ECLIPSE; Grammar.eyp to Learning.pm

replace 'foo->bar23() < 42' with C<foo-E<gt>bar23() E<lt> 42> from lines 3310 to 3510
:3310,3510s/'\([^<]\{-}\)<<\([^<]\{-}\)'/'\1E<ltE<lt\2'/g
:3310,3510s/'\([^<]\{-}\)<\([^<]\{-}\)'/'\1E<lt\2'/g
:3310,3510s/'\([^>]\{-}\)>>\([^>]\{-}\)'/'\1E<gt>E<gt>\2'/g
:3310,3510s/'\([^>]\{-}\)>\([^>]\{-}\)'/'\1E<gt>\2'/g
:3310,3510s/E<lt/E<lt>/g
:3310,3510s/'\([^']\{-}\)'/C<\1>/g


##########################################################################################
# CPAN & METACPAN
##########################################################################################

http://search.cpan.org/~wbraswell/
https://metacpan.org/author/WBRASWELL


##########################################################################################
# CPAN REQUEST TRACKER (BUG REPORTS)
##########################################################################################

https://rt.cpan.org


##########################################################################################
# CPAN TESTERS
##########################################################################################

http://www.cpantesters.org/distro/R/RPerl.html
http://www.cpantesters.org/author/W/WBRASWELL.html

https://admin.cpantesters.org/cgi-bin/pages.cgi?act=user-author
https://admin.cpantesters.org/cgi-bin/pages.cgi?act=author-dist&dist=RPerl


##########################################################################################
# CPANTS KWALITEE
##########################################################################################

http://cpants.cpanauthors.org/dist/RPerl


##########################################################################################
# CPAN PAUSE
##########################################################################################

https://pause.perl.org


##########################################################################################
# CPAN DISTRIBUTION
##########################################################################################

# DEV NOTE: Makefile.PL uses ExtUtils::MakeMaker to interface with PAUSE & CPAN

# UPDATE VERSION NUMBERS
$ vi Changes
	# version, date, name, notes
$ vi lib/RPerl.pm
    # $VERSION
$ vi script/rperl
    # $VERSION
    # -v option

# CLEAN & UNINSTALL PREVIOUS DIST
$ rm -Rf ~/perl5; curl -L cpanmin.us | perl - -l $HOME/perl5 App::cpanminus local::lib
    # optionally create clean ~/perl5 for local::lib single-user installation
    # remember to re-enable Perl::Critic & Eclipse EPIC Integration Fix above
#OR
$ script/development/rperl_locallib_uninstall.sh
	# optionally keep ~/perl5 from previous local::lib single-user installation
	# selectively delete only RPerl files from ~/perl5
$ perl Makefile.PL; make distclean
$ perl Makefile.PL; make realclean
$ rm RPerl*.tar.gz; rm MANIFEST

# MAKE MANIFEST & DIST
$ perl Makefile.PL; make manifest
$ less MANIFEST
$ vi MANIFEST.SKIP
    # update with new files to exclude from CPAN
    # correlated with Makefile.PL & .gitignore
$ make manifest
$ less MANIFEST
$ cpanm --installdeps .; make disttest
	# optionally install deps and test before creating tarball
$ make dist
    # produces tarball output
$ mv ./RPerl-VERSION.tar.gz ./RPerl-VERSION_BETAVERSION.tar.gz
	# DEV NOTE, CORRELATION #rp23: must preserve six numeric digits after the decimal point in the file name
	# DEV NOTE, CORRELATION #rp16: must manually rename beta releases only to include underscore in version number,
	# moving from RPerl's underscore-is-comma numbering scheme (underscores and zeros now hidden) 
	# to CPAN's underscore-is-beta (underscores and zeros now shown) numbering scheme;
$ vi MYMETA.json
	"version" : "1.XXXXXX",
	# DEV NOTE, CORRELATION #rp23: must preserve six numeric digits after the decimal point in the file name

# INSTALL & TEST DIST, LOCAL COPY
$ cpanm ./RPerl-VERSION.tar.gz
    # install from local tarball, ensure tests run & installation is successful
$ which rperl
$ perl -e 'use RPerl;'
	# SEE INSTALL NOTES FOR ADDITIONAL TEST COMMANDS

# UPLOAD TO GITHUB & CPAN
$ mv RPerl*.tar.gz backup/
$ git add -A
$ git commit -a
	# CPAN Release, vX.Y00000; Codename FOO, BAR Edition
$ git push origin master
$ apt-get install libssl-dev
	# to avoid 'fatal error: openssl/err.h: No such file or directory' during install of Net::SSLeay, subdep of CPAN::Uploader
$ cpanm CPAN::Uploader
$ cpan-upload -v -u WBRASWELL --dry-run backup/RPerl-VERSION.tar.gz
	# ARE YOU SURE YOU WISH TO PROCEED?!?
$ cpan-upload -v -u WBRASWELL backup/RPerl-VERSION.tar.gz

# INSTALL & TEST DIST, DOWNLOAD COPY
$ script/development/rperl_locallib_uninstall.sh
$ cpanm WBRASWELL/RPerl-VERSION.tar.gz  # beta pre-release versions
# OR
$ cpanm RPerl  # full release versions
