# RPerl Developer Notes 20150707 2015.188

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

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


##########################################################################################
# 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 INSTALL notes file, Step 1B

# do NOT mix local::lib with Perlbrew
# disable ~/.bashrc 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 use 5.xx.yy
# `perl script/rperl` instead of just `rperl` to 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 .


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

https://rt.cpan.org


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

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


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

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


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

https://pause.perl.org


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

# Makefile.PL uses ExtUtils::MakeMaker
$ vi Changes
	# version, date, name, notes
$ vi lib/RPerl.pm
    # $VERSION
$ vi script/rperl
    # $VERSION
    # -v option
$ 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
$ rm RPerl*.tar.gz; rm MANIFEST
$ perl Makefile.PL; make manifest
    # review MANIFEST contents
$ vi MANIFEST.SKIP
    # update with new files to exclude from CPAN
    # correlated with Makefile.PL & .gitignore
$ make manifest
    # review MANIFEST contents again
$ 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 #16: 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
$ 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
$ 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 RPerl-VERSION.tar.gz
	# ARE YOU SURE YOU WISH TO PROCEED?!?
$ cpan-upload -v -u WBRASWELL RPerl-VERSION.tar.gz
$ script/development/rperl_locallib_uninstall.sh
$ cpanm WBRASWELL/RPerl-VERSION.tar.gz  # beta pre-release versions
# OR
$ cpanm RPerl  # full release versions
