# RPerl Developer Notes 20200304 2020.064

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

ERROR CODE RANGES

ECOGEASxP 0xx - 4xx : misc codes which match between PERLOPS_PERLTYPES & CPPOPS_CPPTYPES (& CPPOPS_PERLTYPES eventually)
          18x       : DEV NOTE, CORRELATION #rp045: identifiers containing underscores may be reserved by C++ 
ECOGEASxP 180x      : variable
ECOGEASxP 181x      : subroutine def
ECOGEASxP 182x      : subroutine call
ECOGEASxP 183x      : subroutine arg
ECOGEASxP 184x      : package or class
ECOGEASxP 185x      : include
ECOGEASxP 186x      : method def
ECOGEASxP 187x      : method call
ECOGEASxP 188x      : method arg
ECOGEASxP 189x      : property

ECOGEASxP 5xx:       PERLOPS_PERLTYPES only codes

ECOGEASxP 6xx - 7xx: CPPOPS_PERLTYPES only codes

ECOGEASxP 8xx - 9xx: CPPOPS_CPPTYPES only codes


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

unindent lines starting w/ spaces
:%s/^\ \ \ \ //g

unindent lines starting w/ \\ comment
:%s/^\/\/\ \ \ \ /\/\//g

unindent lines starting w/ # comment
:%s/^\#\ \ \ \ /\#/g


##########################################################################################
# GDB & VALGRIND
##########################################################################################

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

$ valgrind -v /usr/bin/perl ./script/demo/FOO arg0 arg1


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

01/01  New Year's
02/02  Groundhog Day
02/14  St. Valentine's Day
03/14  Pi Day
03/17  St. Patrick's Day
04/01  April Fools'
04/10? Good Friday
04/12? Easter
05/04  May The 4th
05/10? Mother's Day
05/25? Memorial Day
06/16  Captain Picard Day (June 16)
06/21? Father's Day
07/04  Independence Day
09/07? Labor Day
09/27  Larry Wall's Birthday AKA St. Wall's Day (September 27, 1954)
10/31  Halloween
11/26? Thanksgiving
12/18  Perl's Birthday AKA Perl Day (December 18, 1987)
12/25  Christmas



##########################################################################################
# CPAN INSTALLATION PROCESS
##########################################################################################

your dist's configure prereqs are checked in META.json, the CPAN client goes and installs those.
the CPAN client runs your Makefile.PL (configure phase).
the CPAN client checks MYMETA.json for build, test and runtime prereqs and installs those.
neither your Makefile.PL nor generated Makefile are involved in installation of other modules.


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

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

# CHECK POD
$ podchecker lib/RPerl.pm
$ podchecker script/rperl

# UPDATE VERSION NUMBERS
$ vi Changes
	# version, date, name, notes
$ vi lib/RPerl.pm
    # $VERSION
$ vi script/rperl
    # $VERSION
    # -v option, if minor version then keep codename from previous major version

# 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 META.json META.yml MYMETA.json MYMETA.yml  # DO NOT SKIP THIS STEP, REQUIRED TO CLEAR PREVIOUS VERSION IN META.*
$ perl Makefile.PL; make distclean
$ perl Makefile.PL; make realclean
$ inline_clean.sh

# MAKE MANIFEST & DIST
$ perl Makefile.PL; make manifest
    # generates MYMETA.json & MYMETA.yml; generates MANIFEST
$ less MYMETA.json
    # ensure updated version
$ less MYMETA.yml
    # ensure updated version
$ 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
$ cp MYMETA.json META.json
	# DEV NOTE, CORRELATION #rp061: properly install configure-time dependencies, must have for RPerl & Alien::* 
$ make dist
    # produces tarball output

# INSTALL & TEST DIST, LOCAL COPY
$ cpanm --verbose ./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/
$ make realclean
$ 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!


##########################################################################################
# DOCKER IMAGE
##########################################################################################

# BUILD COMMANDS

# build image
$ cd ~/repos_github/rperl-latest/Docker/cpan_auto_deps
$ sudo docker build -t wbraswell/rperl_cpan . > /tmp/docker_rperl_cpan.out 2>&1

# test local image
$ sudo docker run --name rperl_cpan_instance -ti wbraswell/rperl_cpan
$ sudo docker rm rperl_cpan_instance

# upload image
$ sudo docker push wbraswell/rperl_cpan:latest

# test remote image
$ sudo docker rmi wbraswell/rperl_cpan:latest
$ sudo docker run --name rperl_cpan_instance -ti wbraswell/rperl_cpan
$ sudo docker rm rperl_cpan_instance

# EXTRA COMMANDS

# list all images
$ sudo docker images

# remove image
$ sudo docker rmi <IMAGE>

# list all containers, both running & stopped
$ sudo docker ps -a

# remove container
$ sudo docker rm <CONTAINER>