# RPerl Developer Notes 20170112 2017.012

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

GENERAL SYSTEM CODE LEGEND

problem type
W: Warning
E: Error

data type
BV: Boolean Value
UV: Unsigned integer Value
IV: Integer Value
MV: gMp Integer Value
NV: Number Value
TV: characTer Value
PV: Pointer Value (string)
AV: Array Value
HV: Hash Value
HE: Hash Entry
RV: Reference Value
CV: Code Value [unused]
GV: Glob Value [unused]
CO: Code

phase
IN: Interpret
UN: Uncompile
CO: Compile
AR: Arguments
DE: Dependencies
PA: Parse
GE: Generate
SU: Subcompile
EX: Execute

code analysis, format, misc
PL: Perl Interpreter
PC: Perl::Critic Analyzer
DI: Difference Checker
AS: Abstract Syntax Tree
RP: RPerl
CP: C++
NG: Non-Generating
FI: Filesystem

SPECIFIC APPLICATION CODE LEGEND

AL: Algorithm
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 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

# [[[ UNINDENT ]]]
:%s/^\ \ \ \ //g


##########################################################################################
# GDB
##########################################################################################

$ gdb /usr/bin/perl
(gdb) run ./script/demo/FOO arg0 arg1
...
(gdb) bt


##########################################################################################
# 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


##########################################################################################
# RELEASE HOLIDAYS
##########################################################################################

NEW YEAR'S
GROUNDHOG
ST. VALENTINE'S
PI
ST. PATRICK'S
APRIL FOOLS'
GOOD FRIDAY
EASTER
MAY THE 4TH
CAPTAIN PICARD DAY (JUNE 16)
INDEPENDENCE
HALLOWEEN
THANKSGIVING
CHRISTMAS

MOTHER'S DAY?
FATHER'S DAY?


##########################################################################################
# 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
$ rm RPerl*.tar.gz; rm MANIFEST
$ perl Makefile.PL; make distclean
$ perl Makefile.PL; make realclean
$ inline_clean.sh

# 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
$ cp MYMETA.json META.json
	# properly install configure-time dependencies, must have for Alien::* 

# 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
# DONE!