NAME

Learning RPerl

BOOK TITLE

Learning RPerl

~ or ~

Let's Write Fast Perl!

~ affectionately known as ~

The Roadrunner Book

.
...
.....
.......
being
.......
.....
...
.

The Official Introductory-Level Reference, User Manual, and Educational Documentation

~ for ~

Restricted Perl, The Optimizing Perl 5 Compiler


DEDICATION

For Anna.


EDITION

0th Edition, Pre-Release Copy

Automatically Generated From RPerl/Learning.pm v0.153
Using pod2rperlhtml.pl v0.027
On Sunday, October 23rd, 2016 at 3:44pm CDT


TABLE OF CONTENTS: CHAPTERS AT-A-GLANCE


FOREWORD

[ INSERT FOREWORD CONTENT HERE ]


PREFACE

Section 0.1: Who I Am

My name is William N. Braswell, Jr.; I am also known by a number of other names including Will the Chill, The Voice In The Wilderness, Skipper Brassie ("braz-ee"), and just Will.

I have a degree in computer science and mathematics from Texas Tech University, I have worked as a Perl software developer for over 15 years, and I am the founder of the Auto-Parallel Technologies consulting company.

LinkedIn Profile

GitHub Profile

I am 1 of 3 co-founders of the Perl 11 movement.

Perl11.org

I am also the President of the Austin Perl Mongers.

Austin.pm

Most importantly, I am the creator of the RPerl optimizing compiler for Perl 5, about which you are currently reading!

RPerl.org

Section 0.2: Why I Wrote This Book

Using RPerl is different enough from normal Perl 5 to necessitate the creation of in-depth user documentation.

Manual pages and cookbooks and example source code alone are not enough, only a full textbook can provide the level of detail necessary to truly learn RPerl.

This is that textbook.

Section 0.3: History Of This Book

RPerl v1.0 was released on US Independence Day, July 4th, 2015; 6 days later, work began on the source code solution to exercise 1 of chapter 1 of this book:

First Learning RPerl Commit on GitHub

Significant GitHub commit dates include, but are not limited to the following:

    $ git log --reverse --all --date=short --pretty='%cd: %s' | grep 'Learning RPerl'
    2015-07-10: Learning RPerl, Chapter 1, Exercise 1, Hello World
    2015-07-11: Learning RPerl, Chapter 2, Exercise 1, Circumference Of Circle With Radius 12.5
    2015-07-12: Learning RPerl, Chapter 2, Exercise 1, Circumference Of Circle With Radius 12.5, Part 2
    2015-07-13: Learning RPerl, Chapter 2, Exercise 2, Circumference Of Circle With Any Radius
    2015-07-14: Learning RPerl, Chapter 2, Exercise 3, Circumference Of Circle With Any Positive Radius
    2015-07-15: Learning RPerl, Chapter 2, Exercise 4, Product Of Any Two Numbers
    2015-07-16: Learning RPerl, Chapter 2, Exercise 5, String Repeat
    2015-07-18: Learning RPerl, Chapter 3, Exercise 1, STDIN Strings Reverse
    2015-07-17: Learning RPerl, Chapters 1 & 2, Add Source Comments
    2015-07-19: Learning RPerl, Chapter 3, Exercise 2, STDIN Array Indices
    2015-07-20: Learning RPerl, Chapters 2 & 3, Add Source Comments
    2015-07-21: Learning RPerl, Chapter 3, Exercise 3, STDIN Strings Sort
    2015-07-22: Learning RPerl, Chapter 4, Exercise 1, Subroutine For Stringified Numbers Total
    2015-07-23: Learning RPerl, Chapter 4, Exercise 2, Subroutine For Total Of 1 To 1,000
    2015-07-25: Learning RPerl, Chapter 4, Exercise 3, Subroutines For Above-Average Array Elements
    2015-10-03: Learning RPerl, Chapter 4, Exercise 4, Subroutine To Greet User
    2015-10-04: Learning RPerl, Chapter 4, Exercise 5, Subroutine To Greet Multiple Users
    2015-10-05: Learning RPerl, Chapter 5, Exercise 1, Print Input File(s) Lines In Reverse, Part 1
    2015-10-06: Learning RPerl, Chapter 5, Exercise 1, Print Input File(s) Lines In Reverse, Part 2
    2015-10-07: Learning RPerl, Chapter 5, Exercise 2, Print Input Line(s) Right-Justified
    2015-10-08: Learning RPerl, Chapter 5, Exercise 3, Print Input Line(s) Variable-Width Right-Justified, Part 1
    2015-10-09: Learning RPerl, Chapter 5, Exercise 3, Print Input Line(s) Variable-Width Right-Justified, Part 2
    2015-10-10: Learning RPerl, Chapter 6, Exercise 1, Print Family Names
    2015-10-11: Learning RPerl, Chapter 6, Exercise 2, Unique Word Count
    2015-10-12: Learning RPerl, Ensure All Exercises Parse, Part 1
    2015-10-13: Learning RPerl, Ensure All Exercises Parse, Part 2
    2015-10-19: Learning RPerl, Ensure All Exercises Parse, Part 3
    2015-10-20: Learning RPerl, Ensure All Exercises Parse, Part 4
    2015-10-21: Learning RPerl, Ensure All Exercises Parse, Part 5
    2015-10-22: Learning RPerl, Ensure All Exercises Parse, Part 6
    2015-10-23: Learning RPerl, Ensure All Exercises Parse, Part 7
    2015-10-24: Learning RPerl, Ensure All Exercises Parse, Part 8
    2015-10-25: Learning RPerl, Ensure All Exercises Parse, Part 9
    2015-10-26: Learning RPerl, Ensure All Exercises Parse, Part 10
    2015-10-27: Learning RPerl, Ensure All Exercises Parse, Part 11
    2015-10-28: Learning RPerl, Ensure All Exercises Parse, Part 12
    2015-10-28: Learning RPerl, Ensure All Exercises Parse, Part 13
    2015-10-28: Learning RPerl, Ensure All Exercises Parse, Part 14
    2015-11-07: CPAN Release, v1.200002; Temporarily Fix Macintosh Build Failures, Learning RPerl Parse Failure, Etc.
    2015-11-10: Learning RPerl, Content, Part 1
    2015-11-11: Learning RPerl, Content, Part 2
    2015-11-14: Learning RPerl, Content, Part 3
    2015-11-15: Learning RPerl, Content, Part 4
    2015-11-16: Learning RPerl, Content, Part 5
    2015-11-16: Learning RPerl, Content, Part 6
    2015-11-17: Learning RPerl, Content, Part 7
    2015-11-18: Learning RPerl, Content, Part 8
    2015-11-18: Learning RPerl, Content, Part 9
    2015-11-19: Learning RPerl, Content, Part 10
    2015-11-20: Learning RPerl, Content, Part 11
    2015-11-21: Learning RPerl, Content, Part 12
    2015-11-22: Learning RPerl, Content, Part 13
    2015-11-24: Learning RPerl, Content, Part 14
    2015-12-31: Learning RPerl, Content, Part 15
    2015-12-31: Learning RPerl, Content, Part 16
    2016-01-01: Learning RPerl, Content, Part 17
    2016-01-02: Learning RPerl, FontAwesome & MetaCPAN Files, Initial Commit
    2016-01-02: News, RPerl v1.5 Release; Learning RPerl, FontAwesome & MetaCPAN Files, Move To Subdirectories
    2016-01-02: Learning RPerl, Update pod2rperlhtml.pl Script, Correct CSS & JS Paths
    2016-01-02: Learning RPerl, HTML Content, Initial Commit
    2016-01-03: Learning RPerl, Content, Part 18
    2016-01-05: Learning RPerl, Content, Part 19
    2016-01-06: Learning RPerl, Content, Part 20
    2016-01-07: Learning RPerl, Content, Part 21
    2016-01-08: Learning RPerl, Content, Part 22
    2016-01-09: Learning RPerl, Content, Part 23
    2016-01-09: Learning RPerl, Content, Part 24
    2016-01-10: Learning RPerl, Content, Part 25
    2016-01-11: Learning RPerl, Content, Part 26
    2016-01-12: Learning RPerl, Content, Part 27
    2016-01-14: Learning RPerl, Content, Part 28
    2016-01-15: Learning RPerl, Content, Part 29
    2016-01-16: Learning RPerl, Content, Part 30
    2016-01-16: Learning RPerl, Content, Part 31
    2016-01-16: Learning RPerl, Content, Part 32
    2016-03-03: Learning RPerl, Chapter 2 Content, Part 1
    2016-03-03: Learning RPerl, TPF Grant #2, Part 1

Section 0.4: TPF Grants

This book was made possible in part by 2 generous grants from The Perl Foundation, as part of the September 2015 and January / February 2016 rounds of funding.

Special thanks to TPF Grants Committee Secretary, Makoto Nozaki; TPF Grant Manager, Mark Jensen; TPF Grants Committee's various supporting members; and everyone who gave positive feedback on the grant proposals.

A history of TPF grant #1 may be found at the following links:

A history of TPF grant #2 may be found at the following links:

Section 0.5: Acknowledgements & Thanks

Countless people have contributed to the development of RPerl; from source code to bug testing to financial donations to emotional support, it truly takes a village to build a compiler!

Below are the contents of the official RPerl thank-you file, listing the handles (online nicknames) and names of the most important RPerl contributors. If you don't already know who these people are, you will be pleasantly surprised by researching each of them.

Latest THANKS File

    Many Thanks To irc.perl.org:

    #perl5 Founder timtoady

    #perl6 Founder timtoady (again)

    #perl11 Founders ingy & rurban & willthechill (yours truly)

    #perl11 Members bulk88 & mst

    #inline Founders ingy (again) & nwatkiss

    #inline Members davido & mohawk & sisyphus


    Additional Thanks To:

    Eyapp Creator Casiano Rodriguez-Leon, PhD

    Austin Perl Mongers

    All RPerl Contributors & Users & Supporters

Section 0.6: Defense / Apology

I'm sure I will make errors while writing this book.

I may even upset some people, particularly those who have an emotional or financial investment in slow Perl software.

Despite my best efforts, I remain a fallible human being; thus, bad spelling and grammer and run-on sentences and parts that are hard to understand and parts that are not funny and formattiNg errors and bad spelling adn repetitions and other annoyances will doubtless plague this tome but we must not allow such trivialities as, improper punctuation to affect our willingness and ability to learn how to write super-fast RPerl software.

If you find a mistake in this book (other than in the immediately preceding paragraph), please utilize the following link to create a new GitHub issue (bug report) using a title starting with the words "Learning RPerl":

New GitHub Issue

I will try my best to create an engaging and educational experience for you, the reader; however, in anticipation of the inevitable disappointment you may experience, I can only humbly offer...

I'M SORRY!

Section 0.7: POD

"The Pod format is not necessarily sufficient for writing a book."

http://perldoc.perl.org/perlpod.html

~ Saint Larry Wall & Sean M. Burke


"Challenge accepted."

https://github.com/wbraswell/rperl/blob/master/script/development/pod2rperlhtml.pl

~ Will Braswell


CHAPTER 1: INTRODUCTION

Section 1.1: Welcome To The Roadrunner Book!

You are about to learn the basic concepts of writing software using the RPerl optimizing compiler for the Perl computer programming language. With the skills gained by reading this book, you will be empowered to create new super-fast RPerl programs which can be intermixed with the enormous amount of existing Perl software available on the Internet.

This book is named and stylized for the animal mascot for RPerl, Roadie the Roadrunner. RPerl, like Roadie, "runs really fast".

Throughout this text, the following 14 typography conventions are utilized:

Section 1.2: Learning Perl

This book is purposefully patterned after the popular educational text Learning Perl, affectionately known as the Llama Book. Both the Roadrunner Book and the Llama book are meant as introductory texts on Perl topics. The Llama Book is focused on normal Perl, and the Roadrunner Book is focused on optimized Perl.

This book copies the same chapter topics as Learning Perl, but all content is re-written for RPerl. Learning RPerl also copies the same exercise concepts as Learning Perl, but all solutions are re-written in RPerl. Both books are canonical and may be used together in the classroom; the source code solutions are meant to be compared side-by-side as textbook examples of normal Perl versus optimized Perl.

Please support the Perl community by purchasing a copy of Learning Perl, 7th Edition from our friends at O'Reilly:

http://shop.oreilly.com/product/0636920049517.do

Section 1.3: Is This Book A Good Choice For You?

If you answered "yes" to any of these questions, then the Roadrunner Book is definitely for you!

If you answered "no" to all of these questions, then this book may still be for you, give it a try!

If you hate Perl, or only love slow software, or wish all computers would explode, then we suggest some soul-searching and a few Saint Larry videos. You'll thank us in the morning.

Section 1.4: Why Aren't There More Footnotes?

This is a purposefully simple book, in the same way RPerl is a purposefully simple subset of the full Perl 5 programming language.

Section 1.5: What About Educational Programming Exercises?

There are one or more programming exercises at the end of every chapter, and full answers to each problem are given near the end of the book in Appendix A.

For maximum educational effect, we suggest you attempt to write each piece of code on your own before looking at our solutions.

If you are using this as an official textbook for certification or academic credit, such as at LAMPuniversity.org or a traditional school, you are obviously expected to write all your own code without referring to our or anyone else's solutions whatsoever. We suggest you enclose Appendix A with a paper clip or discard it altogether to avoid the potential for accidental academic dishonesty.

Section 1.6: How Long Should Each Exercise Take To Complete?

The numbers at the beginning of each exercise indicate the approximate number of minutes required for an average person to reach a full working solution. If it takes you less time, good for you! If it takes you more time, don't worry, it's no big deal; learning technical skills requires time and dedication. All experts were once novices.

Section 1.7: What If I Want To Teach RPerl?

Thank you for helping spread the love of Perl and the speed of RPerl!

As previously mentioned, this book may either be used solo or combined with the Llama Book. For students who are not already familiar with Perl, you may wish to use this text alone in order to simplify and ease the learning experience. For students who are already familiar with Perl or other dynamic programming languages like the snake or the red gemstone, you may wish to use both textbooks for a more in-depth compare-and-contrast approach.

Section 1.8: What Does The Name RPerl Actually Mean?

RPerl stands for "Restricted Perl", in that we restrict our use of Perl to those parts which can be made to run fast. RPerl also stands for "Revolutionary Perl", in that we hope RPerl's speed will revolutionize the software development industry, or at least the Perl community. RPerl might even stand for "Roadrunner Perl", in that it runs really fast.

Section 1.9: Why Did Will Invent RPerl?

Will loves Perl and the Perl community.

Will is a scientist and needs his code to run really fast.

Will doesn't like the hassle of writing code in C or C++ or XS or Inline::C or Inline::CPP.

Will waited a decade or two before realizing he had to do it himself.

Section 1.10: Why Didn't Will Just Use Normal Perl?

Dynamic languages like Perl are fast at running some kinds of computational actions, such as regular expressions (text data pattern matching) and reading from a database.

Unfortunately, dynamic languages are slow at running general-purpose computations, such as arithmetic and moving data around in memory. Sometimes very slow.

Dynamic languages like Perl are also flexible, powerful, and relatively easy to learn. Sometimes too flexible.

RPerl's goal is to keep all of Perl's power and ease-of-use, while removing the redundant parts of Perl's flexibility in order to gain a major runtime speed boost.

The most complex and flexible parts of Perl are called "high magic", so RPerl is focused on supporting the "low magic" parts of Perl which can be made to run fast.

Section 1.11: Is RPerl Simple Or Complicated?

RPerl is specifically designed to remove the confusing and overly-complicated parts of Perl.

RPerl also introduces a number of additional rules and templates which are not present in normal Perl, notably including the use of real data types.

The net effect of removing Perl complexity and adding RPerl rules falls in favor of RPerl, due primarily to the exceedingly complex nature of Perl.

In other words, RPerl is easier to learn and use than dynamic languages like normal Perl, and most any other language in general.

Section 1.12: How Is RPerl Being Promoted?

The RPerl team has been regularly promoting RPerl in a number of physical and digital venues, including but not limited to:

Section 1.13: What Is The RPerl Community Up To?

As of US Independence Day 2016, RPerl v2.0 (codename Pioneer) has been publicly released and is in use by a number of early adopters around the world.

RPerl development is proceeding with financial support from both Kickstarter crowdfunding and official grant monies from The Perl Foundation.

The RPerl community is beginning to grow, and there are a number of exciting RPerl projects currently in the works.

If you would like to create software libraries and applications (AKA "programs" or "apps") to be utilized by end-users, then please join the RPerl application developers group, also known as the "RPerl App Devs":

RPerl App Devs Group On Facebook

RPerl App Devs Intake Board On Trello

Section 1.14: What Is RPerl Meant To Do?

RPerl is a general-purpose programming language, which means you can use RPerl to efficiently and effectively implement virtually any kind of software you can imagine.

RPerl is especially well-suited for building software which benefits from speed, such as scientific simulations and graphical video games.

RPerl is also good for building software which utilizes Perl's strong-suit of string manipulation; RPerl currently supports basic string operators, with full regular expression support to be added in an upcoming version.

Section 1.15: What Is RPerl Not Meant To Do?

RPerl has purposefully disabled the most complex features of Perl, such as runtime code evaluation, secret operators, and punctuation variables. If you have purposefully designed your Perl software to depend on these high-magic features, or you are unconditionally committed to continue using high-magic language features, then maybe RPerl isn't for you.

Section 1.16: How Can I Download & Install RPerl?

Installing RPerl ranges from easy to difficult, depending on how well your operating system supports Perl and C++.

On modern operating systems with good Perl support, such as Debian or Ubuntu GNU/Linux, you should be able to install RPerl system-wide by running the following command at your terminal command prompt:

    $ sudo cpan RPerl

You may also choose to use the `cpanm` command for simplicity, or the local::lib tool for single-user (not system-wide) installation, both of which are included in the INSTALL notes document linked below.

If RPerl is properly installed, you should see a short text message displayed when you type the following command:

    $ rperl -v

On operating systems with less Perl support, you may have to perform a number of steps to successfully install RPerl, with dry technical detail available in the INSTALL notes document:

https://github.com/wbraswell/rperl/blob/master/INSTALL

Unless you are an experienced programmer or system administrator, it is strongly recommended you use the Xubuntu operating system. You can download the Xubuntu ISO file at the link below, then use it to create a bootable DVD disc or USB flash drive, install Xubuntu onto any computer, and issue the `sudo cpan RPerl` command as described above.

http://xubuntu.org/getxubuntu

If you are interested in viewing the source code of RPerl itself, you may find the latest major release of RPerl (stable) on CPAN:

https://metacpan.org/author/WBRASWELL

You may find the latest development release of RPerl (possibly unstable) on Github:

https://github.com/wbraswell/rperl

Section 1.17: Where Is Perl Software Stored Online?

CPAN is the "Comprehensive Perl Archive Network", the world's most successful and mature centralized software network.

CPAN servers are where most public Perl software is stored, including RPerl.

https://en.wikipedia.org/wiki/CPAN

http://www.cpan.org

Several other programming language communities have copied the success and implementation of CPAN, including JSAN for Javascript, CRAN for R, and CCAN for C.

Section 1.18: How Can I Obtain Technical Support For RPerl?

Official RPerl technical support is provided through Auto-Parallel Technologies, Inc.

To request more information, please send an e-mail to the following address:

william DOT braswell AT autoparallel DOT com

Section 1.19: Are There Any Free Technical Support Options?

Free technical support for non-commercial users is provided by the RPerl community through Internet Relay Chat.

Server: irc.perl.org

Channel: #perl11

Easy Web Chat: http://irc.lc/magnet/perl11/rperl_newbie@@@

Section 1.20: Are There Any Bugs In RPerl?

All software has small (or large) problems called "bugs", and depending on who is marketing the software, they may even tell you some of the bugs are actually "features"!

RPerl is a work in progress, and may contain a number of bugs, both known and unknown. If you find a bug in RPerl, we would love to hear about it!

The primary bug-tracking platform for RPerl is Github Issues, where you may file a new bug report ("new issue") if it is not already listed:

https://github.com/wbraswell/rperl/issues

Please be sure to include all of the following information in your bug report:

Although Github Issues is strongly preferred, the RPerl development team also supports the legacy CPAN ticket system:

https://rt.cpan.org/Public/Dist/Display.html?Name=RPerl

Section 1.21: How Can I Write A Program Using RPerl?

Computer programs written using the RPerl language are plain text files, which means you can use any text editor to create and modify your RPerl source code. Examples of common text editors include Notepad, Pico, and Vi.

http://www.vim.org

To avoid possible file format problems, do not edit your RPerl programs using a word processor such as Wordpad, Word, OpenOffice, or LibreOffice.

Experienced RPerl developers may choose to utilize an "integrated development environment" (IDE), which is a special text editor made for writing software. Examples of common Perl IDE applications include Eclipse EPIC, Padre, and Komodo (non-free).

http://www.epic-ide.org

http://padre.perlide.org

http://komodoide.com/perl

Section 1.22: A Sample RPerl Program

    #!/usr/bin/perl
    
    # Foo Bar Arithmetic Example
    
    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;
    
    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    
    # [[[ OPERATIONS ]]]
    my integer $foo = 21 + 12;
    my integer $bar = 23 * 42 * 2;
    my number  $baz = to_number($bar) / $foo;
    print 'have $foo = ', to_string($foo), "\n";
    print 'have $bar = ', to_string($bar), "\n";
    print 'have $baz = ', to_string($baz), "\n";

Section 1.23: What Are The Parts Of That Sample RPerl Program?

This program is separated by blank lines into 4 sections: shebang, header, critics, and operations.

Other than the shebang and critics, all lines beginning with # are comments and can be safely ignored or discarded without affecting the program.

The "shebang" section is required, always contains exactly 1 line, and is short for "hash bang"; referring to the two leading characters #! of this line. The "octothorpe" character # (tic-tac-toe symbol) is called a "pound sign" when used on a telephone, and is called a "hash" (or more recently and less accurately "hash tag") when used on a computer. The exclamation point character ! is called a "bang" when used on a computer. When appearing together as the first two characters in a plain text file, the hash and bang characters tell the operating system to run the immediately-following command (in this case the Perl interpreter located at /usr/bin/perl) and pass the remaining contents of the text file as input to the command. In other words, if the first line of a plain text file is #!/usr/bin/perl, then that file is a Perl program.

The "header" section is required and always contains 4 lines for an RPerl "program" file ending in .pl, or 5 lines for an RPerl "module" ending in .pm (covered later in Chapter 11). use is recognized by Perl as a special "keyword" (AKA "built-in operator") which has 2 primary purposes: to load additional RPerl modules, and to enable RPerl "pragma" system configuration modes. The use RPerl; line is dual-purpose, it both loads the RPerl.pm module and enables the special RPerl low-magic pragma. The use strict; and use warnings; lines enable basic Perl pragmas which require decent programming practices by the human programmers. The our $VERSION = 0.001_000; line sets the version number of this RPerl program.

The "critics" section is included as necessary and may contain 1 or more lines beginning with ## no critic, which disable the errors caused by the over-restrictive nature of some Perl::Critic policies. There are currently 6 critics commands enabled for normal RPerl users, the first 2 of which are given in this example. The "USER DEFAULT 1" no critic command allows the use of numeric values such as 21 and 12, as well as the common print command. The USER DEFAULT 2 critics command allows the printing of 'have $foo = ', where a single-quoted ' string literal value contains the the $ dollar sigil (covered later in Chapter 2).

The "operations" section is required and contains 1 or more lines of general-purpose RPerl source code. This is the main body of your program. The 6 lines of source code in our example are used to perform some simple arithmetic and display the results. The my integer $foo = 21 + 12; line declares a new variable named $foo which will only contain non-floating-point numeric data, and which is initialized to contain the arithmetic result of numeric literal values 21 plus 12. The my integer $bar = 23 * 42 * 2; line does much the same thing, creating a new numeric variable named $bar and initialized with 23 times 42 times 2. The my number $baz = to_number($bar) / $foo; line creates a new floating-point numeric variable $baz, and initializes it to the quotient of the $bar and $foo variables. The to_number() RPerl type conversion subroutine converts a non-floating-point integer value to a floating-point number value.

The print 'have $foo = ', $foo, "\n"; and following 2 lines will display on screen (not send to paper printer) the labeled values of $foo, $bar, and $baz respectively. The , comma is used to separate multiple arguments passed to the print operator. The to_string() RPerl type conversion subroutine converts the numeric values to underscore-formatted string values, suitable for use via the print operator. If the <to_string()> subroutine is not used, then the displayed numeric values will still be human-readable, but will not contain the proper underscores to be accepted back into RPerl as valid numeric data. The "n" in the "\n" double-quoted string literal values stands for "newline", which inserts a carriage return to place the next piece of printed data down on the following line.

Section 1.24: How Do I Run The RPerl Compiler?

Normal Perl source code is executed using a software mechanism known as "interpretation", which is to say that Perl is an "interpreted" language and the /usr/bin/perl command is called the "Perl interpreter". The primary alternative to interpretation is "compilation", so RPerl is a "compiled" subset of the Perl language and the /usr/bin/rperl command is called the "RPerl compiler".

Like the Perl interpreter, the RPerl compiler accepts 2 different input file types: Perl programs which end in .pl and Perl modules which end in .pm. Perl program files actually run and execute actions, optionally receiving some functionality from 1 or more Perl module files if specified. Perl modules do not run or execute actions themselves, they only provide functionality which must in turn be called from a Perl program, or from another Perl module which eventually gets called by a Perl program.

A list of all valid RPerl compiler options may be seen by issuing the following command:

    $ rperl -?

You may find the same information by viewing the following links:

rperl

https://metacpan.org/pod/distribution/RPerl/script/rperl

To compile-then-execute the preceding RPerl example program, you may copy and paste the entire program (from shebang to second print) into a temporary file such as /tmp/foobar.pl, then execute the following command:

    $ rperl /tmp/foobar.pl

The output of this example program should be:

    have $foo = 33
    have $bar = 1_932
    have $baz = 58.545_454_545_454_5

If the compilation is successful, a new compiled executable file will be created in /tmp/foobar. You may then directly execute the compiled program as many times as you like, without needing to recompile it using the `rperl` command, and you should receive the exact same output as the non-compiled code:

    $ /tmp/foobar
    have $foo = 33
    have $bar = 1_932
    have $baz = 58.545_454_545_454_5

Please see "CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES" for more information about compiling Perl modules.

Section 1.25: A Quick Overview of RPerl

Section 1.25.1: Creator Of RPerl, Will Braswell

Will Braswell does more than just create Perl compiler software, he is also very active in several other areas of life, including but not limited to:

These areas of interest are reflected in the tone and intention of RPerl.

Section 1.25.2: History Of RPerl

The RPerl project officially began as a New Year's Resolution on January 1st, 2013. Following the grand tradition of Perl creator "Saint" Larry Wall, RPerl version releases are often timed to coincide with major holidays.

After 1 year of work, RPerl v1.0beta1 was released on New Year's Day 2014, eventually followed by RPerl v1.0beta2 on Christmas 2014.

The much-anticipated RPerl v1.0 full release was made on US Independence Day 2015, and RPerl v1.2 came on Halloween 2015.

RPerl v1.3 was released on Thanksgiving 2015, followed by RPerl v1.4 on Christmas 2015, and so forth.

RPerl v1.0 was funded through a Kickstarter campaign, then RPerl v1.2 and v1.3 were funded through a second Kickstarter campaign. Work on the first 6 chapters of this book was funded, in part, by grants from The Perl Foundation.

RPerl v2.0 was released on US Independence Day 2016, exactly 1 year after v1.0 was released, in order to establish a regular annual release cycle.

Section 1.25.3: Performance Of RPerl

The question of "How fast is RPerl?" does not have one simple answer; instead there are several factors and configuration modes to be taken into consideration. A relatively detailed description of the performance and modes may be found at the following link:

http://rperl.org/performance_benchmarks.html

The most condensed answer is that "RPerl is really fast." Utilizing RPerl's fastest execution modes, we see performance very close to the highly-optimized C++ programming language, which means RPerl is now among the short list of "world's fastest languages" along with C, C++, and Fortran.

Section 1.25.4: The Low-Magic Perl Commandments

The high-magic features of Perl are primarily responsible for how slow Perl runs for general-purpose computations. The "R" in RPerl stands for "Restricted", in that we restrict ourselves to only use the low-magic features of Perl which can run really fast.

The definitive list of do's and do-not's for high-magic vs low-magic Perl programming is called The Low Magic Perl Commandments (LMPC). There are 64 total commandments split into 5 groups of Ideals, Magic, Data, Operations, and Object-Orientation. The "Thou Shalt" commandments appear in the left column, and the "Thou Shalt Nots" appear on the right.

http://rperl.org/the_low_magic_perl_commandments.html

The LMPC draw inspiration from, and (wherever possible) work together with Damian Conway's Perl Best Practices and Jeffrey Thalhammer's Perl::Critic software.

http://shop.oreilly.com/product/9780596001735.do

http://search.cpan.org/~thaljef/Perl-Critic/lib/Perl/Critic/PolicySummary.pod

Section 1.25.5: Perlism & The Book Of RPerl

Perlism is the computer religion dedicated to the use, promotion, and development of the Perl family of programming languages. (Not to be confused with a spiritual religion such as Christianity, a computer religion such as Perlism is an independent and complementary belief structure.)

A Perlite is an adherent to the Perlism religion. Perlism has a revered founder, Saint Larry (himself a devout Christian); a prophet, The Voice In The Wilderness (Will); a monastary and shrine, Perl Monks; commandments, The LMPC; proverbs from Saint Larry including TIMTOWTDI, LMFB, and HTAAOF; and canonical scriptures, including Saint Larry's Apocalypses and The Voice's The Book Of RPerl.

The Book is a description of events surrounding the creation of RPerl and the future of the Internet. It is intended to both educate and entertain.

http://rperl.org/the_book_of_rperl.html

Section 1.25.6: Fun With Proverbs & Catch Phrases & Acronyms

St. Larry has given us short and powerful proverbs, some of which are meant to have a purposefully tongue-in-cheek or sarcastic interpretation.

Will has provided a corollary to each of St. Larry's official proverbs.

St. Larry's Original Proverb

Will's Corollary Proverb

3 Great Virtues Of A Programmer:

LIH (Laziness, Impatience, Hubris)

3 Greater Virtues Of A Programmer:

DPH (Diligence, Patience, Humility)

TIMTOWTDI (There Is More Than One Way To Do It)

TDNNTBMTOWTDI (There Does Not Need To Be More Than One Way To Do It)

TIOFWTDI (There Is One Fastest Way To Do It)

LMFB (Let Many Flowers Bloom)

PTBF (Pick The Best Flowers)

HTAAOF (Have The Appropriate Amount Of Fun)

DTAAOW (Do The Appropriate Amount Of Work)

In addition to St. Larry's official proverbs, there are a number of other commonly-used catch phrases and ideas in the Perl community.

Original Catch Phrase

Will's Corollary Catch Phrase

Perl 5 Is The Camel

Perl 5 Is The Raptor

Perl 6 Is The Butterfly

RPerl Is The Roadrunner

Perl Is The Onion

RPerl Is The Scallion

Perl Is The Swiss Army Chainsaw

RPerl Is The Sword

Perl Is Line-Noise

Perl Is A Write-Only Language

RPerl Is Best Practices

Section 1.26: What's New In RPerl v2.0?

The single most significant new feature included in RPerl v2.0 is automatic parallelization. This long-awaited software feature was promised from the very beginning of RPerl's initial development, with RPerl v2.0 being the originally-designated target for release of auto-parallel capabilities. We stuck to the plan and delivered on time: the 4th of July, 2016.

Automatic parallelization is now enabled on 4 parallel CPU cores by default, because quad-core CPUs are common at this time. You may utilize the --num_cores=8 command-line argument to double the default number of parallel cores, for example. (Please see "B.16: Modes, Parallelize" and "B.17: Modes, Parallelize, Number Of Cores" for more information about auto-parallelization arguments.)

Currently, shared memory parallel hardware platforms are supported, such as multi-core CPUs and supercomputers, by utilizing the OpenMP parallelization software. In the near future we will add support for distributed memory platforms, such as clusters and the cloud, by utilizing the MPI parallelization software, as well as GPUs and other specialty hardware by utilizing the OpenCL parallelization software.

RPerl triggers auto-parallelization by simply including the word 'PARALLEL' in a loop label; everything inside that loop will be automatically parallelized, including multiply-nested loops. RPerl implements the polytope model (AKA polyhedral model) for loop parallelization, by utilizing the Pluto PolyCC polytope software.

In addition to auto-parallelization, a number of other new features were released after RPerl v1.0 and by-or-before v2.0, including but not limited to:

Section 1.27: Exercises

1. Hello World [ 15 mins ]

On a computer with RPerl already installed, create a directory named LearningRPerl containing a sub-directory named Chapter1. Using the Foo Bar example program as a template, manually type a new RPerl program into a file named exercise_1-hello_world.pl inside the LearningRPerl/Chapter1 sub-directory. The sole purpose of your first program is to use the print operator and simply display the following one line of text output, followed by one newline character:

    Hello, World!

Run your new program by issuing the following command at your terminal command prompt:

    $ rperl -t LearningRPerl/Chapter1/exercise_1-hello_world.pl

HINT: You only need the "USER DEFAULT 1" no critic command, so your resulting program should be 7 lines long, not counting comments or blank lines.

2. RPerl Commands [ 15 mins ]

First, run the following RPerl command, and observe the output for use in 2a and 2b below:

    $ rperl -?

2a. What are some RPerl command-line options with which you are already familiar?

2b. With which options are you unfamiliar?

Next, run the following 3 RPerl commands, for 2c and 2d below:

    $ rperl -t -V LearningRPerl/Chapter1/exercise_1-hello_world.pl
    $ rperl -t -D LearningRPerl/Chapter1/exercise_1-hello_world.pl
    $ rperl -t -V -D LearningRPerl/Chapter1/exercise_1-hello_world.pl

2c. How do the outputs of these 3 commands differ from the output of Exercise 1?

2d. How do the outputs differ from one another?

3. Foo Bar Arithmetic [ 15 mins ]

Manually type the entire Foo Bar Arithmetic example program into a file named exercise_3-foo_bar_arithmetic.pl inside the LearningPerl/Chapter1 sub-directory. (Even if you have already used copy-and-paste on the Foo Bar Arithmetic example program, you should still use this as an opportunity to build some RPerl muscle memory and type it in by hand.)

Modify your program by adding a new floating-point numeric variable named $zab, set its value to $foo divided by $bar (don't forget to_number()), change the starting value of $bar, and use print to generate the following output:

    have $foo = 33
    have $bar = 966
    have $baz = 29.272_727_272_727_3
    have $zab = 0.034_161_490_683_229_8

Run your program thusly:

    $ rperl -t LearningRPerl/Chapter1/exercise_3-foo_bar_arithmetic.pl


CHAPTER 2: SCALAR VALUES & VARIABLES (NUMBERS & TEXT)

Most programming languages include the basic principles of using named "variables" to store data values such as numbers, text strings, and lists of multiple numbers or strings. Multiple variables may be created, each with different names such as $foo or $bar or $quux, and each potentially containing a different value.

A single piece of data, such as one number or one string, is called a "scalar". Multiple pieces of data combined into a single aggregate structure may be either an "array" or a "hash", described in chapters 3 and 6, respectively. (Although sharing the same terminology, the hash data structure is not related to the hash # tic-tac-toe character.) In normal Perl, only scalar variable names begin with the dollar sign $ "sigil", while aggregate data structures are stored in variables starting with different sigils like @ or %. In RPerl, all variable names begin the $ sigil, both scalar types and aggregate structures alike.

RPerl provides 7 scalar data types:

Of the 7 RPerl scalar data types, 3 are directly (natively) supported by the Perl 5 core: integer, number, and string. This means the Perl 5 core is capable of directly identifying and storing those 3 core types. The remaining 4 non-core types are indirectly supported by the Perl 5 interpreter: boolean and unsigned_integer can be stored within either an integer or number; character can be stored within a string; and gmp_integer is supported by the use bigint; wrapper around the Math::BigInt::GMP module.

When RPerl application source code is compiled from RPerl into C++, all 7 data types are natively supported by C++ for high-speed execution.

A single group of actual numeric digit(s) or quoted string character(s) is called a "literal", such as:

    -21         # integer or gmp_integer or number

    'howdy'     # string

    -23.421_12  # number

    1_234_567   # unsigned_integer or integer or gmp_integer or number

    1_234_567_890_123_456_789_012_345_678_901_234_567_890_123_456_789_012_345  # gmp_integer

    'One million, two-hundred-thirty-four thousand, five-hundred-sixty-seven'  # string

    '1'         # character or string

    'a'         # character or string

    "\n"        # newline character or string

    q{}         # empty character or string

    0           # boolean or unsigned_integer or integer or gmp_integer or number

Section 2.1: Numeric Data & Operators

RPerl provides 5 numeric data types:

Perl 5 provides several built-in operators designed for use with numeric data, which can be organized into 6 general categories:

Each operator in Perl 5 (and thus RPerl) is assigned 4 important characteristics: "arity" (a number), "fixity" (a placement location), "precedence" (a number) and "associativity" (a chirality or "handedness"). Operators of unary arity accept exactly 1 input operand, binary operators accept exactly 2 operands, etc. Prefix operators appear before their respective operands, postfix appear after, infix appear between, and closed operators appear both before and after their operands. Operators with a lower numeric precedence are executed before operators with a higher precedence; in the absence of parentheses, multiplication executes before addition because multiplication has a lower precedence number. Operators with equal precedence number are grouped by (and executed in order of) associativity; in the absence of parentheses, multiple subtraction operators will execute from left to right because subtraction is left-associative, whereas multiple exponent operators will execute from right to left because exponentiation is right-associative. For more information, see the Appendix:

"D.3: Syntax Arity, Fixity, Precedence, Associativity"

Beyond the built-in math operators in Perl 5, more advanced operators and functions are available via the MathPerl software suite, which is (perhaps unsurprisingly) optimized using the RPerl compiler.

MathPerl on CPAN

Section 2.1.1: Boolean Literals

The most memory-efficient numeric literal is boolean, which represents a single "bit" (binary digit) of information. A boolean literal may only give the values of exactly 0 or 1.

    0     # boolean
    1     # boolean
    -1    # not a boolean
    1.5   # not a boolean
    -1.5  # not a boolean

Section 2.1.2: Unsigned Integer Literals

The second most efficient numeric literal is unsigned_integer, which represents a single whole (non-decimal) number greater than or equal to 0. An unsigned_integer literal may describe any positive whole number, within the data size limits of the data types supported by your operating system software and computer hardware. An unsigned_integer may not describe a negative number or a non-whole number.

    23      # unsigned_integer
    0       # unsigned_integer
    42_230  # unsigned_integer
    -23     # not an unsigned_integer
    42.1    # not an unsigned_integer
    999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # bad unsigned_integer, outside data type limits

Section 2.1.3: Integer Literals

The third most efficient numeric literal is integer, which represents a single whole (non-decimal) number. An integer literal may describe any positive or negative whole number, within your operating system and hardware data type limits.

    -23     # integer
    0       # integer
    42_230  # integer
    42.1    # not an integer
    -999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # bad integer, outside data type limits

Section 2.1.4: GMP Integer Literals

The GNU Multi-Precision (GMP) software library is utilized to provide the gmp_integer numeric literal, representing a single whole (non-decimal) number which may safely exceed the data type limits of your operating system and hardware. A gmp_integer literal may describe any positive or negative whole number, within the limits of the memory (real or virtual) available to your RPerl code.

    -23     # gmp_integer
    0       # gmp_integer
    42_230  # gmp_integer
    42.1    # not a gmp_integer
    -999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999  # gmp_integer

Section 2.1.5: Number Literals

The number numeric literal represents a single floating-point (decimal) number, and may express any real number within your computer's data type limits.

    -23.42     # number
    0.000_001  # number
    42.23      # number
    42         # number
    -4_123.456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456  # bad number, outside data type limits

Section 2.1.6: Underscore Digit Separators

For unsigned_integer, integer, gmp_integer, and number literals, an "underscore" _ character must be inserted after every third digit away from the decimal point, where the underscore is used in a similar manner as a comma when writing long numbers by hand.

    1_234_567  # integer, same as "1,234,567" in American notation
    -32_123    # integer, same as "-32,123" in American notation
    -32123     # bad integer, missing underscore

    1.234_567           # number, same as "1.234567" in American notation
    -32_123.456_789_01  # number, same as "-32,123.45678901" in American notation
    -32_123.456_78901   # bad number, missing underscore

Section 2.1.7: Optional Positive Sign

For unsigned_integer, integer, gmp_integer, and number literals, an optional + plus sign may be prepended to explicitly indicate a numeric literal is positive (greater than zero).

    1   # positive one
    +1  # also positive one

BEST PRACTICES

  • When only positive numeric literals are used in one area of code, omit positive signs.
  • When both positive and negative literals are used in one code area, use signs for all applicable literals.
    +23    # NOT BEST PRACTICE: not aligned with other unsigned literal below
    +55.6  # NOT BEST PRACTICE: not aligned with other unsigned literal below
    42

    23     #     BEST PRACTICE:     aligned with other unsigned literal below, best for all-positive literals
    55.6   #     BEST PRACTICE:     aligned with other unsigned literal below, best for all-positive literals
    42

    23     # NOT BEST PRACTICE:      not aligned with other signed literals below
    55.6   # NOT BEST PRACTICE:      not aligned with other signed literals below
    -21
    -66.5

     23    # NOT BEST PRACTICE: manually aligned with other signed literals below, but will not automatically align via Perl::Tidy
     55.6  # NOT BEST PRACTICE: manually aligned with other signed literals below, but will not automatically align via Perl::Tidy
    -21
    -66.5

    +23    #     BEST PRACTICE:          aligned with other signed literals below, best for mixed-sign literals
    +55.6  #     BEST PRACTICE:          aligned with other signed literals below, best for mixed-sign literals
    -21
    -66.5

Section 2.1.8: Scientific Notation

For unsigned_integer, integer, and number literals, very large or very small numbers may be approximated using "scientific notation", where each number is normalized to have exactly one digit to the left of the decimal point, then a lower-case e character and an appropriate integer power-of-ten is appended to the resulting normalized floating-point number. The e character stands for "exponent", as in "exponent of ten", and the Perl style of scientific notation is sometimes more accurately referred to as "scientific e notation".

As with normal integers, negative exponents must be prefixed with a - minus sign and positive exponents may be optionally prefixed with a + plus sign.

    1_234_567_000     # good integer
    1.234_567_000e09  # good number, same as "1_234_567_000" in scientific notation

    0.001_234_567_000  # good number
    1.234_567_000e-03  # good number, same as "0.001_234_567_000" in scientific notation

    -0.000_000_000_000_000_000_000_001_234_567  # bad number, outside data type limits
    -1.234_567e-24  # good number, same as "-0.000_000_000_000_000_000_000_001_234_567" in scientific notation

BEST PRACTICES

  • Use 2 digits to represent all exponents.
  • When only positive exponents are used, omit exponent signs.
  • When both positive and negative exponents are used, use signs for all exponents.
    1_234_567_000      # NOT BEST PRACTICE: no exponent
    1.234_567_000e9    # NOT BEST PRACTICE: not aligned with two-digit exponents below
    1.234_567_000e+09  # NOT BEST PRACTICE: not aligned with two-digit exponents below
    1.234_567_000e09   #     BEST PRACTICE:     aligned with two-digit exponents below, best for all-positive exponents
    1.234_567_000e19
    2.111_000_333e04

    1.234_567_000e09   # NOT BEST PRACTICE: not aligned with signed exponents below
    1.234_567_000e+09  #     BEST PRACTICE:     aligned with signed exponents below, best for mixed-sign exponents
    1.234_567_000e-09
    2.111_000_333e-04

    # accuracy of following numbers may be reduced on computers with lower precision data types
    +1.537_969_711_485_091_65e+21  # BEST PRACTICE: best for mixed-sign exponents
    -2.591_931_460_998_796_41e+01  # BEST PRACTICE: best for mixed-sign exponents
    +1.792_587_729_503_711_81e-01  # BEST PRACTICE: best for mixed-sign exponents
    +2.680_677_724_903_893_22e-03  # BEST PRACTICE: best for mixed-sign exponents
    +1.628_241_700_382_422_95e-03  # BEST PRACTICE: best for mixed-sign exponents
    -9.515_922_545_197_158_70e-15  # BEST PRACTICE: best for mixed-sign exponents

Section 2.1.9: Truth Values

In the most simple case, a "truth value" may be represented by a boolean literal where the numeric value of 0 represents the truth value of "false", and numeric 1 represents "true". In general, a truth value is any data which may be recognized by Perl (and thus RPerl) as being either true or false; there is no third option.

Perl recognizes relatively few values as false, of which only 4 are accepted by RPerl:

      0   # false, number zero
     '0'  # false, text   zero
    q{0}  # false, text   zero
    q{}   # false, text   empty

All other values which RPerl accepts are recognized to hold a truth value of true.

All numeric operators in the comparison and logic sub-categories, as well as all string operators in the comparison sub-category, will generate truth values as output.

Perl attaches magic to the truth value of false, allowing it be utilized as either a normal truth value, or a numeric value of 0, or an empty string value of q{}. This magic behavior is not supported by C++, and thus not supported by RPerl.

In C and C++, only numeric 0 is universally recognized as false, while the text 0 and empty text are recognized as true, which is different than Perl. To achieve compatibility, RPerl automatically inserts additional C++ logic in all compiled output code to check for the 2 remaining RPerl false values of text character zero '0' or q{0}, and empty text q{}. This ensures the compiled C++ output code will behave identically to the original RPerl input source code, with regard to truth values.

WARNING FOR ALL COMPARISON & LOGIC OPERATORS:

Due to Perl's magic attached to truth values of false, as well as the difference between Perl and C++ recognized truth values, you may experience unexpected or undefined behavior if a truth value is utilized anywhere except true-or-false conditions in loops and conditional statements.

Only utilize the truth values returned by comparison and logic operators within the condition enclosed by parentheses in if (), elsif (), for (), or while ().

    if    (1 > 2)     { print 'I think not', "\n"; }  # good use of greater-than operator
    elsif ($x and $y) { print 'Maybe',       "\n"; }  # good use of          and operator

    for   (my integer $i = 0; $i < 23; $i++) { print 'finite loop',   "\n"; }  # good use of less-than operator
    while (                    1 != 2      ) { print 'infinite loop', "\n"; }  # good use of not-equal operator

    my integer $foo = 3 + (1 >= 2);   # UNEXPECTED BEHAVIOR: bad use of greater-than-or-equal operator
    my integer $bar = 3 * (1 <= 2);   # UNEXPECTED BEHAVIOR: bad use of    less-than-or-equal operator
    my integer $bat = sin (1 == 2);   # UNEXPECTED BEHAVIOR: bad use of                 equal operator

Section 2.1.10: Floating-Point Error

A "floating-point number" is any number which includes a decimal point . as part of the numeric representation, as opposed to an integer which does not include a decimal point. In RPerl, all floating-point values are stored in variables of the data type number.

       0  # integer
       1  # integer
    -123  # integer
    
       0.1    # floating-point
       1.654  # floating-point
    -123.4    # floating-point
    
    my integer $some_int   = 23;     # integer variable
    my number  $some_float = 23.42;  # floating-point variable

All computer languages which perform calculations on floating-point numbers are susceptible to "floating-point error", which is any inaccuracy due to incorrect rounding or lack of available precision.

For example, suppose you have a floating-point number 0.105, which seems normal enough. Let us further suppose you want to divide 0.105 by some other number, say 1_000, and by the simple rules of arithmetic you would expect to arrive at an answer of 0.000_105. Unfortunately, due to the way floating-point numbers are stored in computer memory, the actual result is closer to 0.000_104_999, so 0.000_105 happens to be one of many possible floating-point errors.

           (0.105 / 1_000) == 0.000_105    # UNEXPECTED BEHAVIOR: false
    print ((0.105 / 1_000) -  0.000_105);  # UNEXPECTED BEHAVIOR: -1.355_252_715_606_88e-20

It will usually not be possible to easily predict when and where floating-point error will occur. In general, you may experience the effects of floating-point error whenever your code relies upon one or more of the following:

To compensate for unpredictable floating-point error, you should use the "floating-point epsilon" value stored in the constant RPerl::EPSILON(), which is a very small number used to help detect inaccuracies. Whenever you want of directly compare two floating-point values, instead use the subtraction - and absolute value abs operators to take the positive difference, then use the less-than < operator to compare the difference to the floating-point epsilon value. If the difference is less than the floating-point epsilon, then the two input floating-point values can be considered to be numerically equal.

                                         RPerl::EPSILON()  # A VERY SMALL NUMBER: 0.000_000_000_000_000_2
         (0.105 / 1_000) == 0.000_105                      # UNEXPECTED BEHAVIOR: false
    abs ((0.105 / 1_000) -  0.000_105) < RPerl::EPSILON()  #   EXPECTED BEHAVIOR: true

    my number $foo = 0.105 / 1_000;
    my number $faa = 0.105 / 1_000;
    my number $bar = 0.000_105;
    my number $bat = 0.000_105;
         if (0.000_105 == 0.000_105)             { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
         if ((0.105 / 1_000) == (0.105 / 1_000)) { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
         if ($bar == $bat)                       { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
         if ($foo == $faa)                       { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true
         if ($foo == $bar)                       { print 'true'; } else { print 'false'; }  # UNEXPECTED BEHAVIOR: false
    if (abs ($foo -  $bar) < RPerl::EPSILON())   { print 'true'; } else { print 'false'; }  #   EXPECTED BEHAVIOR: true

WARNING FOR ALL FLOATING-POINT NUMERIC OPERATORS:

Due to floating-point error, unexpected behavior may be experienced if a floating-point value is tested for exact equality with any other value.

Always use the floating-point epsilon value RPerl::EPSILON() to check for approximate equality instead of exact equality.

Section 2.1.11: Arithmetic Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Absolute Value

abs

Unary

Prefix

01

Left

Coming Soon

Natural Exponential Function

exp

Unary

Prefix

01

Non

Coming Soon

Exponent AKA Power

**

Binary

Infix

04

Right

Yes

Negative with Parentheses

-( )

Unary

Closed

05

Right

Yes

Multiply

*

Binary

Infix

07

Left

Yes

Divide

/

Binary

Infix

07

Left

Yes

Modulo AKA Modulus

%

Binary

Infix

07

Left

Yes

Add

+

Binary

Infix

08

Left

Yes

Subtract

-

Binary

Infix

08

Left

Yes

Natural Logarithm

log

Unary

Prefix

10

Non

Coming Soon

Square Root

sqrt

Unary

Prefix

10

Non

Coming Soon

Section 2.1.12: Trigonometry Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Arctangent-Divide

atan2

Binary

Prefix

01

Left

Coming Soon

Sine

sin

Unary

Prefix

10

Non

Coming Soon

Cosine

cos

Unary

Prefix

10

Non

Coming Soon

Section 2.1.13: Comparison (Relational & Equality) Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Less-Than

<

Binary

Infix

11

Non

Yes

Greater-Than

>

Binary

Infix

11

Non

Yes

Less-Than-Or-Equal

<=

Binary

Infix

11

Non

Yes

Greater-Than-Or-Equal

>=

Binary

Infix

11

Non

Yes

Equal

==

Binary

Infix

12

Non

Yes

Not-Equal

!=

Binary

Infix

12

Non

Yes

Three-Way Comparison AKA Spaceship

<=>

Binary

Infix

12

Non

Coming Soon

Section 2.1.14: Logic Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Logical Negation

!

Unary

Prefix

05

Right

Yes

Logical And

&&

Binary

Infix

15

Left

Yes

Logical Or

||

Binary

Infix

16

Left

Yes

Logical Negation

not

Unary

Prefix

22

Right

Yes

Logical And

and

Binary

Infix

23

Left

Yes

Logical Or

or

Binary

Infix

24

Left

Yes

Logical Xor

xor

Binary

Infix

24

Left

Yes

Section 2.1.15: Bitwise Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Bitwise Negation with Parentheses

~( )

Unary

Closed

05

Right

Yes

Bitwise Shift Left

<<

Binary

Infix

09

Left

Coming Soon

Bitwise Shift Right

>>

Binary

Infix

09

Left

Coming Soon

Bitwise And

&

Binary

Infix

13

Left

Coming Soon

Bitwise Or

|

Binary

Infix

14

Left

Coming Soon

Bitwise Xor

^

Binary

Infix

14

Left

Coming Soon

All code examples are shown using 64-bit integers; your results may vary depending upon your C++ compiler and hardware platform.

WARNING FOR ALL BITWISE OPERATORS:

Due to the difference between how integer and non-integer scalar values are stored in memory, you may experience unexpected or undefined behavior if a bitwise operator is passed any non-integer operands as input.

Only utilize bitwise operators with integer, unsigned_integer, or boolean operands.

    ~(1)      # good use of bitwise negation    operator
    12 << 2   # good use of bitwise shift left  operator
    13 >> 3   # good use of bitwise shift right operator

    my unsigned_integer $foo = 14;
    $foo & 4  # good use of bitwise and operator
    $foo | 5  # good use of bitwise  or operator
    $foo ^ 6  # good use of bitwise xor operator

    my number $bar = 21.12;
    ~($bar)         # UNEXPECTED BEHAVIOR: bad use of bitwise negation    operator
      $bar <<    7  # UNEXPECTED BEHAVIOR: bad use of bitwise shift left  operator
         8 >> $bar  # UNEXPECTED BEHAVIOR: bad use of bitwise shift right operator

    23.42 &   9   # UNEXPECTED BEHAVIOR: bad use of bitwise and operator
    23    ^ 1.1   # UNEXPECTED BEHAVIOR: bad use of bitwise xor operator

Also, due to the difference between how signed and unsigned integer values are stored in memory, both Perl's use integer; pragma configuration command as well as RPerl's integer and unsigned_integer data types must be utilized in correct combination, as described below. Perl relies on the use integer; pragma to determine numeric data types, while C++ relies on the actual data types provided by the software developers as part of each variable declaration. You may experience unexpected behavior if a bitwise operator is utilized with mismatching pragma and data types.

Each call to Perl's use integer; pragma applies to 1 entire RPerl source code file at a time, either 1 full *.pl program file or 1 full *.pm module file. If the use integer; pragma is in effect for a specific RPerl file, then all bitwise operators in said file must be provided with input operands which are signed (positive or negative) integers only, not unsigned integers or floating-point numbers or other data types. If use integer; is not in effect for an RPerl file, then all bitwise operators in said file must be provided with operands which are unsigned (non-negative) integers or booleans only, not signed integers or other data types.

The use integer; pragma also affects the results of all arithmetic and comparison operators by discarding the non-integer (fractional) portion of input operands, as if the floor operator were called to convert each floating-point number into an integer. Because of this, floating-point operators and signed integer bitwise operators must not be included in the same single RPerl source code file; to compensate, simply move all signed bitwise operators into their own separate RPerl *.pm module file which calls use integer;.

Please see the Perl documentation for more information about the use integer; pragma:

http://perldoc.perl.org/integer.html

    # good combination: no 'use integer;' pragma, 
    # unsigned_integer data types for bitwise negation operator, number data type for multiplication operation
    my unsigned_integer $foo = 5;
    my unsigned_integer $bar = ~($foo);  # $bar  = 18_446_744_073_709_551_610
    my number $quux = 21.12 * 42.23;     # $quux = 891.897_6

    # good combination: 'use integer;' pragma,
    # integer data types for both bitwise negation operator and multiplication operator
    use integer;
    my integer $foo = 5;
    my integer $bar = ~($foo);   # $bar  = -6
    my integer $quux = 21 * 42;  # $quux =  882

    # bad combination: no 'use integer;' pragma, 
    # integer data types for bitwise negation operator
    my integer $foo = 5;
    my integer $bar = ~($foo);   # UNEXPECTED BEHAVIOR: ($bar = 18_446_744_073_709_551_610) in Perl, but ($bar = -6) in C++

    # bad combination: 'use integer;' pragma,
    # unsigned_integer data types for bitwise negation operator, number data type for multiplication operator
    use integer;
    my unsigned_integer $foo = 5;
    my unsigned_integer $bar = ~($foo);  # UNEXPECTED BEHAVIOR: ($bar = -6) in Perl, but ($bar = 18_446_744_073_709_551_610) in C++
    my number $quux = 21.12 * 42.23;     # UNEXPECTED BEHAVIOR: ($quux = 882) in Perl, but ($quux = 891.897_6) in C++

Section 2.1.16: Miscellaneous Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Floor with Parentheses

POSIX::floor( )

Unary

Closed

01

Left

Coming Soon

Ceiling with Parentheses

POSIX::ceil( )

Unary

Closed

01

Left

Coming Soon

Separate Integer & Fraction Parts with Parentheses

POSIX::modf( )

Binary

Closed

01

Left

Coming Soon

Integer Part

int

Unary

Prefix

10

Non

Coming Soon

Random Number

rand

Nullary or Unary

Prefix

10

Non

Coming Soon

Random Seed

srand

Nullary or Unary

Prefix

10

Non

Coming Soon

Section 2.2: Text Data & Operators

RPerl provides 2 text data types:

RPerl provides 3 delimiters for enclosing text data:

Perl 5 provides several built-in operators designed for use with text data, which can be organized into 7 general categories:

Section 2.2.1: Character Literals

The most memory-efficient text literal is character, which represents exactly zero characters or one character of information. A character may express the value of any single numeric digit (0, 1, 2, ..., 8, 9); letter (a, b, c, ..., y, z, A, B, C, ..., Y, Z ); or special ASCII character (!, #, *, +, etc). If the character literal has length zero, meaning it represents zero characters of information, then it is called the "empty character" and contains no data.

    ''           # INVALID: use q{} for empty character
    '0'          #   VALID
    'h'          #   VALID
    '+'          #   VALID
    '\n'         # INVALID: too many characters, use "\n" for newline character
    '-1'         # INVALID: too many characters
    'howdy23!'   # INVALID: too many characters

    ""           # INVALID: use q{} for empty character
    "0"          #   VALID
    "h"          #   VALID
    "+"          #   VALID
    "\n"         #   VALID: newline
    "-1"         # INVALID: too many characters & invalid use of double quotes
    "howdy23!"   # INVALID: too many characters & invalid use of double quotes

    q{}          #   VALID: empty
    q{0}         #   VALID
    q{h}         #   VALID
    q{+}         #   VALID
    q{\n}        # INVALID: too many characters, use "\n" for newline character
    q{-1}        # INVALID: too many characters
    q{howdy23!}  # INVALID: too many characters

Section 2.2.2: String Literals

Any text data more than 1 character in length must be represented by a string literal, which is comprised of any combination of valid character literal characters (numeric digits, letters, and special ASCII characters). Like the empty character, if a string literal has length zero then it is called the "empty string" and contains no data.

    ''           # INVALID: use q{} for empty string
    '0'          #   VALID
    'h'          #   VALID
    '+'          #   VALID
    '\n'         # INVALID: not a newline, use "\n" for string containing newline
    '\\n'        #   VALID: interpolated to become two characters (backslash, letter n)
    '-1'         #   VALID
    'howdy23!'   #   VALID

    ""           # INVALID: use q{} for empty string
    "0"          # INVALID: invalid use of double quotes, must contain newline or tab character(s)
    "h"          # INVALID: invalid use of double quotes, must contain newline or tab character(s)
    "+"          # INVALID: invalid use of double quotes, must contain newline or tab character(s)
    "\n"         #   VALID: interpolated to become newline character
    "-1"         # INVALID: invalid use of double quotes, must contain newline or tab character(s)
    "howdy23!"   # INVALID: invalid use of double quotes, must contain newline or tab character(s)

    q{}          #   VALID: empty string
    q{0}         #   VALID
    q{h}         #   VALID
    q{+}         #   VALID
    q{\n}        # INVALID: not a newline, use "\n" for string containing newline
    q{\\n}       #   VALID: interpolated to become two characters (backslash, letter n)
    q{-1}        #   VALID
    q{howdy23!}  #   VALID

Section 2.2.3: Single Quotes

Text literals enclosed in single quotes are the simplest and most common case in RPerl.

Single-quoted text literals are not "interpolated", which means the literal's data contents are not changed by Perl or RPerl in any way, except for the extra-special double backslash \\ as described below. Because single quotes do not activate string interpolation, you can not use a single-quoted string literal to represent special characters such as newline or tab.

Do not use single quotes to represent a newline or tab character, use double quotes "\n" or "\t" instead.

Do not use single quotes to represent an empty character or empty string, use q quotes q{} instead.

In normal Perl, single backslash characters \ are used to create special characters called "escape sequences", the most common of which are the well-known newline \n and tab \t escape sequences. Each valid escape sequence actually counts as only one character of computer data, even though it is represented to humans by 2 or more typed characters, so a single escape sequence may be utilized as either a character text literal or a string text literal. (Thus, "\n" and "\t" may both be utilized as either a character or string in RPerl, but only when using double quotes as discussed in the following section.)

In single-quoted string literals, the only escape sequence supported by RPerl is the double backslash \\, so the string literal '\\' is interpolated to mean only one single backslash character \. To represent two backslash characters \\, utilize two double backslash escape sequences in a row '\\\\'; for three backslashes \\\ utilize three escape sequences '\\\\\\', and so forth.

Because RPerl only accepts double backslashes (not single backslashes) within single quotes, RPerl thus does not accept any odd number of consecutive backslash characters within single quotes. For example, two or four backslashes in a row are supported, but one or three or five directly adjacent backslashes are not supported.

In normal Perl, the backslash single quote \' escape sequence may be used to include a single quote character ' within a single-quoted text literal. As stated above, RPerl only supports the double backslash \\ escape sequence within single quotes, so the backslash single quote \' escape sequence is thus not supported. Use double quotes "'" or q quotes q{'} to represent a single quote ' character in an RPerl string literal.

Single-quoted text literals must not contain:

Single-quoted text literals may contain:

    ''      # INVALID: empty string
    ' '     #   VALID: single space
    'a'     #   VALID: single letter
    '\'     # INVALID: single backslash

    '   '   #   VALID: three spaces
    ' ' '   # INVALID: single quote within single quotes
    '\' '   # INVALID: backslash single quote escape sequence, also single backslash

    ' a '   #   VALID: space, letter, space
    '"a}'   #   VALID: double quote, letter, right brace
    '\a}'   # INVALID: single backslash       not interpolated as audible bell (alarm beep) escape sequence
    '\n}'   # INVALID: single backslash       not interpolated as newline                   escape sequence
    '\\}'   #   VALID: double backslash           interpolated as one backslash character, right brace
    '\\\'   # INVALID: odd  number of backslashes 
    '\\\\'  #   VALID: even number of backslashes interpolated as half as many backslash characters

BEST PRACTICES

  • Use single-quoted text literals whenever possible.
    'n'      #     BEST PRACTICE
    "n"      # NOT BEST PRACTICE: double quotes not needed
    q{n}     # NOT BEST PRACTICE:      q quotes not needed

    '1atx'   #     BEST PRACTICE
    "1atx"   # NOT BEST PRACTICE: double quotes not needed
    q{1atx}  # NOT BEST PRACTICE:      q quotes not needed

    '\\tx'   #     BEST PRACTICE
    "\\tx"   # NOT BEST PRACTICE: double quotes    invalid, extra backslash
    q{\\tx}  # NOT BEST PRACTICE:      q quotes not needed

Section 2.2.4: Double Quotes

Text literals enclosed in double quotes are fully interpolated in normal Perl, and are only used for trivial interpolation of strings containing the newline "\n" or tab "\t" escape sequences in RPerl. All double-quoted strings in RPerl must contain at least one newline or tab special character.

In addition to escape sequences, string interpolation in normal Perl is also triggered by finding either the dollar sign $ or "at sign" @ characters inside of a double-quoted string literal. Because RPerl does not support string interpolation, double-quoted string literals must not contain the $ or @ characters.

Double-quoted string literals must not contain any backslash characters, other than those used in newline \n and tab \t escape sequences, and thus can not represent a single backslash character \; use single quotes '\\' or q quotes q{\\} double backslash escape sequences instead.

As with single quotes, in normal Perl the backslash double quote \" escape sequence may be used to include a double quote character " within a double-quoted text literal. As stated above, RPerl only supports the newline \n and tab \t escape sequences within double quotes, so the backslash double quote \" escape sequence is thus not supported. Use single quotes '"' or q quotes q{"} to represent a double quote " character in an RPerl string literal.

Double-quoted text literals must not contain:

Double-quoted text literals must contain 1 or more:

Double-quoted text literals may contain:

    ""      # INVALID: empty string
    " "     #   VALID: single space
    "a"     #   VALID: single letter
    "\"     # INVALID: extra  backslash,                                                                     only \n and \t supported

    "   "   #   VALID: three spaces
    " " "   # INVALID: double quote within double quotes
    "\" "   # INVALID: backslash double quote escape sequence, also single backslash

    " a "   #   VALID: space, letter, space
    "'a}"   #   VALID: single quote, letter, right brace
    "\a}"   # INVALID: single backslash           interpolated as audible bell (alarm beep) escape sequence, only \n and \t supported
    "\n}"   #   VALID: single backslash           interpolated as newline                   escape sequence, right brace
    "\\}"   # INVALID: extra  backslashes,                                                                   only \n and \t supported
    "\\\"   # INVALID: extra  backslashes,                                                                   only \n and \t supported 
    "\\\\"  # INVALID: extra  backslashes,                                                                   only \n and \t supported

BEST PRACTICES

  • Use double-quoted text literals to contain newline \n and tab \t characters only, not other normal characters.
  • To represent a mixture of normal characters with newline and/or tab characters, enclose the normal characters in single quotes, enclose the newline and tab characters in double quotes, and use the dot . "string concatenation" operator to append one string literal to the other. (Please see "Section 2.2.6: Editing Operators" for more information about string concatenation.)
    "\n"        #     BEST PRACTICE:     newline         only
    "\t"        #     BEST PRACTICE:                 tab only
    "\t\n\t"    #     BEST PRACTICE:     newline and tab only

    "a\n"       # NOT BEST PRACTICE: not newline and tab only
    'a' . "\n"  #     BEST PRACTICE:     newline         only, additional characters in single quotes

    "\tx"       # NOT BEST PRACTICE: not newline and tab only
    "\t" . 'x'  #     BEST PRACTICE:                 tab only, additional characters in single quotes

    "a\tx\n"                 # NOT BEST PRACTICE: not newline and tab only
    'a' . "\t" . 'x' . "\n"  #     BEST PRACTICE:     newline and tab only, additional characters in single quotes

Section 2.2.5: q Quotes

Text literals enclosed in "q quotes" begin with lowercase letter q and left "curly brace" characters q{, and end with the right curly brace } character. You must use q quotes to represent empty text q{} literals, which contain no characters. Curly braces are also known as "curly brackets" or just "braces" for short.

Normal Perl supports q-quoted string literals using delimiters other than curly braces, as well as "qq quotes" which provide string interpolation in the same way as double-quoted strings. RPerl's existing string quoting mechanisms cover all non-interpolated use cases, so RPerl does not support the additional qq quotes or non-curly-brace q quotes, because TDNNTBMTOWTDI.

q-quoted literals behave exactly the same as single-quoted literals, other than the empty string q{} and the difference in delimiters.

q-quoted text literals must not contain:

q-quoted text literals may contain:

    q{}      #   VALID: empty string
    q{ }     #   VALID: single space
    q{a}     #   VALID: single letter
    q{\}     # INVALID: single backslash

    q{   }   #   VALID: three spaces
    q{ } }   # INVALID: right brace within q quotes
    q{\} }   # INVALID: backslash right brace escape sequence, also single backslash

    q{ a }   #   VALID: space, letter, space
    q{"a'}   #   VALID: double quote, letter, single quote
    q{\a'}   # INVALID: single backslash       not interpolated as audible bell (alarm beep) escape sequence
    q{\n'}   # INVALID: single backslash       not interpolated as newline                   escape sequence
    q{\\'}   #   VALID: double backslash           interpolated as one backslash character, single quote
    q{\\\}   # INVALID: odd  number of backslashes 
    q{\\\\}  #   VALID: even number of backslashes interpolated as half as many backslash characters

BEST PRACTICES

  • Use q-quoted text literals to represent empty text literals only.
    ''      # NOT BEST PRACTICE: single quotes invalid, empty string
    ""      # NOT BEST PRACTICE: double quotes invalid, empty string
    q{}     #     BEST PRACTICE

    '0gnb'   #     BEST PRACTICE
    "0gnb"   # NOT BEST PRACTICE: double quotes not needed
    q{0gnb}  # NOT BEST PRACTICE:      q quotes not needed

    '\\nx'   #     BEST PRACTICE
    "\\nx"   # NOT BEST PRACTICE: double quotes    invalid, extra backslash
    q{\\nx}  # NOT BEST PRACTICE:      q quotes not needed

Section 2.2.6: Editing Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Substring

substr

Variadic

Prefix

01

Left

Coming Soon

Repeat

x

Binary

Infix

07

Left

Coming Soon

Concatenate

.

Binary

Infix

08

Left

Yes

Length

length

Unary

Prefix

10

Non

Coming Soon

Section 2.2.7: Case Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Lowercase

lc

Unary

Prefix

10

Non

Coming Soon

Lowercase First Character

lcfirst

Unary

Prefix

10

Non

Coming Soon

Uppercase

uc

Unary

Prefix

10

Non

Coming Soon

Uppercase First Character

ucfirst

Unary

Prefix

10

Non

Coming Soon

Section 2.2.8: Comparison (Relational & Equality) Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Less-Than

lt

Binary

Infix

11

Non

Coming Soon

Greater-Than

gt

Binary

Infix

11

Non

Coming Soon

Less-Than-Or-Equal

le

Binary

Infix

11

Non

Coming Soon

Greater-Than-Or-Equal

ge

Binary

Infix

11

Non

Coming Soon

Equal

eq

Binary

Infix

12

Non

Coming Soon

Not Equal

ne

Binary

Infix

12

Non

Coming Soon

Three-Way Comparison

cmp

Binary

Infix

12

Non

Coming Soon

Section 2.2.9: Search Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Index

index

Variadic

Prefix

01

Left

Coming Soon

Reverse Index

rindex

Variadic

Prefix

01

Left

Coming Soon

Section 2.2.10: Formatting Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

String Formatted Print

sprintf

Variadic

Prefix

01

Left

Coming Soon

Quote Meta

quotemeta

Unary

Prefix

10

Non

Coming Soon

Section 2.2.11: Base Conversion Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Chr

chr

Unary

Prefix

01

Left

Coming Soon

Hex

hex

Unary

Prefix

10

Non

Coming Soon

Oct

oct

Unary

Prefix

10

Non

Coming Soon

Ord

ord

Unary

Prefix

10

Non

Coming Soon

Section 2.2.12: Miscellaneous Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Crypt

crypt

Binary

Prefix

01

Left

Coming Soon

Section 2.3: RPerl´s Phases, Warnings & Errors

We will now take a break from numbers and strings and operators, in order to investigate the various stages of installing and running RPerl, as well as the most common issues you may encounter.

Like normal Perl, RPerl tries to generate helpful messages when something does not go as planned.

A "warning" occurs when something unexpected happens, but RPerl can continue on without being forced to end prematurely.

An "error" occurs when something unexpected happens, and RPerl must end immediately.

We will collectively refer to both warnings and errors as "problems", and we will refer to both warning messages and error messages as "problem messages".

There are 15 RPerl "phases", most of which are (hopefully unsurprisingly) termed as "compile phases". An RPerl phase is simply a distinct category of work to be done by RPerl or some other related software, and a compile phase is a category of work specifically related to compiling RPerl application source code.

All warnings and errors in RPerl fall within exactly 1 phase; technically, only those phases shown in bold contain problem messages generated by RPerl itself:

Section 2.3.1: Install, Base Dependencies

The first step toward using RPerl is installing RPerl, and the first step of installing RPerl is making sure you have a working copy of the Perl interpreter and a C++ compiler, as well as a few other base dependencies such as libc, libperl, ExtUtils::MakeMaker, GMP, cURL, and AStyle.

A "dependency" is one piece of software which another piece of software requires for proper functionality. One software component is thus said to "depend" upon a second software component, without which the first component would not work correctly. A "subdependency" is a dependency of a dependency. Each piece of software may require any number of dependencies, each of which may require any number of subdependencies, and so forth until all required software components have been loaded. For the purposes of the discussions in this book, the term "dependency" will inclusively refer to all of a specific software component's dependencies, subdependencies, sub-subdependencies, etc.

A "base dependency" is a software component required for RPerl to function, and is differentiated from a "CPAN dependency" because base dependencies are installed manually or via the operating system package manager instead of via the CPAN Perl software network, as detailed in the next section. If you have a modern operating system, you may already have most-or-all of these base dependencies either pre-installed or available for easy automatic install via pre-built packages; if not, you may need to manually install one or more of them. For more information on this phase of installation, please see:

"Section 1.16: How Can I Download & Install RPerl?"

Unique challenges may be posed by every different combination of operating system and hardware platform, because there are many different versions (and even variants) of each base dependency, with no way to predict your computer's behavior ahead of time. Also, the RPerl development team has little-to-no interaction with the developers of the base dependencies, so it is impossible to provide useful documentation of the countless possible problem messages which you may encounter in this phase.

Some common types of problem messages may include:

If you encounter any problems during this step, please consult your operating system's documentation or see:

"Section 1.18: How Can I Obtain Technical Support For RPerl?"

Section 2.3.2: Install, CPAN Dependencies

Perhaps the most complex part of installing RPerl is comprised of finding, building, testing, and installing all of the software needed for RPerl's dependencies (and subdependencies) via CPAN. A "CPAN dependency" is an RPerl dependency which is installed via the CPAN software network. Future versions of RPerl will provide easier pre-built installation packages for popular operating systems, such as those used in the base dependencies phase, but for now all (sub)dependencies must be downloaded from CPAN and custom-built for your operating system. Each individual piece of software downloaded from CPAN is called a "distribution", so RPerl itself is a CPAN distribution, and each of RPerl's CPAN (sub)dependencies is also a CPAN distribution.

We have tried to minimize the number of dependencies upon which RPerl relies, but even 1 dependency can itself have dozens or hundreds of subdependencies. RPerl is a relatively complex piece of software, with a moderate number of dependencies and (by association) a high number of subdependencies. If there is an error with even 1 of the numerous (sub)dependencies, it will either cause the RPerl installation to immediately terminate, or the installation will attempt to proceed in a partially-broken state, which will likely result in further errors when the broken software components are automatically tested.

CPAN promotes the use of a minimum version requirement for each (sub)dependency, which means RPerl will not use out-of-date software from CPAN, thereby avoiding a large number of known errors. However, there is much less emphasis on utilizing a maximum version requirement, so CPAN will always default to installing the latest public release of each (sub)dependency. It is the responsibility of the author of each (sub)dependency to ensure all public releases are stable, secure, and bug-free across a wide range of operating systems and hardware platforms, which is a constantly moving target for each software developer because new operating systems and hardware platforms are released all the time. This means the latest public release of any 1 specific CPAN distribution may remain stable for a long time, and then all-of-a-sudden it may become unstable when a new version of one of its own (sub)dependencies is released containing a bug or incompatibility. This further means the latest public release of the RPerl distribution on CPAN may work fine on your computer, then stop working properly if you update either the base dependencies or the CPAN dependencies.

There are 2 primary front-end applications used to install dependencies from CPAN, namely the `cpan` and `cpanm` commands, each of which has its own style of problem messages. In addition, there are unique problem messages which may be emitted by each individual CPAN distribution. As with the base dependencies in the previous RPerl install phase, there are countless possible problem messages you may encounter in this phase, none of which would be generated by RPerl itself.

Common problem messages in this phase may include:

Getting RPerl to work correctly does not simply require hitting a moving target, it requires hitting dozens of moving targets simultaneously. Most of the authors of CPAN distributions are volunteers, and software bugs happen even when the developers are well-paid, so don't be surprised if you encounter a problem during this phase. If you are convinced that you have found an as-yet undiscovered problem, please see:

"Section 1.18: How Can I Obtain Technical Support For RPerl?"

and

"Section 1.20: Are There Any Bugs In RPerl?"

The RPerl development team is in communication with the developers of several of the primary CPAN dependencies, so if you find a bug we may be able to help find the right people to fix it.

Section 2.3.3: Install, Test Suite

The final step of installing RPerl is to pass all tests in the RPerl automatic test suite, which can only occur after all base and CPAN dependencies are properly installed. The RPerl test suite includes a few thousand individual test cases, covering all parts of the RPerl compiler. If any of the RPerl tests fail or generate a problem message, then there may be a problem with RPerl itself, and we would very much appreciate your help by submitting a bug report:

"Section 1.20: Are There Any Bugs In RPerl?"

Common problem messages in this phase may include:

Section 2.3.4: Initialize, Bootstrap Subcompile

Each time the RPerl compiler is called, it may utilize a number of its own internal "helper function" components which are written using C++, so those components must first be compiled using a C++ compiler and linked to Perl 5 using Inline::CPP, during the "bootstrap subcompile" phase. In common English usage, "bootstrap" refers to "pull yourself up by your boot straps", which is the seemingly-impossible act of lifting one's self off the ground by pulling upward on one's shoes, and which means the ability to create something from nothing or to work some force upon one's own self. In compiler terminology, bootstrap means a compiler which can partially or fully compile itself, and is used as a measure of a compiler's long-term progress because only the most mature compilers can bootstrap. In this specific use of the term as part of the bootstrap subcompile phase, the term bootstrap means the need to use Inline::CPP to compile a small part of the RPerl compiler, which is then used to further compile other RPerl system and application code.

RPerl is a compiler, which itself utilizes 1 or more previously-existing compilers, the use of which we will call "subcompile" actions. The primary subcompile actions utilize the C++ compiler, because both "Initialize, Bootstrap Subcompile" and "Compile, Subcompile (Generate Binary)" are C++ subcompile phases. Only RPerl system developers will be exposed to the additional non-C++ subcompile actions.

Common problem messages in this phase may include:

Section 2.3.5: Initialize, Configuration

The second half of RPerl initialization involves the automatic configuration of multiple internal software settings. This phase is primarily comprised of setting the file and directory paths to important components of your operating system and of RPerl itself.

Common problem messages in this phase may include:

Section 2.3.6: Compile, Arguments & Files

RPerl is a compiler, so it is unsurprising that 9 of the 15 RPerl phases are compile phases. When a software developer (like you!) runs the RPerl compiler via the `rperl` command, the first compile phase checks the validity of the command-line arguments (AKA options) as well as the input source code file(s) to be compiled. Command-line arguments can be entirely omitted, in which case default behavior will be utilized. At least one input file must be specified, unless you are running `rperl -?` or `rperl -v` instead of a full RPerl compile command.

For details about all of RPerl's command-line arguments, please see Appendix B:

"APPENDIX B: RPERL COMMAND-LINE ARGUMENTS"

Common problem messages in this phase may include:

Section 2.3.7: Compile, Dependencies

Not to be confused with base dependencies in section 2.3.1 and CPAN dependencies in section 2.3.2, a normal RPerl "dependency" is one piece of RPerl application software which another piece of RPerl application software requires for proper functionality. Every RPerl application may have 0, 1, or any number of dependencies. As in normal Perl, an RPerl dependency is specified in source code via the use Some::Dependency; operator.

If your RPerl application has 1 or more dependencies, then RPerl must compile each dependency before it compiles your main RPerl application. If any of the dependencies rely upon subdependencies (and so forth), then each subdependency must be recursively checked for its own dependencies and they must all be compiled as well. In other words, before your main RPerl application can be compiled, RPerl must first compile all dependencies, subdependencies, etc. If the compilation of dependencies is disabled via the --nodependencies or --mode dependencies=OFF command-line arguments, or if there is a problem encountered while attempting to compile one of the dependencies, then compilation of your main RPerl program will also almost certainly experience a problem or total failure.

During this phase of compilation, RPerl makes a list of all dependencies which need to be compiled; however, the actual compiling of each dependency's source code input file does not occur until the following compile phases. This phase only produces an assessment of what files need to be compiled, and in what order.

Common problem messages in this phase may include:

Section 2.3.8: Compile, Parse Phase 0 (Check Perl Syntax)

This is the first phase where the input source code files are thoroughly checked for lexical and syntax errors. The term "parse" means to read through some structured data input such as human-readable plain-text source code, and a "full parse" results in the computer storing some "intermediate representation" (IR) which is a more computer-friendly encoding of the original source code. All 3 parse phases are full parses, although only the final intermediate representation is utilized by RPerl.

The normal Perl interpreter is called in "check syntax only" mode with all "strictures" enabled, as well as all warnings enabled and set to "fatal", via the `perl -M"warnings FATAL=q(all)" -Mstrict -cw`> command. Strictures are additional built-in rules which normal Perl can optionally apply during parsing a source code input file, and a fatal warning is essentially upgraded to become the same thing as an error because execution will terminate instead of continuing. All RPerl source code files are required to have strictures and (non-fatal) warnings enabled via the use strict; use warnings; statements, but RPerl won't check for the inclusion of those statements until the following parse phase 1 (criticize Perl syntax); thus, we make sure both strictures and warnings are automatically enabled in this step, in order to catch normal Perl errors sooner rather than later.

All problems encountered in this step are triggered by normal Perl, not by RPerl itself, and it is impractical to attempt to embed all pertinent Perl documentation within this RPerl documentation. Please utilize the following resources (in this order) to help reach a solution:

Common problem messages in this phase may include:

Section 2.3.9: Compile, Parse Phase 1 (Criticize Perl Syntax)

This phase of compilation checks the input source code files to make sure they all follow Perl "best practices" as originated in Damian Conway's book Perl Best Practices and implemented in Jeffrey Thalhammer's software Perl::Critic. A best practice is a rule or strategy which is commonly accepted by a professional community as being the most reliable and successful technique for approaching some specific task.

In this case, the professional community is our Perl computer programming community, and the Perl best practices themselves have been reduced to practice (get it?) by automatic source code checking via Perl::Critic and the PPI Perl pseudo-parser. In this phase of parsing, Perl::Critic is configured to operate in the most restrictive mode possible, which is called severity level 1, AKA "brutal" mode, and enables all possible Perl::Critic "policies" (rules). Although RPerl purposefully utilizes brutal mode, there are some Perl::Critic policies which either conflict with other policies (yes that's bad) or with RPerl itself. To compensate for this, RPerl application developers must selectively disable each problematic policy one-at-a-time using ## no critic statements, which are explained throughout this book where applicable. For a complete list of all accepted no-critic statements, please see Appendix C:

"APPENDIX C: RPERL CRITICS"

In addition, RPerl-specific best practices are included throughout this book where explicitly indicated, although the RPerl best practices are not currently checked or enforced in any way, and you should be careful not to confuse Perl best practices with RPerl best practices. It is assumed the RPerl application developers already have enough flaming hoops to jump through, in the form of the 3 existing RPerl parse phases, so RPerl best practices are not required, only suggested.

You may wish to purchase or download Damian Conway's book from our friends at O'Reilly Media, especially because its page numbers are referenced in this phase's error messages:

http://shop.oreilly.com/product/9780596001735.do

If you can't afford to purchase the book at this time, then you can still review a free list including all of Mr. Conway's Perl best practices in Johan Vromans' reference guide, although currently we have not yet made a mapping from policy numbers to the corresponding book page numbers:

http://rperl.org/docs/PBP_refguide-1.02.00.pdf

You will also likely want to refer to the list of Perl::Critic policies and the explanations thereof:

http://search.cpan.org/~thaljef/Perl-Critic/lib/Perl/Critic/PolicySummary.pod

Common problem messages in this phase may include:

Section 2.3.10: Compile, Parse Phase 2 (Parse RPerl Syntax)

The final parse phase of compilation utilizes RPerl's actual grammar to check the input source code files for valid RPerl syntax. The RPerl grammar implements a restricted subset of the normal Perl 5 language. This phase follows naturally from the previous parse phases: RPerl syntax (parse phase 2) is more restrictive than Perl::Critic brutal severity (parse phase 1), which is in turn more restrictive than normal Perl with fatal warnings and strictures enabled (parse phase 0), which is again more restrictive than normal lax Perl (not needed for RPerl parsing).

Some error messages may also include a "Helpful Hint" indicating a possible cause or solution; computer language parsing can be a very complicated process and there is no guarantee the hint is correct, so each hint should be taken with a grain of salt (a dose of healthy skepticism).

Full documentation of the RPerl grammar is provided in Appendix D:

"APPENDIX D: RPERL GRAMMAR"

Technical support for commercial RPerl users is provided by APTech, as detailed here:

"Section 1.18: How Can I Obtain Technical Support For RPerl?"

Free technical support for non-commercial users is provided by the RPerl community, as detailed here:

"Section 1.19: Are There Any Free Technical Support Options?"

Common problem messages in this phase may include:

Section 2.3.11: Compile, Generate (C++ Syntax)

After all parse phases of compilation have concluded, the original human-readable plain-text input source code files have been converted into an intermediate representation (IR) format known as an "abstract syntax tree" (AST), which exists in the computer's random-access memory (RAM or just "memory"), and which is more easily analyzed or modified by a computer.

Plain-text source code formats can be readily understood by trained humans, but are nearly impossible for computers to directly understand; compilers like RPerl exist for the sole purpose of converting source code into format(s) more easily understood by a computer. Intermediate representation formats such as RPerl's AST or normal Perl's "operation tree" (AKA "optree") or other languages' "bytecode" can be understood by humans and computers alike, but with a significant amount of difficulty for both. Binary code formats such as compiled executables or libraries can be readily understood by properly-configured computers, but are nearly impossible for humans to directly understand.

(The process of "decompiling" or "reverse engineering" the original human-readable source code from an optimized binary format is comparable to unscrambling an egg; it is currently considered nearly impossible to fully achieve, thus the act of compilation is considered to be one-way process and a strong protection against other people viewing your original source code or copying your intellectual property. You should be careful not to confuse decompiling with uncompiling: decompiling accepts as input a compiled binary file and then produces as output human-readable source code, while uncompiling accepts as input human-readable source code and then takes the action of deleting all compiled binary files which were produced from the source code during previous compilations using the same file names. Decompiling is not widely considered to be possible, while uncompiling is one of the more frequently utilized RPerl command-line arguments.)

During this phase of compilation, RPerl converts the AST format back into human-readable source code, but in the C++ language syntax (by default) instead of the RPerl language syntax. This is called the "generate" phase and is, in general, the exact opposite of a full parse phase; parsing converts from source code to IR, while generating converts from IR to source code. When configured to operate in test mode, RPerl does not generate C++ source code during this phase, but instead generates back into the exact same RPerl source code as the original input file. Test mode is thus able to check the generated RPerl source code to make sure it matches the original source code line-by-line, and also thereby "test" the RPerl parser's internal system code and "test" for the syntax correctness of the original source code, without the complexity of new C++ code becoming involved.

When compared to normal Perl, the 2 primary benefits of the RPerl compiler come from generating C++ source code: high-performance runtime speed optimization, and intellectual property source code protection. The act of converting from one human-readable computer language source code into another is compared to the similar act of converting from one spoken (or written) human language to another; this is called the "translate" process. When computer language translation is utilized as part of a compiler, the software is called a "transpiler" or "translating compiler". RPerl is a transpiler.

Common problem messages in this phase may include:

Section 2.3.12: Compile, Save Phase 0 (Final File Modifications)

NEED ADD CONTENT

Common problem messages in this phase may include:

Section 2.3.13: Compile, Save Phase 1 (Format & Write Files To Disk)

NEED ADD CONTENT

Common problem messages in this phase may include:

Section 2.3.14: Compile, Subcompile (Generate Binary)

NEED ADD CONTENT

Common problem messages in this phase may include:

Section 2.3.15: Execute

NEED ADD CONTENT

Common problem messages in this phase may include:

Section 2.4: Variables With Scalar Values

An RPerl "expression" is any general-purpose language component which either returns a value or is a literal value itself.

An RPerl "statement" is any general-purpose language component which performs some action(s).

An RPerl "named operator" is any of the 220+ Perl named operators, although RPerl only supports the low-magic forms of each operator.

An RPerl "operation" is the equivalent of a single sentence in human language, and may be either an expression followed by a ; semicolon punctuation character, or a named operator followed by a semicolon, or a statement.

The = equal sign is the assignment operator, used to set the variable on its left to store the value of the expression on its right.

Perl's my keyword is used to declare a new variable, and optionally initialize it to a starting value when combined with the = assignment operator.

Normal Perl does not support specific data types, so in Perl one variable named $foo may be initialized with a numeric value, then the same $foo variable may be changed to hold a string value without any warning or error.

    my $foo = 23;
    $foo = 'twenty-three';  # just fine in normal Perl

On the other hand, RPerl requires the use of data types for each and every variable.

    my $foo = 23;  # error in RPerl, all modes

    my number $foo = 23;
    $foo = 'twenty-three';  # error in RPerl, compiled (non-test) modes, assigning string literal to number variable

    my number $foo = 23;
    $foo = 42;  # just fine in RPerl

Normal Perl provides a special literal value undef, along with a built-in function named defined which is used to test if a variable contains the special undef value. RPerl does not support undef or defined, because C++ does not fully support the concept of undefined values, and RPerl's high-speed components are written using C++.

Data types make your code much more readable and much, much faster. Learn to love data types. Now. :-)

Section 2.4.1: How To Select Expressive Variable Names

Your choice of variable names will have a significant impact on the readability of your source code, whether written in Perl or any other programming language. If the names of your variables make sense, then it will be much easier for other programmers to understand your code. Also, good variable names will help you to understand your own code, after not looking at it for a few months or years. Variable names may include letters, numbers, and underscores.

BEST PRACTICES

You may not choose to utilize an all-uppercase variable name, because RPerl reserves that format for the names of constants; please see "Section 2.5: Constant Data" for more information. If you really insist, then RPerl will allow you to use mostly-uppercase variable names, as long as at least one lowercase letter is included. Also, instead of underscores you may choose to utilize "CamelCase" in order to separate words in your variable names. However, neither of these variable naming practices are recommended.

In addition to the best practices listed above, a good variable name should also fulfill all 3 of the following:

BEST PRACTICES

The first of these three best practices is for your variable names to be meaningful, so you should never actually choose $foo or $bar as your variable names, unless you are writing a programming textbook and need to make up a bunch of small stand-alone code examples. When first choosing a variable's name, take a moment and simply think of the most descriptive word or words which explain what it is you plan to use the variable for. Don't worry if your variable name starts out a bit too long, you can always shorten it later if appropriate.

The second best practice is for your variable names to be of medium length, so you should usually not choose either $r (too short) or $rounding_error_from_perl_arithmetic_operators (too long); instead, how about $rounding_error (just right)? To be fair, there are a number of commonly-accepted single-letter variable names including $i and $j and $k for loop iterators (see "Section 2.9.1: Loop Iterator Variables" for more info), as well as traditional mathematics variables such as $n (a "number" of items) and $x and $y and $z (Cartesian coordinates).

The third and final best practice is for your variable names to be simple, so you should usually choose $golden_ratio instead of $phi because more people will understand what the "golden ratio" is, and also the greek letter "phi" is ambiguous as it is traditionally used for multiple different mathematical purposes. On the other hand, most people will understand what you mean if you give a numeric variable the name $circumference, so you probably do not need to utilize the longer name $perimeter_length instead.

Try your best to choose good variable names, you will thank yourself for it later.

Section 2.4.2: Boolean Data Type

The most efficient data type is boolean, which is a numeric type which stores a single "bit" (binary digit) of information. A boolean may only hold the values of exactly 0 or 1.

    my boolean $foo = 0;     # fine
    my boolean $bar = 1;     # fine
    my boolean $baz = -1.5;  # error in RPerl, compiled (non-test) modes

Section 2.4.3: Unsigned Integer Data Type

The second most efficient numeric data type is unsigned_integer, which stores a single whole (non-decimal) number which must have a value of 0 or greater. An unsigned_integer may not hold a negative number, and must fit within the data size limits of the data types supported by your operating system software and computer hardware.

    my integer $foo  = -23;     # error in RPerl, compiled (non-test) modes
    my integer $bar  = 0;       # fine
    my integer $baz  = 42_230;  # fine
    my integer $bax  = 42.1;    # error in RPerl, compiled (non-test) modes
    my integer $quux = 999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999;  # likely error or data corruption, outside data type limits

Section 2.4.4: Integer Data Type

The third most efficient data type is integer, which stores a single whole (non-decimal) number. An integer may hold any positive or negative whole number, within your computer's data type limits.

    my integer $foo  = -23;     # fine
    my integer $bar  = 0;       # fine
    my integer $baz  = 42_230;  # fine
    my integer $bax  = 42.1;    # error in RPerl, compiled (non-test) modes
    my integer $quux = -999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999_999;  # likely error or data corruption, outside data type limits

Section 2.4.5: GMP Integer Data Type

The GNU Multi-Precision (GMP) library provides an arbitrary-precision integer data type which is accessible in RPerl as the gmp_integer type, and which does not need to fit within your computer's data type limits. All RPerl source code files which make use of GMP features must include the use rperlgmp; command. This tells RPerl to load the GMP library and other supporting software components, which are not normally loaded by the RPerl compiler.

The GMP integer data type works differently than the other normal data types, because a gmp_integer can be considered a combination of a normal integer data type and a special software component known as an "object". (Please see "CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES" for more information on objects.)

When we declare a new variable of the gmp_integer data type, there is a 2-part initialization procedure, as opposed to a normal variable which can be declared and initialized as part of a single RPerl statement. The first initialization statement is to declare our new gmp_integer variable and pre-initialize it with a special subroutine called a "constructor", which is achieved by calling gmp_integer->new() in your RPerl source code. The second initialization statement completes the procedure by calling one of the three following GMP initialization subroutines:

The gmp_init() subroutine sets the variable's value to a default of 0. The gmp_init_set_unsigned_integer() and gmp_init_set_signed_integer() subroutines set the variable's value to the provided numeric literal value. When you utilize the three example subroutine calls above, you should replace $new_gmp_var with the name of your own gmp_integer variable which has already been pre-initialized via gmp_integer->new(), and also replace POSITIVE_INTEGER_VALUE or INTEGER_VALUE with an actual numeric literal value.

In the source code example below, we create three new gmp_integer variables which are named $foo, $bar, and $baz, and which are initialized to the values of 0, 23, and -23 respectively.

    use rperlgmp;

    my gmp_integer $foo  = gmp_integer->new();
    my gmp_integer $bar  = gmp_integer->new();
    my gmp_integer $baz  = gmp_integer->new();

    gmp_init($foo);
    gmp_init_set_unsigned_integer( $bar, 23 );
    gmp_init_set_signed_integer( $baz, -23 );

Please see "Section 2.4.14: GMP Integer Operators" for more information.

Section 2.4.6: Number Data Type

The number data type stores a single floating-point (decimal) number, and may hold any real number within your computer's data type limit.

    my number $foo  = -23.42;     # fine
    my number $bar  = 0.000_001;  # fine
    my number $baz  = 42.23;      # fine
    my number $bax  = 42;         # fine
    my number $quux = -4_123.456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456_789_123_456;  # likely error or data loss, outside data type limits

Section 2.4.7: Character Data Type

The character data type stores a single text character, which may include any letter or number or special character, and which must not be empty.

    my character $empty = '';    # error in RPerl, compiled (non-test) modes, can't be empty
    my character $foo   = 'f';   # fine
    my character $bar   = q{b};  # fine
    my character $baz   = '7';   # fine
    my character $bax   = "\n";  # fine, newline counts as a single character
    my character $quux  = 'ab';  # error in RPerl, compiled (non-test) modes, too many characters

Section 2.4.8: String Data Type

The string data type stores one or more text characters, which may include any letter or number or special character, and which may be empty.

    my string $empty = '';         # fine
    my string $foo   = 'f';        # fine
    my string $bar   = q{bar};     # fine
    my string $baz   = '7baz';     # fine
    my string $bax   = "\n\n\t";   # fine, counts as 3 characters
    my string $quux  = 'abcdefg';  # fine

Section 2.4.9: Type Conversion

To convert from one data type to another, we use the RPerl data type conversion subroutines, which are automatically available for use in all RPerl source code. All 7 RPerl data types can be converted to any of the other 6 RPerl data types, so in total there are 42 type conversion subroutines. Remember the 7 RPerl data types are as follows:

The name and calling convention of each subroutine takes the form SOURCE_to_DESTINATION(INPUT), where SOURCE is replaced by the current data type from which you are converting, DESTINATION is replaced by the future data type to which you wish to convert, and the argument INPUT is replaced by the input data which should have the data type of SOURCE. Your INPUT can be any source of scalar data such as a variable, a literal, a constant, or a subroutine which returns a scalar value. The return value of each type conversion subroutine has a data type of DESTINATION, so if you want to store the newly-converted return value for later use, then you will need to make sure you utilize a variable with the correct type.

For example, if you want to convert from the input of a string variable named $foo to the output of a number data type, then you simply call string_to_number($foo). If you want to store the number return value of this type conversion, then you must utilize a variable of number type to do so. Thus, if you are providing a variable as the input argument for a type conversion subroutine, and if you are also storing the type conversion's return value in a variable, then these must always be two different variables because they will always have two different data types.

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils

    # [[[ OPERATIONS ]]]
    my string $foo = '723.555_777';
    my number $bar = string_to_number($foo);
    my number $double_bar = $bar * 2;
    print 'have $bar = ', number_to_string($bar), "\n";
    print 'have $double_bar = ', number_to_string($double_bar), "\n";

If we run our code example above, we should receive the following output, which correctly displays the underscore digit separator for long numbers:

    have $bar = 723.555_777
    have $double_bar = 1_447.111_554

BEST PRACTICES

If we do not call the number_to_string() subroutine before the values of $bar and $double_bar are processed by the print operator, then our output will be missing the proper underscore separators:

    print 'have $bar = ', $bar, "\n";                # no number_to_string(), not best practices
    print 'have $double_bar = ', $double_bar, "\n";  # no number_to_string(), not best practices

We no longer receive the exact output desired:

    have $bar = 723.555777
    have $double_bar = 1447.111554

In most cases, the shorthand subroutine to_string() may be used instead of one of the other SOURCE_to_string() type conversion subroutines. The special to_string() data type conversion subroutine will attempt to automatically detect the data type of the input argument value. We will receive the correct desired output if we replace number_to_string() with to_string() in our example above:

    print 'have $bar = ', to_string($bar), "\n";
    print 'have $double_bar = ', number_to_string($double_bar), "\n";

BEST PRACTICES

If the variable $foo was a number instead of a string, then RPerl would give an ERROR ECOPARP00 parse error and complain of Long number not separated with underscores. However, since $foo is of the string data type, then it is not checked for proper numeric underscores, and thus we can omit the underscore in the value of $foo without errors and with the proper output as seen above. However, this is not best practices, and we should consider the underscore to be missing in the following:

    my string $foo = '723.555777';  # no underscore, not best practices

Following is a list of all 42 RPerl data type conversion subroutines, not counting the special shorthand to_string() subroutine:

You must utilize type conversions when you are assigning the value of one variable to another variable of a different data type, otherwise you will have a type mismatch which will probably cause an RPerl sub-compile error. Be aware that you may experience data loss when converting to a data type capable of storing less information:

    my integer $foo = 23;
    my number $bar  = $foo;  # error in RPerl, compiled (non-test) modes, type mismatch

    my integer $foo = 23;
    my number $bar  = integer_to_number($foo);  # fine, $bar is now 23.0

    my number $foo  = 23.42;
    my integer $bar = $foo;  # error in RPerl, compiled (non-test) modes, type mismatch

    my number $foo  = 23.42;
    my integer $bar = number_to_integer($foo);  # fine, $bar is now 23, data loss has occurred

Section 2.4.10 Scope, Type, Name, Value

Every variable has 4 primary qualities, all of which are provided during variable initialization, in the following order:

The "scope" of a variable describes where in the source code the variable is valid and available for use, and does not change after your RPerl software starts to execute. In normal Perl, you will find a combination of locally-scoped variables which are declared the my keyword, globally-scoped variables declared using the our keyword, and state variables declared using the state keyword. (Old Perl 4 programmers also made use of the local keyword, now replaced by my.)

Local variables are only usable within their own enclosing code block, such as the body of a conditional statement, loop, or subroutine. If a local variable is declared in the main operations section of an RPerl program file, then it is considered to be outside of any code block, and it may only be utilized in the operations section of its own program file.

Global variables are usable within any code block accessible by Perl. Except for certain special variables such as our $VERSION, all variables in RPerl are locally-scoped using the my keyword. RPerl does not currently support state variables.

The "type" of a variable is simply the data type which is stored inside the variable, as described in detail throughout the preceeding subsections of "Section 2.4: Variables With Scalar Values". A variable's type must be set during declaration and may not be altered thereafter. Remember there are 7 scalar data types in RPerl: boolean, unsigned_integer, integer, gmp_integer, number, character, and string.

The "name" of a variable is the word or phrase you type after a dollar sign $ character, in order to access the variable. Like the scope and type, a variable's name may not be changed after the point of variable declaration, when the software begins execution. Closely related is the "namespace" of a variable, which is a named group of variables and constants and possibly other things; except where specified in "CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES", all RPerl variables exist outside of any namespace, which is to say that normal RPerl variables do not have a namespace.

The "value" of a variable is the actual data which has been stored inside of the variable, and which may be accessed or modified as your RPerl software is running. A variable's value must be compatible with its type, otherwise an error or undefined behavior may occur.

When your RPerl application is running in normal interpreted mode AKA test mode (Perl operations and Perl data types), then you will be able to access the special subroutines type(), types(), name() and scope_type_name_value(). These four subroutines provide the ability to perform "introspection" on RPerl variables, which means your RPerl application can access information about itself, specifically about its own variables. The types() subroutine is not used for scalar data types as discussed in this chapter, please see "CHAPTER 3: ARRAY VALUES & VARIABLES" and "CHAPTER 6: HASH VALUES & VARIABLES" for more information.

The following source code example shows a simple string variable named $foo (as usual), which we then pass as an argument to the introspection subroutines and display the results:

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils

    # [[[ OPERATIONS ]]]

    my string $foo = 'howdy';
    print 'have $foo = ', $foo, "\n";
    print 'have type($foo) = ', type($foo), "\n";
    print 'have name($foo) = ', name($foo), "\n";
    print 'have scope_type_name_value($foo) = ', "\n", scope_type_name_value($foo), "\n\n";

When this example is executed, the following output is produced:

    have $foo = howdy
    have type($foo) = string
    have name($foo) = $foo
    have scope_type_name_value($foo) = 
    my string $foo = 'howdy';

Section 2.4.11: Binary Assignment Operators

Often you will want to increase a numeric variable by some value, which can be achieved by calling the addition + operator, followed by the assignment = operator:

    $foo = $foo + 1;

We can shorten this example from two operators to only one by utilizing a "binary assignment operator", in this case the "plus-equals" += operator:

    $foo += 1;

We can achieve this effect for the four arithmetic operators addition +, subtraction -, multiplication *, and division /, as well as the string concatenation . operator. The right-hand side argument is not limited to numeric literals such as 1 in the above example, any expression can be utilized as long as it is of a compatible data type, as always.

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Add Assign

+=

Binary

Infix

19

Right

Coming Soon

Subtract Assign

-=

Binary

Infix

19

Right

Coming Soon

Multiply Assign

*=

Binary

Infix

19

Right

Coming Soon

Divide Assign

/=

Binary

Infix

19

Right

Coming Soon

String Concatenate Assign

.=

Binary

Infix

19

Right

Coming Soon

Section 2.4.12: Increment & Decrement Operators

Recall the example from the previous section, regarding the use of binary assignment operators, where we first see long-hand source code using two operators:

    $foo = $foo + 1;

Then we shorten from two operators to only one operator:

    $foo += 1;

Now, for the special case of incrementing by a hard-coded integer value of 1, we can shorten this example even further to eliminate the numeric literal. This is achieved by using the post-increment ++ operator:

    $foo++;

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Pre-Increment

++

Unary

Prefix

03

Non

Yes

Post-Increment

++

Unary

Postfix

03

Non

Yes

Pre-Decrement

--

Unary

Prefix

03

Non

Yes

Post-Decrement

--

Unary

Postfix

03

Non

Yes

    ++$i  # 0

Section 2.4.13: chop & chomp Operators

Often you will want to remove the special newline character "\n" from the end of a string variable, which can be achieved safely by using the chomp operator. When you pass some variable as the operand to chomp, the operator will do nothing if the operand's final character is not a newline. Chomp knows how to use the correct newline character for each operating system, thanks to Perl's magic $INPUT_RECORD_SEPARATOR variable.

    my string $foo = 'howdy' . "\n";
    print $foo;
    print $foo;

    chomp $foo;  # newline character removed
    print $foo;
    print $foo;

    chomp $foo;  # no effect
    print $foo;
    print $foo;

In the example source code above, only the first call to the chomp operator has an effect on the value of the $foo variable. When you run this example source code, you should receive the following output:

    howdy
    howdy
    howdyhowdyhowdyhowdy

Sometimes you will want to trim the final character of a string variable, regardless of whether it is a newline or any other specific character. For these cases, you will want to use the chop operator, which is likened to a non-safe variant of chomp. Obviously, chop and chomp actually perform two different operations, so you will always need to be careful and choose which operator to utilize on a case-by-case basis.

Let's modify the previous code example to use the chop operator instead of chomp:

    my string $foo = 'howdy' . "\n";
    print $foo;
    print $foo;

    chop $foo;    # newline character removed
    print $foo;
    print $foo;

    chop $foo;    # 'y' character removed
    print $foo;
    print $foo;

The trailing newline character is trimmed on the first call to chop, and then the final 'y' character of 'howdy' is deleted on the second call to the chop operator. This generates the following output, notice the missing 'y' characters:

    howdy
    howdy
    howdyhowdyhowdhowd

Section 2.4.14: GMP Integer Operators

The GMP library provides a large number of operators which are only for use with variables of the gmp_integer data type, and these GMP operators are made available in RPerl as subroutines which all begin with "gmp_". These GMP operator subroutines are loaded by the use rperlgmp; command.

gmp_integer_to_boolean gmp_integer_to_unsigned_integer gmp_integer_to_integer gmp_integer_to_number gmp_integer_to_character gmp_integer_to_string boolean_to_gmp_integer integer_to_gmp_integer unsigned_integer_to_gmp_integer number_to_gmp_integer character_to_gmp_integer string_to_gmp_integer

gmp_init gmp_init_set_unsigned_integer gmp_init_set_signed_integer

gmp_set gmp_set_unsigned_integer gmp_set_signed_integer gmp_set_number gmp_set_string gmp_get_unsigned_integer gmp_get_signed_integer gmp_get_number gmp_get_string gmp_add gmp_sub gmp_mul gmp_mul_unsigned_integer gmp_mul_signed_integer gmp_sub_mul_unsigned_integer gmp_add_mul_unsigned_integer gmp_neg gmp_div_truncate_quotient gmp_cmp

Section 2.5: Constant Data

Sometimes you have a piece of data that will never change once you compile your software, which is what we call "constant data" or just a "constant" for short.

Constants are the opposite of variables, because constants are designed not to change, while variables are designed to change as many times as needed.

Below is an example RPerl program with two constants, one containing numeric data and another containing text data:

    #!/usr/bin/perl
 
    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;
 
    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants
 
    # [[[ CONSTANTS ]]]
    use constant PI  => my number $TYPED_PI  = 3.141_59;
    use constant PIE => my string $TYPED_PIE = 'pecan';

These two constants can be utilized as follows:

    my number $area = PI() * $r ** 2;
    my string $dessert = 'having a nice slice of ' . PIE();

As seen in the examples above, we must first declare each constant to have an all-uppercase name via the use constant command, after which we can access the stored data value by calling the constant name followed by empty parentheses. (In normal interpreted Perl, a constant is functionally equivalent to a subroutine which accepts no arguments and performs no operations other than to call the return operator with a hard-coded data value; see "CHAPTER 4: ORGANIZING BY SUBROUTINES" for more information.)

In all RPerl source code files which contain constants, we must include the "USER DEFAULT 3" no critic command; for numeric constants, we must also include "USER DEFAULT 1", as seen in the code example above.

All constants must utilize names with uppercase-only lettering, in order to distinguish them from similarly-named variables. Thus, a normal variable may not have an all-uppercase name. (Special variables called "file handles" must be all-uppercase; see "CHAPTER 5: READING & WRITING FILES" for more information.)

    use constant PIE => my string $TYPED_PIE = 'peanut butter';  # fine
    use constant Pie => my string $TYPED_Pie = 'coffee cream';   # error in RPerl, compiled modes
    use constant pie => my string $TYPED_pie = 'mocha silk';     # error in RPerl, compiled modes

    my string $PIE = 'oreo';        # error in RPerl, compiled modes
    my string $Pie = 'blackberry';  # okay
    my string $pie = 'blueberry';   # best

The declaration of constants follows a purposefully-repetitive format starting with the use constant command, followed by the all-uppercase constant name, a fat arrow (AKA fat comma) =>, the my command, the desired data type, a variable named $TYPED_ with the same all-uppercase name appended, the equal-sign = assignment operator, and finally the desired data value with a closing semicolon. Within a constant declaration, the all-uppercase constant name must appear identically in both places, which is a language construct enabling us to provide a data type where it would otherwise be impossible to do so.

    use constant PIE => my string $TYPED_PIE = 'cherry';        # fine
    use constant PIE =>                        'black forest';  # error in RPerl, compiled modes
    use constant PIE => my string $TYPED_PI  = 'grasshopper';   # error in RPerl, compiled modes
    use constant PIE => my string $TYPED_POE = 'raven';         # error in RPerl, compiled modes

You may access the value of a constant as many times as you like, but you may never change the value once the software has been compiled.

    $pie = PIE();       # fine
    $pie = $PIE;        # error in RPerl, compiled modes
    $pie = $TYPED_PIE;  # error in RPerl, compiled modes

    PIE()      = 'chocolate bourbon';   # error in Perl and RPerl
    $PIE       = 'chocolate chip';      # error in RPerl, compiled modes
    $TYPED_PIE = 'death by chocolate';  # error in RPerl, compiled modes

Constant values must be literals and not other constants or variables.

    use constant PIE => my string $TYPED_PIE = 'banana cream';  # fine
    use constant PIE => my string $TYPED_PIE = PI();            # error in RPerl, compiled modes
    use constant PIE => my string $TYPED_PIE = $pie;            # error in RPerl, compiled modes

It is always possible to use a variable instead of a constant, but not the other way around. You should use constants whenever possible, because they will always be at least as fast as variables, and often faster!

                        my string $pie       = 'lemon meringue';  # okay
    use constant PIE => my string $TYPED_PIE = 'key lime';        # best

Section 2.6: Displaying Output Using The print Operator

You will often want to display some text output while your RPerl application is running, and for this we use the print operator:

    print 'Hello, world!', "\n";

Unsurprisingly, calling print as shown above will display the 13-character global greeting, followed by a special "newline" character which moves the computer cursor down to the next line. (The "n" in "\n" stands for "newline", which is very closely related to the concepts of "line feed", "carriage return", and pressing the "Enter" key on a computer keyboard. The history of these terms harkens back to the days of manual typewriters and is worth spending a few minutes to learn about on Wikipedia, if you are into that sort of thing.)

Multiple operands are passed to the print operator by separating them with commas. The above example passes 2 operands to be received by the print operator, first the greeting literal and second the newline character. You may pass as many operands to print as you like.

You can also print the contents of variables and constants. For example, the 3 operations below produce the exact same output as the 1 operation above:

    use constant NEWLINE => my string $TYPED_NEWLINE = "\n";
    my string $greeting = 'Hello, world!';
    print $greeting, NEWLINE();

Section 2.6.1: STDOUT & STDERR

When you call the print operator, it sends all output to the operating system's default output data stream, which is a special component called "standard output" or just "standard out" for short, written using the STDOUT keyword in Perl. You may explicitly specify STDOUT for any print operator, although this is not necessary because it is already the default behavior. When specified, the output stream has an asterisk * character prepended, and is then wrapped in curly braces.

So again, the following operation produces the exact same output as the 2 preceding examples:

    print {*STDOUT} 'Hello, world', "\n";

You will notice there is no comma after {*STDOUT}; you should only type a blank space character, and then specify the first operand. Other than that, the print operator works exactly the same both with and without the extra STDOUT included.

In addition to STDOUT, there is a second output data stream provided by your operating system, which is called "standard error" and is written using the STDERR keyword. This stream is used to display actual error and warning messages, as well as optional debugging and diagnostic information. The following operation will display an example warning message:

    print {*STDERR} 'WARNING: Danger, Will Robinson!', "\n";

Your software will continue running after you call print to send output to STDERR; if you want execution to immediately stop after displaying an error message, then you will need to explicitly add a termination operator such as exit or die or croak. The operand value of 1 passed to the exit operator below is used to inform the operating system that we have encountered an error. (Please see NEED_ADD_SECTION for more information.)

    print {*STDERR} 'ERROR: A fatal error or failure has occurred, aborting.', "\n";
    exit 1;

As mentioned above, you may also choose to use STDERR to display debugging and diagnostic messages, which are neither warnings nor errors. For example, let's say you are writing an RPerl application which primarily relies on the $foo variable, so your users want to see the value of $foo when the program is finished running. Your code also utilizes the secondary variables named $bar, $bat, and $baz, but the users don't care about the values of these variables, only you (and other software developers) care about them. Following is an example of using print for both normal output to STDOUT (by default), as well as diagnostic output to STDERR:

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils

    # [[[ OPERATIONS ]]]

    my number  $bar =    17.0;
    my number  $bat = 2_112.42;
    my integer $baz =    23;
    my number  $foo;

    print {*STDERR} 'before arithmetic, have $bar = ', number_to_string($bar), "\n";
    print {*STDERR} 'before arithmetic, have $bat = ', number_to_string($bat), "\n";
    print {*STDERR} 'before arithmetic, have $baz = ', integer_to_string($baz), "\n";

    $bat = $bar;
    $bar = $baz / ($bar * 3);
    $baz = $baz + 1;
    $foo = $bar + $bat;

    print '$foo = ', number_to_string($foo), "\n";

    print {*STDERR} 'after arithmetic, have $bar = ', number_to_string($bar), "\n";
    print {*STDERR} 'after arithmetic, have $bat = ', number_to_string($bat), "\n";
    print {*STDERR} 'after arithmetic, have $baz = ', integer_to_string($baz), "\n";

Now you may easily choose to view only the STDOUT, or STDERR, or both. Here we see a normal execution of the program with both output streams displayed:

    $ ./my_program.pl 
    before arithmetic, have $bar = 17
    before arithmetic, have $bat = 2_112.42
    before arithmetic, have $baz = 23
    $foo = 17.450_980_392_156_9
    after arithmetic, have $bar = 0.450_980_392_156_863
    after arithmetic, have $bat = 17
    after arithmetic, have $baz = 24

Next, we execute the same program again; this time we append > /dev/null after our program name, which discards all STDOUT output by redirecting it to a "null" or empty device. (In the Windows operating system, replace > /dev/null with > nul.) This results in only the STDERR output being displayed:

    $ ./my_program.pl > /dev/null
    before arithmetic, have $bar = 17
    before arithmetic, have $bat = 2_112.42
    before arithmetic, have $baz = 23
    after arithmetic, have $bar = 0.450_980_392_156_863
    after arithmetic, have $bat = 17
    after arithmetic, have $baz = 24

Lastly, we run the same program a third time, now with 2> /dev/null appended to discard all STDERR output, so we only see STDOUT:

    $ ./my_program.pl 2> /dev/null
    $foo = 17.450_980_392_156_9

It is easy to simply insert a hash character (AKA octothorpe) # in front of each print {*STDERR} operator to comment it out, thereby disabling the diagnostic output but allowing it to be re-enabled again by future developers:

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils

    # [[[ OPERATIONS ]]]

    my number  $bar =    17.0;
    my number  $bat = 2_112.42;
    my integer $baz =    23;
    my number  $foo;

    #print {*STDERR} 'before arithmetic, have $bar = ', number_to_string($bar), "\n";
    #print {*STDERR} 'before arithmetic, have $bat = ', number_to_string($bat), "\n";
    #print {*STDERR} 'before arithmetic, have $baz = ', integer_to_string($baz), "\n";

    $bat = $bar;
    $bar = $baz / ($bar * 3);
    $baz = $baz + 1;
    $foo = $bar + $bat;

    print '$foo = ', number_to_string($foo), "\n";

    #print {*STDERR} 'after arithmetic, have $bar = ', number_to_string($bar), "\n";
    #print {*STDERR} 'after arithmetic, have $bat = ', number_to_string($bat), "\n";
    #print {*STDERR} 'after arithmetic, have $baz = ', integer_to_string($baz), "\n";

Now we don't need any redirection on the command line to suppress STDERR output, and our program will run faster:

    $ ./my_program.pl
    $foo = 17.450_980_392_156_9

Section 2.7: Program Control Using The if Conditional Statement

Often you will want to perform a task, but only if some specific "condition" is met; this is called a "conditional statement" or just "conditional" for short, and is implemented using the if statement in Perl. You may also refer to the if statement as a "control structure", because it is a source code structure used to control the execution flow of a piece of Perl software. In other words, a conditional statement can control how your software runs, and so your software may run differently depending on your conditional statements.

Whether or not an if statement's task is actually performed is determined by the truth value of its condition, which is specified in the loop's "header", contained within parentheses immediately after the if keyword; please review "Section 2.1.9: Truth Values" for more information. The header of a conditional statement contains only its condition. The task to be conditionally performed is known as the conditional statement's "body", and is specified within curly braces immediately after the header.

    if ( $my_integer == 17 ) { print 'I got seventeen!', "\n"; }

We can read the source code above as "if the value of the variable $my_integer is equal to 17, then display the text 'I got seventeen!' followed by a newline character"; or for short we can just say "if $my_integer is 17, print 'I got seventeen!'". Note the use of the word "then" in the long-form translation; if statements are also commonly referred to as "if - then" statements, although in Perl the word "then" is not used in actual source code. We will include the word "then" in the translations below, for ease of comprehension.

Section 2.7.1: Conditional Chaining With if & elsif & else

So, what if you also want to perform a different task when your if statement's condition is evaluated as false? Then use the else keyword with its own body:

    if ( $my_integer == 17 ) { print 'I got seventeen!',         "\n"; }
    else                     { print 'I did not get seventeen.', "\n"; }

We can read the two lines of code above as "if $my_integer is 17, then print 'I got seventeen!'; or else print 'I did not get seventeen.'".

Now let's add a third check, to see if we match one more possible value of $my_integer before declaring that these aren't the values (or droids) we're looking for. The following three lines of code can be read as "if $my_integer is 17, then print 'I got seventeen!'; or else if $my_integer is 23, then print 'I got twenty-three!'; or else print 'I did not get either.'":

    if    ( $my_integer == 17 ) { print 'I got seventeen!',      "\n"; }
    elsif ( $my_integer == 23 ) { print 'I got twenty-three!',   "\n"; }
    else                        { print 'I did not get either.', "\n"; }

When at least one elsif or else statement is appended to an if statement, it is called a "conditional chain".

Now let's look at the output values of some slightly less simple conditional statements. For example, perhaps you want to increment the value of an integer stored in the variable named $heart, but only until it reaches a value of 3. You can achieve this (in a contrived manner) by executing the following RPerl program:

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils

    # [[[ OPERATIONS ]]]

    my integer $heart = 0;
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    if ( $heart < 3 ) { $heart++; }
    if ( $heart < 3 ) { $heart++; }
    if ( $heart < 3 ) { $heart++; }
    if ( $heart < 3 ) { $heart++; }

    print '$heart = ', $heart, "\n";

What do you think will be the generated output from the code above? Well here it is:

    $heart = 0
    $heart = 3

By studying the source code and output above, we can see there are five opportunities for the value of the $heart variable to be incremented via the ++ operator, but only three of them are actually executed. This is because the truth value of $heart < 3 is true while $heart is equal to 0, 1, and 2, but then the truth value of $heart < 3 becomes false once the value of $heart reaches 3. Obviously, a value of 3 is not less than another equal value of 3, so the final 2 truth values are false.

According to the generated output, it appears we have achieved our simple goal of incrementing $heart until it reaches 3, but it can be difficult to know exactly what is happening while the program is running. Let's add some print operators to display more useful output:

    my integer $heart = 0;
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    print '$heart = ', $heart, "\n";

Now we can see what's really going on:

    $heart = 0
    $heart = 1
    $heart = 2
    $heart = 3
    $heart = 3
    $heart = 3

From this more informative output, we can see the final two print operators are called, but the final two increment ++ operators are not called, so "$heart = 3" is repeated twice.

Each of the five if statements in the previous example are syntactically independent conditional statements, which means you can change any of their conditions without affecting the evaluation of the other conditions. In other words, all five conditions with all five less-than < operators are evaluated every time this program runs, even if only three of the five if statement bodies are executed. This is fine, because it is the correct behavior we want in this example.

Now let's say (for some odd reason) you want to chain three if statements together where they are now dependent upon one another, so if you change any one condition then it may affect the evaluation of the following condition(s). You can achieve this by changing the second and third if statements to be elsif statements instead:

    my integer $heart = 0;
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    elsif ( $heart < 3 ) { $heart++; }
    elsif ( $heart < 3 ) { $heart++; }

    print '$heart = ', $heart, "\n";

We can't include all the extra print operators because each elsif keyword must follow immediately after the preceding conditional body. Also, we can't link more than three if statements together without breaking the Perl Best Practices guideline against utilizing a "cascading if-elsif chain".

So what do you think the output will for the above conditional chain? Here you go:

    $heart = 0
    $heart = 1

This time only the first of the three increment ++ operators was executed, so the value of $heart only increased from 0 to 1. This is because an elsif statement's condition will automatically default to a truth value of false if any preceding if or elsif truth values in its conditional chain are evaluated as true. In other words, both elsif statements in this example were totally skipped or "short-circuited" without even evaluating their less-than < operators, because the condition of the starting if statement is evaluated as a true. It would literally be a waste of time to evaluate the second and third less-than operators, so our program will run a little bit faster by allowing Perl to automatically skip over those elsif statements completely.

Can you quickly tell what the output will be for the following example, where we have simply added an else statement?

    my integer $heart = 0;
    print '$heart = ', $heart, "\n";

    if ( $heart < 3 ) { $heart++; }
    elsif ( $heart < 3 ) { $heart++; }
    elsif ( $heart < 3 ) { $heart++; }
    else                 { $heart++; }

    print '$heart = ', $heart, "\n";

In this case, the same short-circuiting occurs for the else as does for the elsif statements in this and the previous example, so our output is unchanged:

    $heart = 0
    $heart = 1

The longest conditional chain allowable by Perl Best Practices is four members long and is comprised of an if statement, followed by two elsif statements, followed by an else statement, as seen in the example above. If all your conditions test a single variable for equivalence to some specific values, as in our first $my_integer examples in this section, then instead of a conditional chain you may be able to utilize a hash data structure with the keys pre-set to the possible matching values; please see "CHAPTER 6: HASH VALUES & VARIABLES" for more information.

If your conditions are not all simple equivalence tests via the equals == operator, as in our $heart examples where the conditions include less-than < operators, then Perl Best Practices directs us to use a given ... when statement instead of any if or elsif statements at all. However, RPerl does not yet support given ... when, so if it is unavoidable then you may disable the rule against cascading conditional chains for just one source code file at a time:

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    ## no critic qw(ProhibitCascadingIfElse)  # USER DEFAULT 9: allow cascading conditional chains until given-when is implemented
    
    # [[[ OPERATIONS ]]]
    
    my integer $foo = 0;
    print '$foo = ', $foo, "\n";
    
    if ( $foo < 3 ) { $foo++; }
    elsif ( $foo < 3 ) { $foo++; }
    elsif ( $foo < 3 ) { $foo++; }
    elsif ( $foo < 3 ) { $foo++; }
    else               { $foo++; }
    
    print '$foo = ', $foo, "\n";

As seen above, now we may add one or more additional elsif statements without triggering a Perl Best Practices violation error via Perl::Critic. This is achieved by the inclusion of the special "USER DEFAULT 9" no critic command, which disables the "ProhibitCascadingIfElse" policy. If we attempt to run this source code without the proper critic command, we will receive an error:

    $ rperl -t my_program.pl 
    ERROR ECOPAPC02, RPERL PARSER, PERL CRITIC VIOLATION
    Failed Perl::Critic brutal review with the following information:

        File Name:    ./lib/RPerl/Test/Conditional/program_08_bad_00.pl
        Line number:  22
        Policy:       Perl::Critic::Policy::ControlStructures::ProhibitCascadingIfElse
        Description:  Cascading if-elsif chain
        Explanation:  See Perl Best Practices page(s) 117, 118

However, with the proper "USER DEFAULT 9" no critic command in place, we receive no errors and the same output as before:

    $heart = 0
    $heart = 1

Section 2.7.2: Nested Conditionals

In all the examples above, the body of each conditional statement only includes one operation, such as a single increment ++ operator or a single print operator. However, the bodies of your conditional statements may include as many operations as you like. Also, conditional statements may be nested within one another:

    if ( $friend_enjoys_lasagna ) {
        if ( $other_lasagna_lovers_so_far == 0 ) {
            print 'Oh thank goodness, I thought I was the only one!', "\n";
        }
        elsif ( $other_lasagna_lovers_so_far == 1 ) {
            print 'Well, at least there are a few of us...', "\n";
        }
        else {
            print 'Welcome to the Lasagna Lovers club!', "\n";
        }
        $other_lasagna_lovers_so_far++;
    }
    else {
        print 'Why would anyone NOT like lasagna?', "\n";
    }

Section 2.7.3: Conditionals & Variable Declarations

When a variable is declared inside the body of any conditional statement, then said variable may only be utilized from within that same conditional body (or any nested bodies within it). In all the previous examples, we are implying unseen variable declarations which happen before (and thus outside) the conditional bodies, so all our example variables may be accessed or modified outside the conditional statements themselves.

If a variable is declared within a conditional's statement's body, then we will receive an error if we try to utilize it outside the conditional:

    my integer $foo = 0;
    print 'outside conditional, have $foo = ', $foo, "\n";
    
    if ( $foo < 3 ) {
        $foo++;
        my integer $bar = $foo * 2;
        print 'inside  conditional, have $bar = ', $bar, "\n";
    }
    
    print 'outside conditional, have $foo = ', $foo, "\n";
    print 'outside conditional, have $bar = ', $bar, "\n";  # THIS CAUSES A PARSE ERROR

If we run the code above, the last line attempts to access the $bar variable outside of the conditional body where it was declared, so we receive an error:

    ERROR ECOPAPL02, RPERL PARSER, PERL SYNTAX ERROR
    Failed normal Perl strictures-and-fatal-warnings syntax check with the following information:
    
        File Name:        my_program.pl
        Return Value:     2
        Error Message(s): 
    
    Global symbol "$bar" requires explicit package name at my_program.pl line XYZ
    my_program.pl had compilation errors.

If we simply remove the last line where $bar is incorrectly accessed, then our code runs fine:

    outside conditional, have $foo = 0
    inside  conditional, have $bar = 2
    outside conditional, have $foo = 1

Section 2.8: Receiving Input From The User & STDIN

When you want the users of your software to provide some keyboard input, then you will need to use the STDIN keyword in Perl, which represents the "standard input" data stream. This will allow the user to type one line of input text and numbers, ended by pressing the Enter key. All user input is received in text format, and should initially be stored in a variable with a string data type. Unless converted to a different data type via one of RPerl's type conversion subroutines, the string variable should be passed to the chomp operator, which will remove the trailing newline character collected by STDIN.

When used in Perl, we wrap STDIN with "angle brackets", which start with the less-than < character and end with the greater-than > character. In this context, the less-than and greater-than characters are not used as tests for numeric inequality. Also, when using STDIN in RPerl we must always include the "USER DEFAULT 4" no critic command, which enables use of STDIN in general.

Along with the two output streams STDOUT and STDERR, the input stream STDIN makes up the third of three standard I/O ("input / output") data streams available on most operating systems.

The following example asks the user for their name, then greets them by name:

    #!/usr/bin/perl

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]

    print 'Please input your first name: ';
    my string $first_name = <STDIN>;
    chomp $first_name;
    print 'Hello ', $first_name, ', nice to meet you!', "\n";

One possible execution of this example, with the input name "Will", produces the following output:

    Please input your first name: Will
    Hello Will, nice to meet you!

You may also receive numeric data input, with the use of the appropriate data type conversion subroutines:

    print 'Please input your age in years: ';
    my string $age_string = <STDIN>;
    my integer $age = string_to_integer($age_string);
    print 'You are ', integer_to_string($age), ' years old.', "\n";
    print 'In one year from now, you will be ', integer_to_string($age + 1), ' years old.', "\n";

In the above example, you may optionally omit the two calls to the integer_to_string() data type conversion subroutine, because it has no effect on any integer with a value less than 1,000. One possible execution produces the following output:

    Please input your age in years: 34
    You are 34 years old.
    In one year from now, you will be 35 years old.

You may receive input from STDIN as many times as needed:

    print 'Please input your favorite band or musician: ';
    my string $favorite_band = <STDIN>;
    chomp $favorite_band;
    
    print 'Please input your favorite movie: ';
    my string $favorite_movie = <STDIN>;
    chomp $favorite_movie;
    
    print 'Please input your favorite TV show: ';
    my string $favorite_show = <STDIN>;
    chomp $favorite_show;
    
    print 'You are a fan of ', $favorite_band, ', ', $favorite_movie, ', and ', $favorite_show, q{.}, "\n";
    print '(I like Rush, Blade Runner, and Star Trek!)', "\n";

One possible run of this example produces:

    Please input your favorite band or musician: Neil Peart
    Please input your favorite movie: Blade Runner 2
    Please input your favorite TV show: TNG
    You are a fan of Neil Peart, Blade Runner 2, and TNG.
    (I like Rush, Blade Runner, and Star Trek!)

Section 2.9: Program Control Using The while Loop

Most programs will contain one or more operations which need to be repeated a certain number of times, and for these cases we use a "loop statement" or just a "loop" for short. Like a conditional statement, a loop statement is a kind of control structure, because they are both used to control the execution flow of your software.

In this section, we will describe the most basic loop in Perl, which is the while loop statement. Just like an if conditional statement, a while loop has both a header containing only a condition, and a body of operations. There is only one difference between if and while statements: if executes once when the condition is true, and while executes repeatedly as long as the condition is true.

The following loop will never stop running, because it has a condition which is hard-coded to numeric literal 1, which has a truth value of true. This is called an "infinite loop", and it will repeatedly print an unending amount of global greetings until the user sends a CTRL-C or similar termination signal:

    while (1) { print 'Hello, world!', "\n"; }

As with an if conditional statement, a while loop's condition may be any truth value, which is usually generated by a numeric comparison operator such as less-than < and greater-than > and equals ==, or a logical operator such as and and or and not. Also like a conditional statement, a loop's body may include as many operations as needed, on as many lines as needed.

Section 2.9.1: Loop Iterator Variables

Many loops use a designated variable called an "iterator", utilized for the sole purpose of keeping track of the current iteration count. Traditionally this variable is named $i, and its value is increased by one via the increment ++ operator called as the last operation in a loop body. The value of $i would then be tested via numeric comparison in the loop's condition:

    my integer $i = 0;
    while ( $i < 5 ) {
        print 'Hello, world #', $i, q{!}, "\n";
        $i++;
    }

In the example above, we first declare our iterator $i to start counting at a hard-coded numeric literal value of 0. All of computer science is based on binary logic with two possible binary values of 0 and 1; because of this and other reasons discussed in chapter 3, most counters and iterators start with 0 as their first value, 1 as their second value, and so forth. When $i starts at 0 and uses a less-than < operator to be compared to a certain maximum iteration value, then your while loop will iterate exactly that many times.

When we run the code above, we receive the following output:

    Hello, world #0!
    Hello, world #1!
    Hello, world #2!
    Hello, world #3!
    Hello, world #4!

If you really want to start $i at 1 instead of 0, then you have to use a less-than-or-equal <= operator to perform the same number of iterations:

    my integer $i = 1;
    while ( $i <= 5 ) {
        print 'Hello, world #', $i, q{!}, "\n";
        $i++;
    }

Now our output seems to make more sense to a human, but our iterator variable $i is no longer starting at 0:

    Hello, world #1!
    Hello, world #2!
    Hello, world #3!
    Hello, world #4!
    Hello, world #5!

In order to have our iterator $i start at 0, and also have our output make sense to a human, we call the addition + operator within parentheses as part of the print operator:

    my integer $i = 0;
    while ( $i < 5 ) {
        print 'Hello, world #', ( $i + 1 ), q{!}, "\n";
        $i++;
    }

Now we receive the desired output with $i starting at 0:

    Hello, world #1!
    Hello, world #2!
    Hello, world #3!
    Hello, world #4!
    Hello, world #5!

Section 2.9.2: Nested Loops

As with the if conditional statements, multiple while loops may be nested within one another. When you want to have iterator variables for 2 or even 3 nested loops, the traditional naming convention for simple cases is to start with iterator $i for the outer-most loop, then iterator $j for the next loop nested within the $i loop, and then iterator $k for the loop nested within the $j loop. If you need more or different iterators, you may choose any variable names which you find appropriate.

Also as with if conditional statements, when a variable is declared inside the body of a while loop statement, then said variable may only be utilized from within that same loop body (or any nested bodies within it). In the previous example, the integer variable $i is declared before the loop, so it may be accessed or modified outside the loop. In the next example, the variable $j is declared within the outer loop, so $j may not be utilized outside the outer loop.

Let's take a look at the simplest example of 3 nested loops:

    my integer $i = 0;
    while ( $i < 5 ) {
        my integer $j = 0;
        while ( $j < 4 ) {
            my integer $k = 0;
            while ( $k < 3 ) {
                print 'Hello, world #(', ( $i + 1 ), ', ', ( $j + 1 ), ', ', ( $k + 1 ), q{)!}, "\n";
                $k++;
            }
            $j++;
        }
        $i++;
    }

In each line of the generated output, the first number is from the outer-most $i loop, the second number is from the middle $j loop, and the last number is from the inner-most $k loop:

    Hello, world #(1, 1, 1)!
    Hello, world #(1, 1, 2)!
    Hello, world #(1, 2, 1)!
    Hello, world #(1, 2, 2)!
    Hello, world #(1, 3, 1)!
    Hello, world #(1, 3, 2)!
    Hello, world #(2, 1, 1)!
    Hello, world #(2, 1, 2)!
    Hello, world #(2, 2, 1)!
    Hello, world #(2, 2, 2)!
    Hello, world #(2, 3, 1)!
    Hello, world #(2, 3, 2)!
    Hello, world #(3, 1, 1)!
    Hello, world #(3, 1, 2)!
    Hello, world #(3, 2, 1)!
    Hello, world #(3, 2, 2)!
    Hello, world #(3, 3, 1)!
    Hello, world #(3, 3, 2)!
    Hello, world #(4, 1, 1)!
    Hello, world #(4, 1, 2)!
    Hello, world #(4, 2, 1)!
    Hello, world #(4, 2, 2)!
    Hello, world #(4, 3, 1)!
    Hello, world #(4, 3, 2)!

Section 2.9.3: Loop Control Operators

Sometimes you need to skip to the next loop iteration immediately, without finishing the current iteration. For this, we use the next operator:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n";
    
    while ( $i < 10 ) {
        print "\n";
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i % 2 ) { next; }
        print 'bottom of loop, have next    $i = ', $i, "\n";
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

As you can see, we can freely mix if conditional statements with while loop statements. When we run the code above, the print operator at the bottom of the loop's body is reached only when the incremented $i is even, because odd values of $i will cause the modulo % operator to evaluate as a truth value of true, which then calls the next operator:

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    
    top    of loop, have current $i = 1
    bottom of loop, have next    $i = 2
    
    top    of loop, have current $i = 2
    
    top    of loop, have current $i = 3
    bottom of loop, have next    $i = 4
    
    top    of loop, have current $i = 4
    
    top    of loop, have current $i = 5
    bottom of loop, have next    $i = 6
    
    top    of loop, have current $i = 6
    
    top    of loop, have current $i = 7
    bottom of loop, have next    $i = 8
    
    top    of loop, have current $i = 8
    
    top    of loop, have current $i = 9
    bottom of loop, have next    $i = 10
    
    after     loop, have current $i = 10

Sometimes you need to exit a loop immediately, without finishing the current iteration; for this, we use the last operator. Let's take the previous example and simply replace the next operator with last instead:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n";
    
    while ( $i < 10 ) {
        print "\n";
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i % 2 ) { last; }
        print 'bottom of loop, have next    $i = ', $i, "\n";
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

When we run the code above, the print operator at the bottom of the loop's body is never reached and the loop only executes for one (partial) iteration, because the very first incremented value of $i is odd and will cause the modulo % operator to evaluate as true, which then immediately calls the last operator:

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    
    after     loop, have current $i = 1

Section 2.9.4: Loop Labels & More Loop Control Operators

Sometimes you need to restart a loop's current iteration, without actually finishing the current iteration first or re-executing the loop's header; for this, we use the redo operator. However, before we use the redo operator, we must first learn about loop labels.

When using nested loops, it can be confusing to keep track of which loop is being affected by which loop control operator. To solve this issue, we use loop labels, which are simply all-uppercase names prepended to the loop keyword, which is while in this case. The use of loop labels is optional in most cases, but is required when you want to reliably use loop control operators inside nested loops, and whenever you want to use the redo operator at all.

Let's take the previous example again, add the loop label MY_LOOP, and simply replace the last operator with redo MY_LOOP instead:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n";
    
    MY_LOOP: while ( $i < 10 ) {
        print "\n";
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i % 2 ) { redo MY_LOOP; }
        print 'bottom of loop, have next    $i = ', $i, "\n";
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

When we run the code above, we see the redo operator provides the exact same behavior as next in this case, but that only applies to some while loops and will not always be true. (In the next chapter we will learn about another kind of loop, where next and redo never behave the same.)

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    
    top    of loop, have current $i = 1
    bottom of loop, have next    $i = 2
    
    top    of loop, have current $i = 2
    
    top    of loop, have current $i = 3
    bottom of loop, have next    $i = 4
    
    top    of loop, have current $i = 4
    
    top    of loop, have current $i = 5
    bottom of loop, have next    $i = 6
    
    top    of loop, have current $i = 6
    
    top    of loop, have current $i = 7
    bottom of loop, have next    $i = 8
    
    top    of loop, have current $i = 8
    
    top    of loop, have current $i = 9
    bottom of loop, have next    $i = 10
    
    after     loop, have current $i = 10

The redo operator does not re-execute its corresponding loop's header, it jumps directly to the first operation in the loop's body and continues execution from there. In contrast, the next operator does execute the loop's header, which in the case of while is comprised only of checking the loop's condition.

The following source code example is comprised of a while loop containing an if conditional with a "bail out" condition:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n\n";
    
    MY_LOOP: while ( $i < 5 ) {
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i > 10 ) {
            print 'inside of loop, have next    $i = ', $i, '; value too big, bailing out!', "\n";
            last MY_LOOP;
        }
        next MY_LOOP;
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

When we run the example code above, we never reach the last operator inside the loop, because the next operator causes the loop's condition to be checked and the loop stops iterating before $i reaches a value greater than 10. In fact, we could totally delete the next MY_LOOP line as well as the entire if conditional statement, and we would still receive the same output:

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    top    of loop, have current $i = 1
    top    of loop, have current $i = 2
    top    of loop, have current $i = 3
    top    of loop, have current $i = 4
    
    after     loop, have current $i = 5

In the following code, we have simply replaced next MY_LOOP with last MY_LOOP:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n\n";
    
    MY_LOOP: while ( $i < 5 ) {
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i > 10 ) {
            print 'inside of loop, have next    $i = ', $i, '; value too big, bailing out!', "\n";
            last MY_LOOP;
        }
        last MY_LOOP;
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

As before, the body of the if conditional statement is never executed because $i never reaches a value higher than 10. Perhaps unsurprisingly, running this code produces a relatively short output:

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    
    after     loop, have current $i = 1

Of course, we will now replace next MY_LOOP with redo MY_LOOP:

    my integer $i = 0;
    
    print 'before    loop, have current $i = ', $i, "\n\n";
    
    MY_LOOP: while ( $i < 5 ) {
        print 'top    of loop, have current $i = ', $i, "\n";
        $i++;
        if ( $i > 10 ) {
            print 'inside of loop, have next    $i = ', $i, '; value too big, bailing out!', "\n";
            last MY_LOOP;
        }
        redo MY_LOOP;
    }
    
    print "\n";
    print 'after     loop, have current $i = ', $i, "\n";

The redo operator does not cause the while loop's header to be executed, so the $i < 5 condition is only checked the very first iteration. Therefore, the value of $i continues to increase until it is greater than 10 and triggers the "bail out" mechanism. (If only the economy was this simple.)

When we run the code, this is the output we see displayed:

    before    loop, have current $i = 0
    
    top    of loop, have current $i = 0
    top    of loop, have current $i = 1
    top    of loop, have current $i = 2
    top    of loop, have current $i = 3
    top    of loop, have current $i = 4
    top    of loop, have current $i = 5
    top    of loop, have current $i = 6
    top    of loop, have current $i = 7
    top    of loop, have current $i = 8
    top    of loop, have current $i = 9
    top    of loop, have current $i = 10
    inside of loop, have next    $i = 11; value too big, bailing out!
    
    after     loop, have current $i = 11

Now we will look at at a simple nested loop example; we have 2 loops with the last operator called from the body of the inner loop:

    my integer $i = 0;
    my integer $j = 0;
    
    print 'before    outer loop, have current $i = ', $i, "\n";
    print 'before    outer loop, have current $j = ', $j, "\n";
    
    while ( $i < 3 ) {
        print "\n";
        print 'top    of outer loop, have current $i = ', $i, "\n";
        $i++;
        $j = 0;
        while ( $j < 5 ) {
            print 'top    of inner loop, have current $j = ', $j, "\n";
            $j++;
            if ( $j > 2 ) { next; }
            print 'bottom of inner loop, have current $j = ', $j, "\n";
        }
        print 'bottom of outer loop, have next    $i = ', $i, "\n";
    }
    
    print "\n";
    print 'after     outer loop, have current $i = ', $i, "\n";
    print 'after     outer loop, have current $j = ', $j, "\n";

When we run this code we can see that for every iteration of the outer loop, the bottom of the inner loop is only reached twice, when the current value of $j is less than 2. This is because when the next operator is called without a loop label, then it is applied to most immediate loop, which means next is applied to the inner loop in this case:

    before    outer loop, have current $i = 0
    before    outer loop, have current $j = 0
    
    top    of outer loop, have current $i = 0
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    top    of inner loop, have current $j = 3
    top    of inner loop, have current $j = 4
    bottom of outer loop, have next    $i = 1
    
    top    of outer loop, have current $i = 1
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    top    of inner loop, have current $j = 3
    top    of inner loop, have current $j = 4
    bottom of outer loop, have next    $i = 2
    
    top    of outer loop, have current $i = 2
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    top    of inner loop, have current $j = 3
    top    of inner loop, have current $j = 4
    bottom of outer loop, have next    $i = 3
    
    after     outer loop, have current $i = 3
    after     outer loop, have current $j = 5

Now let's take the same nested loops, add loop labels, and replace next with next OUTER_LOOP instead:

    my integer $i = 0;
    my integer $j = 0;
    
    print 'before    outer loop, have current $i = ', $i, "\n";
    print 'before    outer loop, have current $j = ', $j, "\n";
    
    OUTER_LOOP: while ( $i < 3 ) {
        print "\n";
        print 'top    of outer loop, have current $i = ', $i, "\n";
        $i++;
        $j = 0;
        INNER_LOOP: while ( $j < 5 ) {
            print 'top    of inner loop, have current $j = ', $j, "\n";
            $j++;
            if ( $j > 2 ) { next OUTER_LOOP; }
            print 'bottom of inner loop, have current $j = ', $j, "\n";
        }
        print 'bottom of outer loop, have next    $i = ', $i, "\n";
    }
    
    print "\n";
    print 'after     outer loop, have current $i = ', $i, "\n";
    print 'after     outer loop, have current $j = ', $j, "\n";

This time we can see the bottom of the inner loop is only reached twice, which is the same as before. However, now the bottom of the outer loop is never reached, because the next operator is being applied to the outer loop instead of the inner loop:

    before    outer loop, have current $i = 0
    before    outer loop, have current $j = 0
    
    top    of outer loop, have current $i = 0
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    
    top    of outer loop, have current $i = 1
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    
    top    of outer loop, have current $i = 2
    top    of inner loop, have current $j = 0
    bottom of inner loop, have current $j = 1
    top    of inner loop, have current $j = 1
    bottom of inner loop, have current $j = 2
    top    of inner loop, have current $j = 2
    
    after     outer loop, have current $i = 3
    after     outer loop, have current $j = 3

If we replace next OUTER_LOOP with next INNER_LOOP, then we will see the same default behavior as when next is called with no loop label.

What do you think will happen if we place next with last or redo in these example cases? I will leave it up to you to experiment and find out for yourself! (Hint: redo INNER_LOOP and redo OUTER_LOOP will cause two different kinds of infinite loop.)

Section 2.9.5: Combining while & STDIN

Sometimes you want to accept multiple lines of user input via STDIN, instead of just one line at a time as in previous examples. To achieve this, we put the call to STDIN inside the loop's condition:

    #!/usr/bin/perl
    
    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;
    
    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt
    
    # [[[ OPERATIONS ]]]
    
    my string $input_strings = q{};
    
    print 'Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D> on a blank line:', "\n";
    
    while ( my string $input_string = <STDIN> ) {
        $input_strings .= $input_string;
    }
    
    print "\n";
    print 'after loop, have $input_strings = ', "\n", $input_strings, "\n";

As displayed by the first print operator above, the users must press the two-keystroke combination CTRL-D in order to signal the "EOF" or "End Of File" condition, which tells the while loop to stop iterating. Also, we must remember to include the "USER DEFAULT 4" no critic command, thereby enabling use of STDIN.

When we run the code above, we can see all user input has been combined into one variable $input_strings via the string concatenation . operator:

    Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D> on a blank line:
    howdy
    dowdy
    doo
    
    after loop, have $input_strings = 
    howdy
    dowdy
    doo

Section 2.10: Exercises

1. Constant Pi & Calculated Circumference Of A Circle [ 30 mins ]

In the same LearningRPerl directory from the chapter 1 exercises, create a new sub-directory named Chapter2. In the new sub-directory, create a RPerl program file named exercise_1-circumference_of_specific_radius.pl, which contains constant data for the approximate value of pi equal to 3.141_592_654. In your program, utilize the print operator and RPerl's data type conversion subroutines to display your hard-coded value of pi.

Next, create a variable named $radius with a value of 12.5, and a second variable named $circumference which contains the properly-calculated circumference for a circle with the corresponding radius value. Use print and the type conversion subroutines to display all your values:

    Pi = 3.141_592_654
    Radius = 12.5
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * 12.5 = 78.539_816_35

Run your new program by issuing the following command at your terminal command prompt:

    $ rperl -t LearningRPerl/Chapter2/exercise_1-circumference_of_specific_radius.pl

HINT: You will need two no critic commands, and your program should be at least 13 lines long.

2. Variable Radius & Calculated Circumference Of A Circle [ 20 mins ]

Make a copy of your fully-functioning program from exercise 1 above, thereby creating a new RPerl program file named exercise_2-circumference_of_any_radius.pl. (Don't just edit your previous program file without making a copy, or you will not receive full credit.)

Use print to prompt the user to enter a custom value for $radius, then use the STDIN keyword to receive one input value into a new variable named $radius_string of string data type. Next, use a RPerl data type conversion subroutine to convert the string data type and store it in the original $radius variable of number data type.

As in the previous exercise, end by using the print operator to display all your values:

    $ rperl -t LearningRPerl/Chapter2/exercise_2-circumference_of_any_radius.pl
    Please input radius: 3

    Pi = 3.141_592_654
    Radius = 3
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * 3 = 18.849_555_924

HINT: You will need to add a third no critic command, and a total of at least 3 or 4 extra lines of code.

3. Conditional Error Checking & Calculated Circumference Of A Circle [ 20 mins ]

Make a copy of your completed program from exercise 2 above, and name your new file exercise_3-circumference_of_any_positive_radius.pl.

Using an if and else conditional statement, detect when the user provides a negative number for the radius variable, in which case a warning should be displayed and the circumference should be set to a value of zero:

    $ rperl -t LearningRPerl/Chapter2/exercise_3-circumference_of_any_positive_radius.pl
    Please input radius: -3
    Negative radius detected, defaulting to zero circumference!

    Pi = 3.141_592_654
    Radius = -3
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * -3 = 0

4. Product Of Two Numbers [ 20 mins ]

Write a new RPerl program named exercise_4-product_of_any_two_numbers.pl, which will prompt the user for two input numbers, one at a time, and then display the result of multiplying the two input numbers together. As with all keyboard input in this and any other RPerl source code, your input values are text data and should be passed to the RPerl data type conversion subroutines before being used in numeric calculations. Remember to reverse this by converting back from number to string types again, before passing a numeric value to the print operator.

An example execution of this exercise should display:

    $ rperl -t LearningRPerl/Chapter2/exercise_4-product_of_any_two_numbers.pl
    Please input multiplicator: 17
    Please input multiplicand: 123.456_789

    Product = Multiplicator * Multiplicand = 17 * 123.456_789 = 2_098.765_413

5. String Repetition [ 15 mins ]

Create a new program named exercise_5-string_repeat.pl, which will prompt the user for one input string followed by one input integer. Your program should then use the string repetition operator x to display the input string repeated as many times as the input integer specifies. As always, use the RPerl data type conversion subroutines when appropriate.

An example execution should display:

    $ rperl -t LearningRPerl/Chapter2/exercise_5-string_repeat.pl
    Please input string to be repeated: Repetition is an aid to memory.
    Please input integer (whole number) times to repeat string: 5

    Repetition is an aid to memory.
    Repetition is an aid to memory.
    Repetition is an aid to memory.
    Repetition is an aid to memory.
    Repetition is an aid to memory.

6. Looping Integer Sum [ 35 mins ]

Create a program named exercise_6-sum_of_first_n_integers.pl, which will prompt the user for one input integer and then display the sum of the numbers 1 through the input integer, inclusive. Utilize an if conditional statement to perform an error check, and call the die operator if the input integer is less than 0. Then utilize a while loop to compute the actual sum to be displayed as a result.

Store your input integer in a variable named $n, and your final result in a variable named $sum, both of the integer data type. As with all loop iterators, the $i variable is also an integer.

Two possible executions of this exercise follow:

    $ rperl -t LearningRPerl/Chapter2/exercise_6-sum_of_first_n_integers.pl
    Please input a positive integer: 42
    The sum of the first 42 integers is 903

    $ rperl -t LearningRPerl/Chapter2/exercise_6-sum_of_first_n_integers.pl
    Please input a positive integer: -42
    ERROR: -42 is not positive, dying

7. Non-Looping Integer Sum [ 45 mins ]

Make a copy of your completed program from the previous exercise, and save it into a new file named exercise_7-sum_of_first_n_integers_no_loop.pl.

Modify the new program to remove the while loop, and instead replace it with the famous method credited to Gauss, the "Prince of Mathematics":

It is said that as a child, Gauss was punished by his teacher by being told to mentally add together all the numbers from 1 to 100. Young Gauss realized that 1 plus 100 is 101, and 2 plus 99 is also 101, as well as 3 plus 98 and so forth. All the numbers may be paired in this manner to equal 101, and there are 50 such pairs from 1 to 100 inclusively, so the final answer is 101 multiplied by 50. Thus, with a bit more thought Gauss was able to quickly calculate the correct answer of 5,050 and perplex his teacher in the process.

Use young Gauss' algorithm to optimize the runtime performance (AKA speed) of your new program, which you can achieve by replacing the while loop with arithmetic operators as described in the story above. This exercise should always give the same answer as the previous exercise, but Gauss' algorithm is naturally more efficient for large input integers, because it requires far fewer calculations than the repeated addition loop algorithm.

Start by assuming your input integer will be evenly divisible by two, so you can use the exact algorithm used by Gauss in the story. Once your program works correctly for all even integer inputs, then use an if conditional statement to check for odd integer inputs and extend your algorithm to handle those cases. Of course, the error checking for negative input integers should be left in place from the previous exercise.

Two possible executions of this exercise follow, one with an even input integer, and one with an odd input integer:

    $ rperl -t LearningRPerl/Chapter2/exercise_7-sum_of_first_n_integers_no_loop.pl
    Please input a positive integer: 64
    The sum of the first 64 integers = 2_080

    $ rperl -t LearningRPerl/Chapter2/exercise_7-sum_of_first_n_integers_no_loop.pl
    Please input a positive integer: 65
    The sum of the first 65 integers = 2_145

HINT: Use the modulo % operator to check for odd input integers; if found, initialize a temporary variable named $n_odd to the value of $n, decrement $n to become even, and add $n_odd to your original $sum result.


CHAPTER 3: ARRAY VALUES & VARIABLES

In the previous chapter, we explored the many uses of scalar values and variables, which dealt with one number or one string at a time. In this chapter, we will similarly explore the uses of array values and variables, which are collections of multiple scalars (numbers or strings) grouped together.

A scalar represents exactly one piece of Perl data and represents one specific data type. An array represents zero or more pieces of Perl data and represents a compound "data structure", defined as a combination of two or more subcomponents which may themselves be either normal scalar data types or additional compound data structures. In an array, each individual subcomponent is known as an "element".

In normal Perl, a variable may contain (represent) an array directly "by value", or indirectly "by reference". As an analogy, imagine that your computer's memory is like a filing cabinet, your Perl program's memory is like one drawer in the filing cabinet, your array data structure is like one folder in the filing cabinet drawer, your variable is like the label on the folder, and each element of the array is like one page in the folder.

In this filing cabinet analogy, an array which is stored by value is like a normal label (array variable), on a normal folder (array data structure), containing normal pages (elements). An array which is stored by reference is like a special label (scalar variable), affixed to a single piece of paper (scalar data type), upon which is written the location (memory address AKA reference) of a special folder (anonymous array data structure). Inside the special folder are normal pages (elements), and there is no label (array variable) affixed to the special folder, thus we say the folder is an "anonymous array" because it has no label.

To reiterate, an array stored by reference is actually a scalar variable which contains the memory address of an anonymous array. When compared to the memory usage of storing an array by data, the memory needs of storing by reference only require one additional scalar value (one piece of paper in our filing cabinet analogy), which contains the anonymous array's memory address. Both storing by value and storing by reference are commonly utilized in many different computer programming languages.

When an array is stored by value, the corresponding variable has an at sign @ as its sigil, and the assigned data is enclosed within parentheses ( ) characters. When an array is stored by reference, the corresponding variable has a dollar sign $ as its sigil, and the assigned data is enclosed within square bracket [ ] characters. If an array is stored by value and is then passed as input to an operation, it is said the array is "passed by value". On the other hand, if the array is instead stored by reference and then passed to an operation, it is said to be "passed by reference".

For arrays with more than just a few elements, it may be impractical or impossible to pass by value, because a full copy of each array element must be made in the process, which may fill up all your program's available memory or take a prohibitively long time to complete. Also, Perl allows us to provide explicit data types only when an array is stored by reference, so we can not provide a data type for an array stored by value. Because of these reasons, all RPerl arrays are stored by reference, and are declared with an explicit RPerl data type ending with _arrayref.

    my                  @foo_by_value           = (2, 4, 6);  # fine in normal Perl, error in RPerl
    my                  $foo_by_reference       = [2, 4, 6];  # fine in normal Perl, error in RPerl
    my integer_arrayref $foo_by_reference_typed = [2, 4, 6];  # fine in normal Perl, fine  in RPerl

In a few special cases, Perl forces us to provide an array by value instead of by reference, in which case we need to "dereference" our array variable, which is the process of converting from the stored-by-reference memory address to the stored-by-data values. This is achieved by use of Perl's closefix array dereference syntax, comprised of enclosing the scalar array variable within at sign curly braces @{ }. Because all arrays in RPerl are stored by reference, only necessary uses of the dereference syntax are supported by the RPerl compiler. (Please see "Section 3.8: push & pop Operators" for more information on pop.)

    my integer_arrayref $foo_by_reference_typed = [10, 20, 30];                    # fine in normal Perl, fine  in RPerl
    my integer          $foo_last_element       = pop @{$foo_by_reference_typed};  # fine in normal Perl, fine  in RPerl,   necessary dereference 
    my                  @foo_by_value           = @{$foo_by_reference_typed};      # fine in normal Perl, error in RPerl, unnecessary dereference

In normal Perl, a single array may contain elements with multiple different data types, such as a three-element array containing one string and one integer and one floating-point number. In RPerl, a single array must contain elements of all the same data type, so you can have a three-element array with all strings, but you can't store an integer inside an array of strings, and likewise you can't store a string inside an array of integers, etc.

    my integer_arrayref $foo = [5, 10, 15];                 # fine
    my  number_arrayref $bar = [5, 10, 15.5];               # fine
    my  string_arrayref $bat = ['five', 'ten', 'fifteen'];  # fine

    my integer_arrayref $foo = [5, 10, 15.5];               # error in RPerl, compiled modes
    my  number_arrayref $bar = [5, 10, 'fifteen'];          # error in RPerl, compiled modes
    my  string_arrayref $bat = ['five', 'ten', 15];         # error in RPerl, compiled modes

You can create an array with only one element, sometimes called a "singleton"; you can even create an empty array with zero elements:

    my integer_arrayref $foo = [];    # zero elements, empty     array
    my integer_arrayref $bar = [23];  # one  element,  singleton array

To display the contents of an array, you may utilize the *_arrayref_to_string() family of stringification subroutines:

    my integer_arrayref $foo;
    $foo = [23, 42, 2_112];
    print '$foo = ', integer_arrayref_to_string($foo), "\n";

Running the code example above generates the following output:

    $foo = [23, 42, 2_112]

RPerl currently supports the following array stringification subroutines, with support for all RPerl array data types coming soon:

Section 3.1: Lists vs Arrays

In Perl, we use the comma , character to separate elements in a "list", which may then be utilized either as the operands passed as input to an appropriate operation, or as the values stored inside an array data structure. Thus, an array variable may be assigned the value of an enclosed list, but in RPerl the reverse is not true. (Please see "Section 3.7: Array Assignment" for more information.)

    my                 @variable_storing_array_by_value     = ('list', 'enclosed', 'within', 'round',  'parentheses');  # fine in  Perl, error in RPerl, list assigned to stored-by-value     array
    my string_arrayref $variable_storing_array_by_reference = ['list', 'enclosed', 'within', 'square', 'brackets'];     # fine in RPerl, fine  in RPerl, list assigned to stored-by-reference array

    my ($list, $of, $variables) = @variable_storing_array_by_value;      # fine  in Perl, error in RPerl, stored-by-value     array assigned to list
    my [$list, $of, $variables] = $variable_storing_array_by_reference;  # error in Perl, error in RPerl, stored-by-reference array assigned to list

As seen in the code example above, when a list is enclosed within square brackets [ ], then we have a stored-by-reference "array literal", which represents the literal value which may be assigned to an RPerl variable. Likewise, when a list is enclosed within parentheses ( ) characters and the context tells Perl the parentheses are used as array syntax, then we have a stored-by-data array literal, which may be assigned to a normal Perl variable.

Depending upon the context of the surrounding source code, the parentheses ( ) characters have multiple different uses in Perl, including list and array literal values, explicit order-of-operations, operation input arguments, and control structure statement headers. (Remember that RPerl only supports arrays which are stored by reference, so all RPerl array literals will be enclosed in square brackets [ ], not parentheses ( ).)

    my                 @foo = (1,  3,   5);  # fine in Perl, error in RPerl, parentheses enclosing list values to create stored-by-value array
    my integer         $foo = (1 + 3) * 5;   # fine in Perl, fine  in RPerl, parentheses enclosing arithmetic order-of-operations
    my string_arrayref $foo = [qw(a c e)];   # fine in Perl, fine  in RPerl, parentheses enclosing input arguments to qw() operator
    if (1 < 3)         { print   'a c e'; }  # fine in Perl, fine  in RPerl, parentheses enclosing if conditional statement header

Terminology can be confusing at times. An array literal should not be confused with the similar-sounding "array of literals", which is an array where all the elements are literals instead of variables or operations. In the source code example below, the data structure [$foo, $bar, 23] is an array literal, even though two of its three elements are variables themselves; remember, an array literal is any enclosed list which can be assigned to a variable. On the other hand, the data structure [22, 13, 24] below is an array of literals, because all its elements are literal values themselves. At the same time, the variable $frob can also be considered an array of literals, due to the ambiguity of the term "array" when used without explicit context.

    my integer          $foo  = 21;
    my integer          $bar  = 12;
    my integer_arrayref $quux = [$foo, $bar, 23];  # array literal     on right side  of = assignment operator
    my integer_arrayref $frob = [22,   13,   24];  # array of literals on both  sides of = assignment operator

Depending on context, the unqualified term "array" can be taken to have either the general meaning of "array data structure category", or the specific meanings "array literal" or "array assigned to variable". The phrase "scalar versus array" should be read as "scalar data type category versus array data structure category", because we are referring to the general ideas of "scalar" and "array" instead of specific array literals or variables. The phrase "array [22, 13, 24]" should be read as "array literal [22, 13, 24]", because we can see an enclosed list of comma-separated values. The phrase "array $frob" should be read as "array assigned to variable $frob", because we can see a dollar sign $ sigil variable name. (This is just one of many possible confusion points caused by the linguistic subtleties inherent in our particular brand of technical terminology, often rightfully referred to as "programming jargon" or even the mocking "techno-babble".) Because the stand-alone term "array" is ambiguous, the term "array of literals" can be taken to mean either "array-literal of literals" or "array-assigned-to-variable of literals". This means we can consider both $frob and [22, 13, 24] to be an "array of literals" in the source code example above. Hopefully, you will never again experience this specific confusion of jargon, but you must always be wary of subtle language issues when dealing with high-tech concepts such as programming in RPerl.

Section 3.2: 1-D Array Data Types & Constants

In RPerl, all arrays are stored by reference and have a specific data type which ends with _arrayref. In the preceeding examples, you have already seen the three most common RPerl array data types, which are integer_arrayref, number_arrayref, and string_arrayref.

A single scalar may be considered to be a zero-dimensional (0-D) data point. When an array's individual elements are each scalars, the array is considered to be one-dimensional (1-D), and may be visualized as multiple data points displayed on a single line. Some additional math and software concepts related to a 1-D array or list are "vector", "sequence", and "set"; please see Wikipedia for more information. (For example, in the MathPerl software suite, which is part of the RPerl Family of software, the Vector data structure is simply a specially-packaged number_arrayref.) In some cases, it may also be useful to visualize a 1-D array as a single "row" of elements.

    my integer_arrayref $row_1D = [0, 2, 4, 6, 8];  # one row on one line

The following 1-D array data types may be utilized in RPerl:

Perl itself does not currently support array data structures with constant values, so only scalars may be constants.

    use constant PIE  => my string $TYPED_PIE = 'pecan';  # fine in Perl & RPerl

    use constant DAYS => my string_arrayref $TYPED_DAYS = [ 'Sun', 'Mon', 'Tues', 'Weds', 'Thurs', 'Fri', 'Sat' ];  # error in Perl & RPerl

Please see "Section 3.5: 2-D Array Data Types & Nested Arrays" for more RPerl array data types.

Section 3.3: How To Access Array Elements

Each element of a Perl array is numbered, in order, by integers starting at the value of zero and counting upward. Each such integer is known as an "array index", or just "index" for short. Thus, what a normal person would think of as being the "first" element in an array is actually not at index value of 1, but is actually at index 0 instead. This is a common point of confusion for new programmers, or even experienced programmers who may be accustomed to a different computer language which starts at index 1 insted of index 0 like Perl. It may help to think of the "first" element as actually being the "zeroth" element.

    my string_arrayref $marx_brothers = ['Chico', 'Harpo', 'Groucho', 'Gummo', 'Zeppo'];
    print 'The first born is ',   $marx_brothers->[0], "\n";
    print 'The middle child is ', $marx_brothers->[2], "\n";
    The first born is Chico
    The middle child is Groucho

In the example above, note the "first born" is located at index value of 0 (not 1), and the "middle child" is at index 2 (not 3).

Also, note the thin-arrow-square-brackets ->[ ] syntax for accessing the individual elements. The thin arrow -> is Perl's "postfix dereference" operation, which fetches the array data pointed to by the array's memory address, and is necessary because all RPerl arrays are stored by reference. When combined with the postfix dereference operation, the square brackets [ ] return the actual element located at the specified index value. In the following example, each of the three lines of source code achieves the same goal of returning the array element at index 2, although only the last line is valid in RPerl:

    $my_element = @my_array[2];        # fine in Perl, error in RPerl, array not stored by reference
    $my_element = @{$my_arrayref}[2];  # fine in Perl, error in RPerl, unnecessary use of @{} closefix dereference syntax
    $my_element = $my_arrayref->[2];   # fine in Perl, fine  in RPerl,   necessary use of ->   postfix dereference syntax

Section 3.4: Array Length & Negative Indices

When we want to count how many elements are in an array, we need to find the array's length. This is achieved by use of Perl's scalar operator, combined with Perl's closed-fixity at sign curly braces @{ } dereference operation. Both the dereference and postfix dereference operations perform the same task, although they are used in differing scenarios due to their unique syntax. The scalar operator forces the dereferenced array to be evaluated in "scalar context", which means Perl tries to treat an array as if it were a scalar. Perl has many complex behaviors when forcing one data type's context upon another different data type, although in the case of forcing an array into scalar context we are simply provided with the length of the array.

    my string_arrayref $greetings        = ['hello', 'hi', 'howdy'];
    my integer         $greetings_length = scalar @{$greetings};
    print 'have $greetings_length = ', $greetings_length, "\n";
    have $greetings_length = 3

So, when you want to utilize an array's length to calculate a desired index value, remember that you must subtract one from the length value, because array indices start counting at zero but the array length starts counting at one. Yes, this is another common trap for new programmers, so watch yourself!

    my string_arrayref $greetings        = ['hello', 'hi', 'howdy'];
    my integer         $greetings_length = scalar @{$greetings};
    my string $greeting_final            = $greetings->[($greetings_length - 1)];
    print 'have $greeting_final = ', $greeting_final, "\n";
    have $greeting_final = howdy

Now let's see what would happen if we simply forgot to subtract one:

    my string_arrayref $greetings        = ['hello', 'hi', 'howdy'];
    my integer         $greetings_length = scalar @{$greetings};
    my string $greeting_final            = $greetings->[$greetings_length];
    print 'have $greeting_final = ', $greeting_final, "\n";
    Use of uninitialized value $greeting_final in print...
    have $greeting_final =

As you can see in the output above, an attempt to access the $greetings element at index value 3 results in an uninitialized value error message, because the highest valid index value is actually 2 in this case. Don't forget to subtract one when converting from array lengths to array indices!

In Perl, an array index with a negative value will access elements beginning from index -1 as the final element of the array, and counting backward to end with the starting (zeroth) element. Thus, we may rewrite the previous example to achieve the exact same result by utilizing a negative index instead of the scalar operation, thereby simplifying our code by removing at least three operations and one variable:

    my string_arrayref $greetings        = ['hello', 'hi', 'howdy'];
    my string $greeting_final            = $greetings->[-1];
    print 'have $greeting_final = ', $greeting_final, "\n";
    have $greeting_final = howdy

If you want to access each array element in reverse order, simply count downward with indices starting at -1:

    my string_arrayref $greetings        = ['hello', 'hi', 'howdy'];
    print 'have $greetings->[-1] = ', $greetings->[-1], "\n";
    print 'have $greetings->[-2] = ', $greetings->[-2], "\n";
    print 'have $greetings->[-3] = ', $greetings->[-3], "\n";
    have $greetings->[-1] = howdy
    have $greetings->[-2] = hi
    have $greetings->[-3] = hello

Section 3.5: 2-D Array Data Types & Nested Arrays

Because one data structure may contain another data structure as one of its subcomponents, we may thus nest multiple array values within one another. In normal Perl, any number of arrays may be arbitrarily nested within one another in any syntactically-valid combination; in RPerl, we require the use of explicit data types, which are currently limited to 2-dimensional array-within-array data structures. Support for 3-dimensional or other nested data structures will be added in a future version of RPerl.

    my integer_arrayref_arrayref $nested_2d =      # fine in normal Perl, fine  in RPerl, 2x3     2-D nested array
        [[0, 1, 2],
         [9, 8, 7]];
    my                           $nested_2d_mix =  # fine in normal Perl, error in RPerl, 2x3     2-D nested array, unmatching integer & string types
        [[0, 1, 2],
         ['a', 'b', 'c']];
    my                           $nested_3d =      # fine in normal Perl, error in RPerl, 3x3x3   3-D nested array, RPerl support coming soon
        [[[1, 2, 3], 
          [2, 3, 4], 
          [3, 4, 5]],
         [[9, 8, 7],
          [8, 7, 6],
          [7, 6, 5]],
         [[0, 2, 4],
          [2, 4, 6],
          [4, 6, 8]]];
    my                           $nested_4d =      # fine in normal Perl, error in RPerl, 1x1x1x3 4-D nested array, RPerl support coming soon
        [[[[23, 42, 2_112]]]];

When an array's individual elements are each arrays, and each of those arrays is comprised of scalars, then the primary array is considered to be 2-D. ("Or not 2-D? That is the question." ... Okay sorry for that one, haha!) A 2-D array may be visualized as multiple data points displayed on multiple lines. In mathematics, the concept of a "matrix" is essentially a 2-D array which usually has an equal number of elements in each row. Because of this, a matrix can often be visualized as either rectangular or square, and is said to contain both rows and "columns", where the number of columns is defined as the number of elements in each row. In the example below, the 2-D array can be utilized as a square matrix, because there are an equal number of rows (five) as there are columns (also five).

    my integer_arrayref_arrayref $rows_and_columns_2D =  # fine in RPerl, multiple rows and columns on multiple lines
        [[0, 2, 4, 6, 8],
         [1, 3, 5, 7, 9],
         [4, 3, 2, 1, 0],
         [9, 8, 7, 6, 5],
         [5, 5, 5, 5, 5]];

However, in RPerl we are not limited to only rectangular or square matrices, because we are not required to have the same number of elements in each row of a 2-D array. In the example below, note the acceptable use of rows with only one or zero elements; the empty array [ ] and the singleton array [5] are both valid in RPerl.

    my integer_arrayref_arrayref $rows_and_columns_2D_irregular =  # fine in RPerl, irregular row lengths
        [[0, 2, 4],
         [1, 3, 5, 7, 9],
         [],
         [9, 8, 7, 6],
         [5]];

The following 2-D array data types may be utilized in RPerl:

To access elements in a 2-D array, you must use two postfix dereference operations, which may either be combined into one statement or separated across multiple statements. When a 2-D array is being utilized as a matrix in RPerl, then the data structure is stored in "row-major form", which means the first dereference operation will give you a whole row, and the second dereference will give you an individual column element from within the selected row.

    my integer $row_3_column_0_combined = $rows_and_columns_2D->[3]->[0];  # row and column dereferences, combined in one statement
    print 'have $row_3_column_0_combined = ', $row_3_column_0_combined, "\n";

    my integer_arrayref $row_3 = $rows_and_columns_2D->[3];                # row dereference only
    print 'have $row_3 = ', integer_arrayref_to_string($row_3), "\n";
    my integer $row_3_column_0_separated = $row_3->[0];                    # column dereference only
    print 'have $row_3_column_0_separated = ', $row_3_column_0_separated, "\n";

If you run the code example above with the value of $rows_and_columns_2D given in this section, then you should receive the following output:

    have $row_3_column_0_combined = 9
    have $row_3 = [9, 8, 7, 6, 5]
    have $row_3_column_0_separated = 9

If you want to select an entire matrix column instead of a row, then you can change the first dereference operation's index to select each row one-at-a-time, while keeping the second dereference's index set to the desired column:

    my integer_arrayref $column_3 = [];
    $column_3->[0] = $rows_and_columns_2D->[0]->[3];
    $column_3->[1] = $rows_and_columns_2D->[1]->[3];
    $column_3->[2] = $rows_and_columns_2D->[2]->[3];
    $column_3->[3] = $rows_and_columns_2D->[3]->[3];
    $column_3->[4] = $rows_and_columns_2D->[4]->[3];
    # ... and so on, for each row in $rows_and_columns_2D (if there are more than 5 rows as shown above)
    print 'have $column_3 = ', integer_arrayref_to_string($column_3), "\n";

If you run the code example above, then you should receive the following output:

    have $column_3 = [6, 7, 1, 6, 5]

It is important not to confuse a 1-D array with a 2-D array which only contains one row. A 1-D array will only require one dereference in order to access individual elements, while a 2-D array will require two dereferences to achieve the same thing. For a 2-D array containing only one row, the first dereference should always be at index 0 to retrieve the whole row.

    my integer_arrayref          $foo_1D =  [3, 6, 9];
    my integer_arrayref_arrayref $foo_2D = [[3, 6, 9]];

    print 'have 1-D single dereference = ', $foo_1D->[2],      "\n";
    print 'have 2-D double dereference = ', $foo_2D->[0]->[2], "\n";

Both dereference statements in the example above should access the numeric value of 9, taken from $foo_1D and then $foo_2D, respectively:

    have 1-D single dereference = 9
    have 2-D double dereference = 9

Section 3.6: qw() Operator

Sometimes you will want to create an array which contains multiple string literals, which can be achieved either by normal use of quotes and commas, or by use of the "quote word" qw() operator. Let's return to a source code example from "Section 3.1: Lists vs Arrays", which shows a common use of the qw() operator, compared below with the equivalent code using quotes and commas.

    my string_arrayref $foo_1 = [qw(a c e)];
    my string_arrayref $bar_1 = ['a', 'c', 'e'];  # 4 characters less

In the example above, we can reduce our source code by 4 characters by utilizing the qw() operator. The benefit of using qw() only increases with the number of array elements.

    my string_arrayref $foo_2 = [qw(a b c d e f g)];
    my string_arrayref $bar_2 = ['a', 'b', 'c', 'd', 'e', 'f', 'g'];  # 16 characters less
 
    my string_arrayref $foo_3 = [qw(a b c d e f g h i j k l m)];
    my string_arrayref $bar_3 = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm'];  # 34 characters less

Now let's take a look at the data we have stored in our array reference variables:

    print 'have $foo_1 = ', string_arrayref_to_string($foo_1), "\n";
    print 'have $bar_1 = ', string_arrayref_to_string($bar_1), "\n";
    print 'have $foo_2 = ', string_arrayref_to_string($foo_2), "\n";
    print 'have $bar_2 = ', string_arrayref_to_string($bar_2), "\n";
    print 'have $foo_3 = ', string_arrayref_to_string($foo_3), "\n";
    print 'have $bar_3 = ', string_arrayref_to_string($bar_3), "\n";
    have $foo_1 = ['a', 'c', 'e']
    have $bar_1 = ['a', 'c', 'e']
    have $foo_2 = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
    have $bar_2 = ['a', 'b', 'c', 'd', 'e', 'f', 'g']
    have $foo_3 = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm']
    have $bar_3 = ['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l', 'm']

As we can see in the output above, the data stored by the qw() operator is identical to the data stored by the normal quotes and commas technique, and qw() requires fewer characters of source code when there are at least 2 string array elements.

Section 3.7: Array Assignment

As mentioned in "Section 3.1: Lists vs Arrays", normal Perl allows you to perform a special kind of array assignment with multiple variables on the left (receiving) side of the equal sign = assignment operator. This is one of Perl's countless shortcuts, allowing a software developer to initialize or modify more than one variable in a single statement.

    my ($x, $y, $z)       = @array_by_value;  # fine in Perl, error in RPerl, stored-by-value array assigned to list of scalar variables
    my ($foo, $bar, $bat) = (10, 20, 30);     # fine in Perl, error in RPerl, list                  assigned to list of scalar variables

In RPerl, we support exactly one variable on the left side of each assignment operator. If you need to initialize or modify multiple variables, simply separate each into its own statement. The source code below achieves the same goals as the code above, without utilizing special array assignment statements. Each line of source code above has been expanded into three equivalent lines below.

    my integer $x = $array_by_reference->[0];  # fine in Perl, fine in RPerl, stored-by-reference array element assigned to scalar variable
    my integer $y = $array_by_reference->[1];
    my integer $z = $array_by_reference->[2];

    my integer $foo = 10;                      # fine in Perl, fine in RPerl, scalar assigned to scalar variable
    my integer $bar = 20;
    my integer $bat = 30;

Section 3.8: push & pop Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Push

push

Variadic

Prefix

01

Left

Coming Soon

Pop

pop

Unary

Prefix

01

Left

Coming Soon

Section 3.9: shift & unshift Operators

Name

Symbol

Arity

Fixity

Precedence

Associativity

Supported

Shift

shift

Unary

Prefix

01

Left

Coming Soon

Unshift

unshift

Variadic

Prefix

01

Left

Coming Soon

Section 3.10: Converting From Array To String

The terms "stringify" and "pretty print" refer to the conversion from any non-string data type or data structure into a string data type.

As mentioned in L </INSERT_SECTION>, RPerl provides the following stringification functions:

The integer_arrayref_to_string() function is implemented by the following Perl source code:

Section 3.11: Program Control Using The foreach Loop

START HERE: add content

Section 3.12: Punctuation Variables & Magic [[[ NEED ADD MAGIC INTRO SECTION SOMEWHERE??? ]]]

START HERE: add content

Section 3.13: reverse Operator

START HERE: add content

Section 3.14: sort Operator

START HERE: add content

Section 3.15: Scalar & Array Contexts

START HERE: add content

Section 3.16: Array Values In Scalar Context

START HERE: add content

Section 3.17: Scalar Values In Array Context

START HERE: add content

Section 3.18: Explicitly Scalar Context

START HERE: add content

Section 3.19: STDIN & Arrays

START HERE: add content

"Square brackets" are also known as just "brackets" for short.

Closely related to the loop concept of an iterator variable is that of an "index", and depending upon the usage you may argue the "i" in $i stands for either "iterator" or "index". The main difference between an iterator and an index are usage: an iterator is an integer variable used to count loop iterations; whereas an index is a numeric value used to specify an array element, and may be either an integer variable or a hard-coded integer literal. An iterator can always be used as an index, but an index by definition is not meant to be used as an iterator.

types() introspection subroutine

Section 3.20: SSE Operators

    OP08_MATH_ADD_SUB         = /(sse_add|sse_sub)/    # precedence 08 infix: SSE add 'sse_add', SSE subtract 'sse_sub'
    OP07_MATH_MULT_DIV_MOD    = /(sse_mul|sse_div)/  # precedence 07 infix: SSE multiply 'sse_mul', SSE divide 'sse_div'


CHAPTER 4: ORGANIZING BY SUBROUTINES

    our void $SWEET_TOOTH = sub { print 'Yum!  I love ', PIE(), "\n"; };  # error in RPerl, compiled modes
    our void $Sweet_Tooth = sub { print 'Yum!  I love ', PIE(), "\n"; };  # okay
    our void $sweet_tooth = sub { print 'Yum!  I love ', PIE(), "\n"; };  # best


CHAPTER 5: READING & WRITING FILES


CHAPTER 6: HASH VALUES & VARIABLES

A hash may not be a constant.

types() introspection subroutine


CHAPTER 7: THE REGULAR EXPRESSION SUB-LANGUAGE


CHAPTER 8: MATCHING BY REGULAR EXPRESSIONS


CHAPTER 9: PROCESSING BY REGULAR EXPRESSIONS


CHAPTER 10: ADDITIONAL CONTROL STRUCTURES


CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES


CHAPTER 12: FILE TEST OPERATORS

Section 12.x.x: File Test Operators

    %token OP10_NAMED_UNARY_SCOLON   = /(-A;|-B;|-C;|-M;|-O;|-R;|-S;|-T;|-W;|-X;|-b;|-c;|-d;|-e;|-f;|-g;|-k;|-l;|-o;|-p;|-r;|-s;|-t;|-u;|-w;|-x;|-z;)/


CHAPTER 13: DIRECTORY OPERATORS


CHAPTER 14: SORTING TEXT VALUES


CHAPTER 15: ADDITIONAL SPECIAL OPERATORS


CHAPTER 16: MANAGING OPERATING SYSTEM PROCESSES


CHAPTER 17: ADDITIONAL ADVANCED TECHNIQUES

Section 17.x.x: UNSORTED Operators

# REGEX %token OP01_NAMED_SCOLON = /(m;|pos;|qr;|s;|study;|tr;|y;

# FORMAT %token OP01_NAMED_SCOLON = /(format;|formline;|write;

# PACK / UNPACK %token OP01_NAMED_SCOLON = /(pack;|unpack;|vec;|

# UNSORTED TEMPORARILY HIDDEN FROM VIEW


APPENDIX A: EXERCISE ANSWERS

Chapter 1, Exercise 1

This exercise is commonly used as the first task for new programmers, or for programmers who are learning a new language.
The goal of this exercise is to become familiar with the boilerplate (often-repeated template) RPerl HEADER and CRITICS code sections, as well as the basic print operator.
The first line, starting with #! and called a "shebang", tells the operating system to run this program using Perl.
The 4 lines in the HEADER section tell Perl to run this program using RPerl, and the $VERSION number may be incremented for each update to this file.
The line in the CRITICS section, starting with ##, tells RPerl to allow hard-coded numeric values (not used in this program), as well as the print operator.
The last line, in the OPERATIONS section, calls the print operator on a comma-separated list consisting of 2 string literals, which will simply display the text "Hello, world!" followed by a newline character.
All other lines beginning with # are comments and, along with blank lines, may be safely ignored or removed.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 1, Exercise 1
    # Print "Hello, world!"; the classic first program for new programmers

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator

    # [[[ OPERATIONS ]]]
    print 'Hello, world!', "\n";

Example execution and output:

    $ rperl -t LearningRPerl/Chapter1/exercise_1-hello_world.pl
    Hello, world!


Chapter 1, Exercise 2

The goal of this exercise is to become familiar with the `rperl` command.

Example execution and output for 2a and 2b:

    $ rperl -?
    Usage:
                rperl [ARGUMENTS] input_program_0.pl [input_program_1.pl input_program_2.pl ...]
                rperl [ARGUMENTS] MyClassFoo.pm [MyClassBar.pm MyClassBat.pm ...]
                rperl [ARGUMENTS] input_program_0.pl MyClassFoo.pm [input_program_1.pl ... MyClassBar.pm ...]
    
    Arguments:
        --help ...OR... -h ...OR... -?
                Print this (relatively) brief help message for command-line usage.
                For additional explanations, run the command `perldoc RPerl::Learning` and see Appendix B.
    
        --version ...OR... -v
        --vversion ...OR... -vv
                Print version number and copyright information.
                Repeat as 'vv' for more technical information, similar to `perl -V` configuration summary argument.
                Lowercase 'v' not to be confused with uppercase 'V' in 'Verbose' argument.
    
        --infile=MyFile.pm ...OR... -i=MyFile.pm
                Specify input file, may be repeated for multiple input files.
                Argument prefix '--infile' may be entirely omitted.
                Argument prefix MUST be omitted to specify wildcard for multiple input files.
    
        --outfile=MyCompiledModule ...OR... -o=MyCompiledModule
        --outfile=my_compiled_program ...OR... -o=my_compiled_program
                Specify output file prefix, may be repeated for multiple output files.
                RPerl *.pm input file with PERL ops will create MyCompiledModule.pmc output file.
                RPerl *.pl input file with PERL ops will create my_compiled_program (or my_compiled_program.exe on Windows) output file.
                RPerl *.pm input file with CPP  ops will create MyCompiledModule.pmc, MyCompiledModule.cpp, & MyCompiledModule.h output files.
                RPerl *.pl input file with CPP  ops will create my_compiled_program (or my_compiled_program.exe on Windows) & my_compiled_program.cpp output files.
                Argument may be entirely omitted, foo.* input file will default to foo.* output file(s).
    
        --CXX=/path/to/compiler
                Specify path to C++ compiler for use in subcompile modes, equivalent to '--mode CXX=/path/to/compiler' or 'CXX' manual Makefile argument, 'g++' by default.
    
        --mode ops=PERL ...OR... -m ops=PERL
        --mode ops=CPP ...OR... -m ops=CPP
                Specify operations mode, CPP by default.
                If set to PERL, generate Perl operations in the source code output file(s).
                If set to CPP, generate C++ operations in the source code output file(s).
                PERL ops mode forces PERL types mode & PARSE or GENERATE compile mode; PERLOPS_PERLTYPES is test mode, does not actually compile.
    
        --mode types=PERL ...OR... -m types=PERL
        --mode types=CPP ...OR... -m types=CPP
        --mode types=DUAL ...OR... -m types=DUAL
                Specify data types mode, CPP by default.
                If set to PERL, generate Perl data types in the source code output file(s).
                If set to CPP, generate C++ data types in the source code output file(s).
                If set to DUAL, generate both Perl and C++ data types in the source code output file(s).
                DUAL mode allows generate-once-compile-many types, selected by '#define __FOO__TYPES' in lib/rperltypes_mode.h or `gcc -D__FOO__TYPES` manual subcompile argument.
    
        --mode check=OFF ...OR... -m check=OFF
        --mode check=ON ...OR... -m check=ON
        --mode check=TRACE ...OR... -m check=TRACE
                Specify data type checking mode, TRACE by default.
                If set to OFF, do not perform dynamic type checking, only built-in C++ static type checking.
                If set to ON, perform dynamic type checking in addition to built-in C++ static type checking.
                If set to TRACE, perform dynamic type checking in addition to built-in C++ static type checking, with subroutine-and-variable trace information.

    [[[ REMAINING ARGUMENTS OMITTED FOR BREVITY ]]]

Example execution and output for 2c and 2d:

    $ rperl -t -V LearningRPerl/Chapter1/exercise_1-hello_world.pl 
    Verbose Flag:       1
    Debug Flag:         0
    Test Flag:          1
    Input File:         LearningRPerl/Chapter1/exercise_1-hello_world.pl
    Output File(s):     LearningRPerl/Chapter1/exercise_1-hello_world  
    Modes:              ops => PERL, types => PERL, check => TRACE, compile => GENERATE, execute => ON, label => ON

    DEPENDENCIES:       Follow & find all deps...    0 found.
    PARSE PHASE 0:      Check     Perl syntax...        done.
    PARSE PHASE 1:      Criticize Perl syntax...        done.
    PARSE PHASE 2:      Parse    RPerl syntax...        done.
    GENERATE:           Generate RPerl syntax...        done.
    EXECUTE:            Run code...

    Hello, world!


    $ rperl -t -D LearningRPerl/Chapter1/exercise_1-hello_world.pl 
    in rperl, have $RPerl::DEBUG = 1
    in rperl, have $RPerl::VERBOSE = 0
    Hello, world!


    $ rperl -t -V -D LearningRPerl/Chapter1/exercise_1-hello_world.pl 
    Verbose Flag:       1
    Debug Flag:         1
    Test Flag:          1

    in rperl, have $RPerl::DEBUG = 1
    in rperl, have $RPerl::VERBOSE = 1
    Input File:         LearningRPerl/Chapter1/exercise_1-hello_world.pl
    Output File(s):     LearningRPerl/Chapter1/exercise_1-hello_world  
    Modes:              ops => PERL, types => PERL, check => TRACE, compile => GENERATE, execute => ON, label => ON

    DEPENDENCIES:       Follow & find all deps...    0 found.
    PARSE PHASE 0:      Check     Perl syntax...        done.
    PARSE PHASE 1:      Criticize Perl syntax...        done.
    PARSE PHASE 2:      Parse    RPerl syntax...        done.
    GENERATE:           Generate RPerl syntax...        done.
    EXECUTE:            Run code...

    Hello, world!

Of the above 3 commands executed for 2c and 2d, the first includes normal output plus additional verbose output; the second includes normal output plus additional debugging output (minimal in this simple case); and the third includes normal output plus both verbose and debugging output.


Chapter 1, Exercise 3

The goal of this exercise is to become familiar with basic variables and arithmetic.
The shebang line, HEADER section, and first line in the CRITICS section are the same boilerplate as the previous exercise.
The second line in the CRITICS section tells RPerl to allow the $ (dollar) character, among others, to be displayed using the print operator.
The first 3 lines in the OPERATIONS section each declare a new variable; $foo and $bar each hold an integer (non-floating-point) numeric value, while $baz holds a number (floating-point) value.
The $foo and $bar variables receive their values from hard-coded numeric values being operated upon by the addition + and multiplication * operators, respectively; the $baz and $zab variables receive their values from the the $foo and $bar variables being operated upon by the division / operator. The to_number() type conversion subroutine is necessary for the C++ compiler to use floating-point arithmetic instead of integer arithmetic on the division / operators, without it we would receive the truncated integer value of 58 in $baz, for example. We will receive the correct floating-point answers if we call to_number() on either $bar (as shown), or $foo, or both; in other words, at least one of the input operands for each operator must be passed through to_number().
The last 4 lines call the print operator to display the names of each variable; followed by each variable's respective value, converted from number to underscore-formatted string via the RPerl type conversion subroutine to_string(); followed by a newline character.

    #!/usr/bin/perl
    
    # Learning RPerl, Chapter 1, Exercise 3
    # Foo Bar Arithmetic Example
    
    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;
    
    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    
    # [[[ OPERATIONS ]]]
    my integer $foo = 21 + 12;
    my integer $bar = 23 * 42;
    my number  $baz = to_number($bar) / $foo;
    my number  $zab = to_number($foo) / $bar;
    print 'have $foo = ', to_string($foo), "\n";
    print 'have $bar = ', to_string($bar), "\n";
    print 'have $baz = ', to_string($baz), "\n";
    print 'have $zab = ', to_string($zab), "\n";

Example execution and output:

    $ rperl -t LearningRPerl/Chapter1/exercise_3-foo_bar_arithmetic.pl 
    have $foo = 33
    have $bar = 966
    have $baz = 29.272_727_272_727_3
    have $zab = 0.034_161_490_683_229_8


Chapter 2, Exercise 1

The goal of this exercise is to become familiar with constant values.
The first line in the CRITICS section tells RPerl to allow hard-coded numeric values as well as the print operator, both of which are utilized in this program.
The second line in the CRITICS section tells RPerl to allow the use constant operation.
The line in the CONSTANTS section declares a number (floating-point) constant value named PI, automatically accessible via a subroutine named PI().
The inner type variable $TYPED_PI is only used for RPerl parsing purposes; for example, if your constant is named FOO then you should declare it using the inner type variable $TYPED_FOO and you should access it by calling the subroutine FOO(), but you should never directly utilize the variable $TYPED_FOO anywhere else in your code.
The first 2 lines in the OPERATIONS section each create a new number variable, with $radius set to the hard-coded value of 12.5 and $circumference set to the well-known basic geometry formula "circumference equals 2 pi times radius".
The last 3 lines call the print operator to display the values of PI, $radius, and $circumference, each followed by a newline character.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 1
    # Find the circumference of a circle with hard-coded radius of 12.5 units

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants

    # [[[ CONSTANTS ]]]
    use constant PI => my number $TYPED_PI = 3.141_592_654;

    # [[[ OPERATIONS ]]]
    my number $radius = 12.5;
    my number $circumference = 2 * PI() * $radius;

    print 'Pi = ', to_string(PI()), "\n";
    print 'Radius = ', to_string($radius), "\n";
    print 'Circumference = 2 * Pi * Radius = 2 * ', to_string(PI()), ' * ', to_string($radius), ' = ', to_string($circumference), "\n";

Example execution and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_1-circumference_of_specific_radius.pl 
    Pi = 3.141_592_654
    Radius = 12.5
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * 12.5 = 78.539_816_35


Chapter 2, Exercise 2

The goal of this exercise is to become familiar with accepting user keyboard input.
The third line in the CRITICS section tells RPerl to allow user input via the <STDIN> standard stream, a software input connection which is attached to the keyboard by default.
The second line in the OPERATIONS section creates a string variable $radius_string, and assigns to it the text value typed by the user on their keyboard.
The third line in the OPERATIONS section creates a number variable $radius, and assigns to it the numeric value returned by calling the RPerl type conversion subroutine string_to_number() on the string variable $radius_string.
This exercise is otherwise identical to the previous exercise.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 2
    # Find the circumference of a circle with any radius entered by the user

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ CONSTANTS ]]]
    use constant PI => my number $TYPED_PI = 3.141_592_654;

    # [[[ OPERATIONS ]]]
    print 'Please input radius: ';
    my string $radius_string = <STDIN>;
    my number $radius = string_to_number($radius_string);
    my number $circumference = 2 * PI() * $radius;

    print "\n";
    print 'Pi = ', to_string(PI()), "\n";
    print 'Radius = ', to_string($radius), "\n";
    print 'Circumference = 2 * Pi * Radius = 2 * ', to_string(PI()), ' * ', to_string($radius), ' = ', to_string($circumference), "\n";

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_2-circumference_of_any_radius.pl 
    Please input radius: 2

    Pi = 3.141_592_654
    Radius = 2
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * 2 = 12.566_370_616


Chapter 2, Exercise 3

The goal of this exercise is to become familiar with conditional statements and comparison operators.
In the OPERATIONS section, the line starting with if ($radius >= 0) denotes the beginning of a conditional statement: if the numeric value of the variable $radius is greater-than-or-equal-to 0, then the normal calculation for $circumference is used; if $radius is less than 0 (physically impossible), then a warning message is printed and $circumference is set to 0.
This exercise is otherwise identical to the previous exercise.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 3
    # Find the circumference of a circle with any positive radius entered by the user

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ CONSTANTS ]]]
    use constant PI => my number $TYPED_PI = 3.141_592_654;

    # [[[ OPERATIONS ]]]
    print 'Please input radius: ';
    my string $radius_string = <STDIN>;
    my number $radius = string_to_number($radius_string);
    my number $circumference;

    if ($radius >= 0) {
        $circumference = 2 * PI() * $radius;
    }
    else {
        print 'Negative radius detected, defaulting to zero circumference!', "\n";
        $circumference = 0;
    }

    print "\n";
    print 'Pi = ', to_string(PI()), "\n";
    print 'Radius = ', to_string($radius), "\n";
    print 'Circumference = 2 * Pi * Radius = 2 * ', to_string(PI()), ' * ', to_string($radius), ' = ', to_string($circumference), "\n";

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_3-circumference_of_any_positive_radius.pl 
    Please input radius: -2
    Negative radius detected, defaulting to zero circumference!

    Pi = 3.141_592_654
    Radius = -2
    Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * -2 = 0


Chapter 2, Exercise 4

The goal of this exercise is to gain further exposure to the <STDIN> standard stream and variable multiplication.
In the OPERATIONS section, <STDIN> is accessed to collect user input for both the $multiplicator_string and $multiplicand_string variables.
These 2 string variables are converted from text values to numeric values by calling string_to_number(), then multiplied via the * multiplication operator, and the results displayed by calling print.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 4
    # Find the product of any two numbers entered by the user

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    print 'Please input multiplicator: ';
    my string $multiplicator_string = <STDIN>;
    my number $multiplicator = string_to_number($multiplicator_string);

    print 'Please input multiplicand: ';
    my string $multiplicand_string = <STDIN>;
    my number $multiplicand = string_to_number($multiplicand_string);

    my number $product = $multiplicator * $multiplicand;

    print "\n";
    print 'Product = Multiplicator * Multiplicand = ', to_string($multiplicator), ' * ', to_string($multiplicand), ' = ', to_string($product), "\n";

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_4-product_of_any_two_numbers.pl 
    Please input multiplicator: 2112
    Please input multiplicand: 23.42

    Product = Multiplicator * Multiplicand = 2_112 * 23.42 = 49_463.04


Chapter 2, Exercise 5

The goal of this exercise is to become familiar with the x string repeat operator.
In the OPERATIONS section, <STDIN> is accessed twice to collect user input for a string variable $repeat_string to be repeated, and an integer variable $repeat_integer to specify the number of repetitions.
The last line contains 2 operators, print and the x string repeat operator.
Like the . (single dot) string concatenation operator, the x operator has a higher precedence than print and is thus executed first, generating a single string value comprised of the original string repeated 0 or more times, then the resulting string is displayed by calling print.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 5
    # Repeat any string any number of times, both values entered by the user

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    print 'Please input string to be repeated: ';
    my string $repeat_string = <STDIN>;

    print 'Please input integer (whole number) times to repeat string: ';
    my string $repeat_integer_string = <STDIN>;
    my integer $repeat_integer = string_to_integer($repeat_integer_string);

    print "\n";
    print $repeat_string x $repeat_integer;

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_5-string_repeat.pl 
    Please input string to be repeated: howdy
    Please input integer (whole number) times to repeat string: 3

    howdy
    howdy
    howdy


Chapter 2, Exercise 6

The goal of this exercise is to become familiar with the while loop control structure.
In the OPERATIONS section, <STDIN> is accessed to collect user input into the string variable $n_string, then the data type conversion subroutine string_to_integer() is called to create the corresponding integer variable $n.
The if ($n < 0) conditional control structure calls die to exit with an error message if $n is not a positive value.
Two additional integer variables are created: $sum is initialized to 0 and will eventually hold the final answer value; and $i is initialized to 0 for use as the iteration counter variable (AKA "iterator") inside the following while loop control structure.
The while loop iteratively executes as long as the integer value of $i is less-than-or-equal-to $n. Each iteration of the while loop causes the value of $sum to be increased by $i, after which $i itself is incremented by 1, and the loop is repeated.
The last line calls print, the to_string() conversion subroutine, and the . (single dot) string concatenation operator to display the final answer.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 6
    # Calculate the sum of the first n integers; 1 + 2 + 3 + ... + n = ?

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    print 'Please input a positive integer: ';
    my string $n_string = <STDIN>;
    my integer $n = string_to_integer($n_string);

    if ($n < 0) { die 'ERROR: ' . to_string($n) . ' is not positive, dying' . "\n"; }

    my integer $sum = 0;
    my integer $i = 1;

    while ($i <= $n) {
        $sum += $i;
        $i++;
    }

    print 'The sum of the first ', to_string($n), ' integers is ', to_string($sum), "\n";

Example executions, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_6-sum_of_first_n_integers.pl 
    Please input a positive integer: 100
    The sum of the first 100 integers is 5_050

    $ rperl -t LearningRPerl/Chapter2/exercise_6-sum_of_first_n_integers.pl 
    Please input a positive integer: -100
    ERROR: -100 is not positive, dying


Chapter 2, Exercise 7

The goal of this exercise is to utilize an optimization to remove the while loop from the previous exercise.
In the OPERATIONS section, user input is collected and error-checked, as before.
By utilizing an algorithm attributed to Gauss, we are able to remove the while loop, so we also remove the $i loop iterator. The $sum variable is kept the same as the previous exercise.
Two new integer variables are also created: $n_original is initialized to hold a copy of $n which will never change; and $n_odd is initialized to 0.
The code block beginning with if ($n % 2) is used to detect if the user provided a value for $n which is odd (not even), this is detected by utilizing the % modulo operator to test for a remainder of dividing $n by 2. If $n is odd, then a second copy of the original value of $n is stored in $n_odd, after which $n itself is decremented by 1. This if statement allows our algorithm to accept odd as well as even user input values for $n.
The computational kernel (most important part) is the one line of arithmetic: $sum = (($n + 1) * ($n / 2)) + $n_odd;
Recall the story of Gauss's algorithm in the exercise description; our arithmetic generalizes the idea of young Gauss by using $n instead of 100, and by adding $n_odd to enable support for odd values of $n. Using Gauss' own example of $n equal to 100, which is even (not odd) so $n_odd will equal 0, we can see the algorithm becomes: $sum = ((100 + 1) * (100 / 2)) + 0;
One more step of arithmetic simplification shows our algorithm to be the same as Gauss': $sum = 101 * 50;
The last line calls print using the value of $n_original, because the value of $n will have been decreased by 1 if $n is odd.
It is usually faster to run an algorithm without a loop than with a loop, because you are only doing 1 thing instead of many things. However, not all problems can be easily optimized by changing to a new algorithm, because it may be prohibitively complex or there may only be 1 known algorithm. In this case, Gauss' algorithm should be faster than the while loop algorithm, expecially for very large values of $n. It may be possible to further optimize this exercise by utilizing bitwise operators to replace the modulo and division operators.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 2, Exercise 7
    # Calculate the sum of the first n integers, without using a loop; 1 + 2 + 3 + ... + n = ?

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    print 'Please input a positive integer: ';
    my string $n_string = <STDIN>;
    my integer $n = string_to_integer($n_string);

    if ($n < 0) { die 'ERROR: ' . to_string($n) . ' is not positive, dying' . "\n"; }

    my integer $sum = 0;
    my integer $n_original = $n;
    my integer $n_odd = 0;

    if ($n % 2) {
        $n_odd = $n;
        $n--;
    }

    $sum = (($n + 1) * ($n / 2)) + $n_odd;

    print 'The sum of the first ', to_string($n_original), ' integers is ', to_string($sum), "\n";

Example executions, input, and output:

    $ rperl -t LearningRPerl/Chapter2/exercise_7-sum_of_first_n_integers_no_loop.pl 
    Please input a positive integer: 100
    The sum of the first 100 integers is 5_050

    $ rperl -t LearningRPerl/Chapter2/exercise_7-sum_of_first_n_integers_no_loop.pl 
    Please input a positive integer: -100
    ERROR: -100 is not positive, dying


Chapter 3, Exercise 1

The goal of this exercise is to become familiar with the foreach loop control structure, arrays, and array operators; and to become further familiarized with the while loop.
The first line in the OPERATIONS section declares a new variable $input_strings of type string_arrayref, which is capable of storing 0 or more individual string values, and $input_strings is then initialized to contain the empty set [].
The line starting with while (my string $input_string = <STDIN>) denotes the beginning of an iterative (repeating) loop statement, which continues to accept and store user input until CTRL-D is pressed to indicate the EOF (end-of-file) condition, also known as EOT (end-of-transmission).
A new copy of the variable $input_string is created and assigned the value of collected user input by calling <STDIN> at the start of each loop iteration; the my operator is evaluated as a true condition and the loop repeats, until CTRL-D is received and the my operator returns a false condition.
Inside the body of the while loop is 1 line calling the push operator, which appends the current iteration's value of $input_string onto the list of strings contained in $input_strings.
The @{...} (at-sign-curly-braces) is the array dereference operator, which exists because in Perl it is still sometimes necessary to directly access an array by value, instead of the RPerl method of indirectly accessing the array by reference, such as is required by the push operator.
The line starting with my string_arrayref $input_strings_reversed declares another array of string values input_strings_reversed, and then assigns it the strings contained within the first array $input_strings in reversed order, as returned by calling the reverse operator.
As with the push operator, the reverse operator requires its argument to be dereferenced using @{...}; another dereferenced array value is returned by reverse, and an array reference is returned by enclosing reverse and its argument inside the [...] (square brackets) array reference operator.
Finally, the line starting with foreach my string $input_strings_reversed_element denotes the beginning of another loop statement, which iterates the value of $input_strings_reversed_element once for each string value contained in the $input_strings_reversed array; print is called inside the loop body to display the original input strings in reverse order.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 3, Exercise 1
    # Print user-supplied list of strings in reverse order

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    my string_arrayref $input_strings = [];

    print 'Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:', "\n";

    while (my string $input_string = <STDIN>) {
        push @{$input_strings}, $input_string;
    }

    print "\n";
    print 'Strings in reverse order:', "\n";

    my string_arrayref $input_strings_reversed = [reverse @{$input_strings}];

    foreach my string $input_strings_reversed_element (@{$input_strings_reversed}) {
        print $input_strings_reversed_element;
    }

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter3/exercise_1-stdin_strings_reverse.pl 
    Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:
    howdy
    doody
    buffalo
    bob
    clarabell
    clown

    Strings in reverse order:
    clown
    clarabell
    bob
    buffalo
    doody
    howdy


Chapter 3, Exercise 2

The goal of this exercise is to become familiar with utilizing array indices.
The first line in the OPERATIONS section declares a new variable $flintstones_and_rubbles of type string_arrayref, which is then initialized to contain a qw() (quoted word) set of names including the string element 'fred' at array index 0, 'betty' at array index 1, and so on.
The second line in OPERATIONS creates an empty array of integers $input_indices, and the following while loop uses the push operator to fill $input_indices with integers entered by the user.
The foreach loop iterates through all the user input integers, placing each in the variable $input_index.
Inside the foreach loop, the variable $input_index is used to access the individual names inside the variable $flintstones_and_rubbles.
In Perl, all array indices start at 0 instead of 1, so we must first subtract 1 from $input_index before accessing the individual string elements of $flintstones_and_rubbles.
Thus, if a user inputs the integer 1, the array index will be 0, which is 'fred'; similarly, user input 5 will access array index 4 which is 'wilma'.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 3, Exercise 2
    # Print string array elements indexed by user-supplied integers

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ OPERATIONS ]]]
    my string_arrayref $flintstones_and_rubbles = [qw(fred betty barney dino wilma pebbles bamm-bamm)];
    my integer_arrayref $input_indices          = [];

    print 'Please input zero or more integers with values ranging from 1 to 7, separated by <ENTER>, ended by <CTRL-D>:', "\n";

    while ( my string $input_string = <STDIN> ) {
        push @{$input_indices}, string_to_integer($input_string);
    }

    print "\n";
    print 'Flintstones & Rubbles:', "\n";

    foreach my integer $input_index ( @{$input_indices} ) {
        print $flintstones_and_rubbles->[ ( $input_index - 1 ) ], "\n";
    }

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter3/exercise_2-stdin_array_indices.pl 
    Please input zero or more integers with values ranging from 1 to 7, separated by <ENTER>, ended by <CTRL-D>:
    2
    5
    3
    6
    5
    1
    2
    7
    4
    4

    Flintstones & Rubbles:
    betty
    wilma
    barney
    pebbles
    wilma
    fred
    betty
    bamm-bamm
    dino
    dino


Chapter 3, Exercise 3

The goal of this exercise is to become familiar with the sort and chomp operators.
In the CONSTANTS section, a constant SINGLE_LINE_OUTPUT is created and set to 0, which will cause the program's output to be displayed on multiple lines. If SINGLE_LINE_OUTPUT is instead set to 1, the program's output will be displayed on one line.
In the OPERATIONS section, a while loop is used to fill the array variable $input_strings with data supplied by the user.
The sort operator is then called to fill the $input_strings_sorted array with the same data in ASCII alphabetical order.
Last, a foreach loop is used to print the sorted output by storing and accessing one string at a time in the variable $input_strings_sorted_element.
An if conditional statement inside the foreach loop tests the constant SINGLE_LINE_OUTPUT; if the condition is true, then the chomp operator is called to remove the newline character from each string element and replace it with a normal blank space character, thereby displaying all the elements on a single line of output.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 3, Exercise 3
    # Print user-supplied list of strings in ASCIIbetical order, optionally on single line of output

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ CONSTANTS ]]]
    use constant SINGLE_LINE_OUTPUT => my boolean $TYPED_SINGLE_LINE_OUTPUT = 0;

    # [[[ OPERATIONS ]]]
    my string_arrayref $input_strings = [];

    print 'Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:', "\n";

    while ( my string $input_string = <STDIN> ) {
        push @{$input_strings}, $input_string;
    }

    print "\n";
    print 'Strings in ASCIIbetical order:', "\n";

    my string_arrayref $input_strings_sorted = [ sort @{$input_strings} ];

    foreach my string $input_strings_sorted_element ( @{$input_strings_sorted} ) {
        if ( SINGLE_LINE_OUTPUT() ) {

            # strip trailing newline, if present
            chomp $input_strings_sorted_element;
            $input_strings_sorted_element .= q{ };
        }

        print $input_strings_sorted_element;
    }

    print "\n";

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter3/exercise_3-stdin_strings_sort.pl 
    Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:
    howdy
    doody
    buffalo
    bob
    clarabell
    clown

    Strings in ASCIIbetical order:
    bob
    buffalo
    clarabell
    clown
    doody
    howdy


Chapter 4, Exercise 1

The goal of this exercise is to become familiar with user-defined subroutines.
In the SUBROUTINES section, one subroutine total() is defined, which accepts as input one argument variable $input_numbers of type number_arrayref, and which also has a number return value stored in the variable $retval.
Inside the total() subroutine, the return value is initialized to 0 in $retval, then a foreach loop iteratively adds the elements of the array $input_numbers to $retval, after which the value of $retval is returned to original external caller of total().
By itself, a subroutine such as total() does not actually do anything; every subroutine must first be called either by some other subroutine or in the OPERATIONS section.
In OPERATIONS, a 5-element array is created and stored in the variable $fred, which is then passed as input to the subroutine total(), and the return value is displayed using the variable $fred_total and the print operator.
Next, a while loop and <STDIN> are used to collect user input strings, which are then converted to numeric data values using the string_to_number() subroutine, and stored in the array $input_numbers using the push operator.
Finally, the subroutine total() is called a second time, now with the variable $input_numbers passed as the input argument, and the return value is displayed using the variable $user_total.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 4, Exercise 1
    # Subroutine & driver to calculate the totals of arrays of stringified numbers, both hard-coded and user-supplied

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our number $total = sub {
        (my number_arrayref $input_numbers) = @_;
        my number $retval = 0;
        foreach my number $input_number (@{$input_numbers}) {
            $retval += $input_number;
        }
        return $retval;
    };

    # [[[ OPERATIONS ]]]

    my number_arrayref $fred = [1, 3, 5, 7, 9];
    my number $fred_total = total($fred);
    print 'The total of $fred is ', to_string($fred_total), "\n";

    print 'Please input zero or more numbers, separated by <ENTER>, ended by <CTRL-D>:', "\n";

    my number_arrayref $input_numbers = [];
    while (my string $input_string = <STDIN>) {
        push @{$input_numbers}, string_to_number($input_string);
    }

    my number $user_total = total($input_numbers);
    print 'The total of those numbers is ', to_string($user_total), "\n";

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter4/exercise_1-subroutine_total.pl 
    The total of $fred is 25
    Please input zero or more numbers, separated by <ENTER>, ended by <CTRL-D>:
    21.12
    23.42
    1701.877
    -123.456
    The total of those numbers is 1_622.961


Chapter 4, Exercise 2

The goal of this exercise is to become familiar with the .. range operator.
In the SUBROUTINES section, the same subroutine total() is defined as in the previous exercise.
In the OPERATIONS section, an array of numbers is created and stored in the variable $one_to_one_thousand.
Upon execution, there will be 1,000 number elements in the array, which are automatically created by the .. range operator.
The actual elements stored the array variable $one_to_one_thousand start with [1, 2, 3, 4 and end with 997, 998, 999, 1_000].
Finally, the subroutine total() is called with $one_to_one_thousand passed as the input argument, and the return value is displayed using the variable $one_to_one_thousand_total.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 4, Exercise 2
    # Subroutine & driver to calculate the total of 1 to 1,000

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator

    # [[[ SUBROUTINES ]]]

    our number $total = sub {
        ( my number_arrayref $input_numbers ) = @_;
        my number $retval = 0;
        foreach my number $input_number ( @{$input_numbers} ) {
            $retval += $input_number;
        }
        return $retval;
    };

    # [[[ OPERATIONS ]]]

    my number_arrayref $one_to_one_thousand = [ 1 .. 1_000 ];
    my number $one_to_one_thousand_total    = total($one_to_one_thousand);
    print 'The total of 1 to 1_000 is ', to_string($one_to_one_thousand_total), q{.}, "\n";

Example execution and output:

    $ rperl -t LearningRPerl/Chapter4/exercise_2-subroutine_total_1000.pl 
    The total of 1 to 1000 is 500_500.


Chapter 4, Exercise 3

The goal of this exercise is to become familiar with calling user-defined subroutines from one another.
In the SUBROUTINES section, 3 subroutines are defined: total() (same as previous exercises), average(), and above_average().
Inside the subroutine average() is a call to the subroutine total(); there is also a call to the scalar operator, which returns the count of elements inside the array $input_numbers. When the return value of total() is divided by that of scalar, the result is computation of the numeric mean (average) of all elements of $input_numbers.
Inside above_average() is a call to the subroutine average(), with the return value stored in the variable $average. An empty array is created in the variable $retval, then a foreach loop iterates over all elements in $input_numbers and an if conditional statement makes a copy of all elements which are greater than $average. All above-average elements are returned as an array in $retval.
In the OPERATIONS section, 2 arrays are created in the $fred and $barney variables, which are then passed as input arguments to 2 calls to the subroutine above_average(), and the results are displayed.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 4, Exercise 3
    # Subroutines & driver to calculate the above-average elements of hard-coded arrays

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our number $total = sub {
        ( my number_arrayref $input_numbers ) = @_;
        my number $retval = 0;
        foreach my number $input_number ( @{$input_numbers} ) {
            $retval += $input_number;
        }
        return $retval;
    };  

    our number $average = sub {
        ( my number_arrayref $input_numbers ) = @_;
        return (total($input_numbers) / (scalar @{$input_numbers}));
    };

    our number_arrayref $above_average = sub {
        ( my number_arrayref $input_numbers ) = @_;
        my number $average = average($input_numbers);
        my number_arrayref $retval = [];
        foreach my number $input_number (@{$input_numbers}) {
            if ($input_number > $average) {
                push @{$retval}, $input_number;
            }
        }
        return $retval;
    };

    # [[[ OPERATIONS ]]]

    my string_arrayref $fred = [1 .. 10];
    my number $fred_above_average = above_average($fred);
    print '$fred is ', number_arrayref_to_string($fred), "\n";
    print 'The above-average elements of $fred are ', number_arrayref_to_string($fred_above_average), "\n";
    print '(Should be [6, 7, 8, 9, 10])', "\n\n";

    my string_arrayref $barney = [100, 1 .. 10];
    my number $barney_above_average = above_average($barney);
    print '$barney is ', number_arrayref_to_string($barney), "\n";
    print 'The above-average elements of $barney are ', number_arrayref_to_string($barney_above_average), "\n";
    print '(Should be just [100])', "\n";

Example execution and output:

    $ rperl -t LearningRPerl/Chapter4/exercise_3-subroutine_above_average.pl 
    $fred is [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    The above-average elements of $fred are [6, 7, 8, 9, 10]
    (Should be [6, 7, 8, 9, 10])

    $barney is [100, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    The above-average elements of $barney are [100]
    (Should be just [100])


Chapter 4, Exercise 4

The goal of this exercise is to become familiar with program state.
As a program executes, there may be one or more variables in the OPERATIONS section which store information that is important to the overall program; these variables are collectively known as the "state" of the program.
In the OPERATIONS section, a string variable $previous_name is created and set to the empty string q{}; this 1 variable is the state of the program.
Each of the 4 following lines in the OPERATIONS section utilize the program state by both reading from and writing to the variable $previous_name; the calls to the subroutine greet() read from $previous_name as the 2nd argument, and the return value of greet() is then written to $previous_name by the = assignment operator.
In the SUBROUTINES section, 1 subroutine greet() is defined which accepts 2 string arguments, the variables $name and $previous_name.
Inside greet(), a personalized greeting is displayed for the virtual person represented by the variable $name, after which an if() else conditional statement checks if there is any data inside $previous_name and further displays a customized comment about the state of the program. The state variable $previous_name is used to represent the very simple state of virtual people who have already been greeted.
Finally, the string variable $name is returned from greet() and passed to the = assignment operators in the OPERATIONS section, thereby updating the program state variable $previous_name to contain the value of $name.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 4, Exercise 4
    # Subroutine & driver to greet users

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator

    # [[[ SUBROUTINES ]]]

    our string $greet = sub {
        ( my string $name, my string $previous_name ) = @_;
        print 'Hi ', $name, '!  ';
        if ($previous_name eq q{}) {
            print 'You are the first one here!', "\n";
        }
        else {
            print $previous_name, ' is also here!', "\n";
        }
        return $name;
    };

    # [[[ OPERATIONS ]]]

    my string $previous_name = q{};
    $previous_name = greet('Fred', $previous_name);
    $previous_name = greet('Barney', $previous_name);
    $previous_name = greet('Wilma', $previous_name);
    $previous_name = greet('Betty', $previous_name);

Example execution and output:

    $ rperl -t LearningRPerl/Chapter4/exercise_4-subroutine_greet.pl 
    Hi Fred!  You are the first one here!
    Hi Barney!  Fred is also here!
    Hi Wilma!  Barney is also here!
    Hi Betty!  Wilma is also here!


Chapter 4, Exercise 5

The goal of this exercise is to become further familiarized with program state.
In the OPERATIONS section, the state variable $previous_names is an array of strings representing all previous virtual people who have been greeted.
In the SUBROUTINES section, the subroutine greet() prints the names of previously-greeted virtual people on one line, separated by spaces, by using the join operator.
Finally, the current value of $name is appended as the last element of the array $previous_names by the push operator, and $previous_names is then returned by greet() to update the program state.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 4, Exercise 5
    # Subroutine & driver to greet multiple users

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator

    # [[[ SUBROUTINES ]]]

    our string_arrayref $greet = sub {
        ( my string $name, my string_arrayref $previous_names ) = @_;
        print 'Hi ', $name, '!  ';
        if ((scalar @{$previous_names}) == 0) {
            print 'You are the first one here!', "\n";
        }
        else {
            print q{I've seen: }, (join q{ }, @{$previous_names}), "\n";
        }
        push @{$previous_names}, $name;
        return $previous_names;
    };

    # [[[ OPERATIONS ]]]

    my string_arrayref $previous_names = [];
    $previous_names = greet('Fred', $previous_names);
    $previous_names = greet('Barney', $previous_names);
    $previous_names = greet('Wilma', $previous_names);
    $previous_names = greet('Betty', $previous_names);

Example execution and output:

    $ rperl -t LearningRPerl/Chapter4/exercise_5-subroutine_greet_multiple.pl 
    Hi Fred!  You are the first one here!
    Hi Barney!  I've seen: Fred
    Hi Wilma!  I've seen: Fred Barney
    Hi Betty!  I've seen: Fred Barney Wilma


Chapter 5, Exercise 1

The goal of this exercise is to become familiar with file test operators, as well as opening, closing, and reading from a file.
In the CRITICS section, the ProhibitPostfixControls critic is disabled due to a bug in Perl::Critic and/or PPI which causes a false error.
In the SUBROUTINES section, 1 subroutine tac() is defined which accepts as input an array of file names received via the operating system's command-line arguments, and which has a void return value, meaning there is no return value for this subroutine.
Inside tac(), the reverse operator is called to reverse the order of the command-line arguments; for example, if the 3 file names fred barney betty are given as command-line arguments, then reverse causes the 3 strings betty barney fred to be stored in the array variable $command_line_arguments.
The outer foreach loop iterates through each $file_name in the now-reversed $command_line_arguments.
Next, 4 file test operators are called, to ensure each input file exists via -e, is readable via -r, is a regular (not special device) file via -f, and is comprised of plain text via -T.
The operator open is called with the < file input (read-only) argument, which opens each $file_name for reading via the $FILE filehandle variable.
The inner while loop reads in all lines from the current $FILE filehandle using the <$FILE> syntax (similar to <STDIN>) and stores the input file's lines in the string array variable $file_lines; then, the reverse operator is called again to reverse the order of the newly-read file lines.
Finally, the inner foreach loop displays the now-reversed $file_lines, and the close operator is called to close the $FILE filehandle so no more file access will occur for the current $file_name.
In the OPERATIONS section, the tac() subroutine is called with its only argument being a reference to the special @ARGV array, which is Perl's way of accessing the command-line arguments.
Before executing this program, the non-Perl `printf` program must be called to populate some test data into the 3 input files fred, barney, and betty; and after execution the `rm` program is called to delete the 3 input files.
To begin execution of this program via the `rperl` command, the program name and input file names must be enclosed in either 'single quotes' or "double quotes"; this tells RPerl the input file names are command-line arguments to be passed to the 1 specified program, instead of specifying additional RPerl programs.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 5, Exercise 1
    # Accept one or more input files, and print their contents line-by-line in reverse order

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitPostfixControls)  # SYSTEM SPECIAL 6: PERL CRITIC FILED ISSUE #639, not postfix foreach or if

    # [[[ SUBROUTINES ]]]

    our void $tac = sub {
        ( my string_arrayref $command_line_arguments ) = @_;
        $command_line_arguments = [ reverse @{$command_line_arguments} ];
        foreach my string $file_name ( @{$command_line_arguments} ) {
            if ( not( -e $file_name ) ) {
                croak 'ERROR: File ', $file_name, ' does not exist, croaking';
            }
            if ( not( -r $file_name ) ) {
                croak 'ERROR: File ', $file_name, ' is not readable, croaking';
            }
            if ( not( -f $file_name ) ) {
                croak 'ERROR: File ', $file_name, ' is not a regular file, croaking';
            }
            if ( not( -T $file_name ) ) {
                croak 'ERROR: File ', $file_name, ' is (probably) not text, croaking';
            }

            my integer $open_success = open my filehandleref $FILE, '<', $file_name;
            if ( not $open_success ) {
                croak 'ERROR: Failed to open file ', $file_name, ' for reading, croaking';
            }

            my string_arrayref $file_lines = [];

            while ( my string $file_line = <$FILE> ) {
                push @{$file_lines}, $file_line;
            }

            $file_lines = [ reverse @{$file_lines} ];

            foreach my string $file_line ( @{$file_lines} ) {
                print $file_line;
            }

            if ( not close $FILE ) {
                croak 'ERROR: Failed to close file ', $file_name, ' after reading, croaking';
            }
        }
    };

    # [[[ OPERATIONS ]]]

    tac( [@ARGV] );

Example execution, input, and output:

    $ printf "fred0\nfred1\nfred2\nfred3\nfred4\n" > fred
    $ printf "barney0\nbarney1\nbarney2\n" > barney
    $ printf "betty0\nbetty1\nbetty2\nbetty3\n" > betty
    $ rperl -t 'LearningRPerl/Chapter5/exercise_1-tac.pl fred barney betty'
    betty3
    betty2
    betty1
    betty0
    barney2
    barney1
    barney0
    fred4
    fred3
    fred2
    fred1
    fred0
    $ rm fred barney betty


Chapter 5, Exercise 2

The goal of this exercise is to become familiar with the string length operator and basic text formatting.
In the SUBROUTINES section, 1 subroutine right_justify_20() is defined, which accepts no input arguments and returns no values.
Inside right_justify_20(), an empty array of strings is initialized in the $input_strings variable, which is then populated with strings in a while loop collecting user input from <STDIN>.
The x string repeat operator is called to create a 60-character-wide horizontal ruler, which is then displayed by the print operator.
Finally, a foreach loop iterates through each $input_string and calls the length operator, thereby determining the correct number of spaces to prepend in order to achieve right justification alignment to the 20th character column. The - subtraction operator is passed a hard-coded column width of 20, and the chomp operator is called to remove any trailing newline characters which may be appended when the user presses the ENTER key after each input word.
In the OPERATIONS section, the only operation is a call to the right_justify_20() subroutine.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 5, Exercise 2
    # Accept one or more input lines, and print them in a right-justified 20-column format

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our void $right_justify_20 = sub {
        my string_arrayref $input_strings = [];
        print 'Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:', "\n";
        while ( my string $input_string = <STDIN> ) {
            push @{$input_strings}, $input_string;
        }

        print "\n";
        print '1234567890' x 6;
        print "\n";

        foreach my string $input_string ( @{$input_strings} ) {
            chomp $input_string;
            print q{ } x ( 20 - ( length $input_string ) );
            print $input_string, "\n";
        }
    };

    # [[[ OPERATIONS ]]]

    right_justify_20();

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter5/exercise_2-right_justify.pl
    Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:
    howdy
    doody
    buffalo
    bob
    clarabell
    clown

    123456789012345678901234567890123456789012345678901234567890
                   howdy
                   doody
                 buffalo
                     bob
               clarabell
                   clown


Chapter 5, Exercise 3

The goal of this exercise is to become further familiarized with basic text formatting.
In the SUBROUTINES section, 1 subroutine right_justify_variable() is defined, which accepts no input arguments and returns no values.
Inside right_justify_variable(), the user is prompted to input a custom right justify width, stored in the integer variable $column_width.
The integer variable $ruler_width_tens is used to determine the number of characters displayed for the ruler, by tens; the default value for $ruler_width_tens is 6, which means a ruler width of 60 characters. If the user-supplied $column_width is greater than 60, we scale it by 1/10 and add 1, thereby creating a new value for $ruler_width_tens which will always display a ruler wider than $column_width.
When the ruler is displayed, $ruler_width_tens is passed to the x string repeat operator instead of a hard-coded value of 6; likewise, when each $input_string is right justified, the - subtraction operator is passed $column_width instead of a hard-coded value of 20.
In the OPERATIONS section, the only operation is a call to the right_justify_variable() subroutine.
This exercise is otherwise identical to the previous exercise.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 5, Exercise 3
    # Accept column width followed by one or more input lines, and print lines in a right-justified format

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our void $right_justify_variable = sub {
        my string_arrayref $input_strings = [];
        print 'Please input integer column width, then press <ENTER>:', "\n";
        my string $column_width_string = <STDIN>;
        my integer $column_width       = string_to_integer($column_width_string);

        print 'Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:', "\n";
        while ( my string $input_string = <STDIN> ) {
            push @{$input_strings}, $input_string;
        }

        my integer $ruler_width_tens = 6;    # default to ruler line width 60
        if ( $column_width > 60 ) {
            $ruler_width_tens = number_to_integer( $column_width / 10 ) + 1;
        }

        print "\n";
        print '1234567890' x $ruler_width_tens;
        print "\n";

        foreach my string $input_string ( @{$input_strings} ) {
            chomp $input_string;
            print q{ } x ( $column_width - ( length $input_string ) );
            print $input_string, "\n";
        }
    };

    # [[[ OPERATIONS ]]]

    right_justify_variable();

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter5/exercise_3-right_justify_variable.pl 
    Please input integer column width, then press <ENTER>:
    67
    Please input zero or more strings, separated by <ENTER>, ended by <CTRL-D>:
    howdy
    doody
    buffalo
    bob
    clarabell
    clown

    1234567890123456789012345678901234567890123456789012345678901234567890
                                                                  howdy
                                                                  doody
                                                                buffalo
                                                                    bob
                                                              clarabell
                                                                  clown


Chapter 6, Exercise 1

The goal of this exercise is to become familiar with hash data structures and hash operators.
In the SUBROUTINES section, 1 subroutine given_to_family_name() is defined, which accepts no input arguments and returns no values.
Inside given_to_family_name(), a hash data structure is created in the variable $names. Another term for hash is associative array, because each hash is comprised of key-value pairs, and we say there is a value "associated" with every key. Hash keys are bare words and must be unique, while hash values may be any specified data type and need not be unique. The 3 keys in $names are fred, barney, and wilma; the value of the key fred is 'flintstone'.
A first name is collected from the user by <STDIN> and stored in $given_name, then the chomp operator is called to remove the trailing newline recorded when the user presses the ENTER key.
An if conditional statement calls the exists and defined operators to ensure the user has entered a valid hash key, and an error is returned if there is no such key in the $names hash.
Finally, the thin-arrow syntax $names->{$given_name} is used to retrieve the hash value, and print is called to display the family name outputs.
In the OPERATIONS section, the only operation is a call to the given_to_family_name() subroutine.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 6, Exercise 1
    # Accept one input given (first) name, and print the corresponding family (last) name

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our void $given_to_family_name = sub {
        my string_hashref $names = {
            fred => 'flintstone',
            barney => 'rubble',
            wilma => 'flintstone'
        };

        print 'Please input a given (first) name in all lowercase, then press <ENTER>:', "\n";
        my string $given_name = <STDIN>;
        chomp $given_name;

        if ((not exists $names->{$given_name}) or (not defined $names->{$given_name})) {
            croak 'ERROR: No family (last) name found for given (first) name ', $given_name, ', croaking', "\n";
        }

        print 'The family (last) name of ', $given_name, ' is ', $names->{$given_name}, q{.}, "\n";
    };

    # [[[ OPERATIONS ]]]

    given_to_family_name();

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter6/exercise_1-hash_family_names.pl 
    Please input a given (first) name in all lowercase, then press <ENTER>:
    fred
    The family (last) name of fred is flintstone.

    $ rperl -t LearningRPerl/Chapter6/exercise_1-hash_family_names.pl 
    Please input a given (first) name in all lowercase, then press <ENTER>:
    howdy
    ERROR: No family (last) name found for given (first) name howdy, croaking


Chapter 6, Exercise 2

The goal of this exercise is to become further familiarized with hash data structures and hash operators.
In the SUBROUTINES section, 1 subroutine unique_word_count() is defined, which accepts no input arguments and returns no values.
In unique_word_count(), an empty hash of integer values is created in the variable $word_counts; a while loop then collects user input strings, inside of which an if() else conditional statement updates the $word_counts hash. If a word is seen for the first time, then the corresponding $word_counts hash value will be set to 1, otherwise the count value will be incremented by 1.
Finally, a foreach loop iterates through the alphabetically-sorted keys of the $word_counts hash by calling the sort and keys operators, then the thin-arrow hash value retrieval syntax $word_counts->{$unique_word} is called, and the print operator displays the word count outputs.
In the OPERATIONS section, the only operation is a call to the unique_word_count() subroutine.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 6, Exercise 2
    # Accept a list of words, and print the count of each unique word

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt

    # [[[ SUBROUTINES ]]]

    our void $unique_word_count = sub {
        my integer_hashref $word_counts = {};

        print 'Please input zero or more words, separated by <ENTER>, ended by <CTRL-D>:', "\n";
        while (my string $input_word = <STDIN>) {
            chomp $input_word;
            if (not exists $word_counts->{$input_word}) {
                $word_counts->{$input_word} = 1;
            }
            else {
                $word_counts->{$input_word} += 1;
            }
        }

        print "\n", 'Unique word count:', "\n";

        foreach my string $unique_word (sort keys %{$word_counts}) {
            print $unique_word, ' appeared ', to_string($word_counts->{$unique_word}), ' time(s)', "\n";
        }
    };

    # [[[ OPERATIONS ]]]

    unique_word_count();

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter6/exercise_2-hash_unique_word_count.pl 
    Please input zero or more words, separated by <ENTER>, ended by <CTRL-D>:
    george
    jane
    judy
    elroy
    astro
    rosie
    george
    judy
    astro
    fred
    wilma
    barney
    betty
    pebbles
    bamm-bamm
    dino
    fred
    barney
    dino
    george
    fred
    barney
    astro
    dino
    jane
    judy
    betty
    wilma

    Unique word count:
    astro appeared 3 time(s)
    bamm-bamm appeared 1 time(s)
    barney appeared 3 time(s)
    betty appeared 2 time(s)
    dino appeared 3 time(s)
    elroy appeared 1 time(s)
    fred appeared 3 time(s)
    george appeared 3 time(s)
    jane appeared 2 time(s)
    judy appeared 3 time(s)
    pebbles appeared 1 time(s)
    rosie appeared 1 time(s)
    wilma appeared 2 time(s)


Chapter 6, Exercise 3

The goal of this exercise is to become further familiarized with hash data structures and basic text formatting.
In the SUBROUTINES section, 1 subroutine sort_env_vars() is defined, which accepts no input arguments and returns no values.
Inside sort_env_vars(), a hash of strings is created in the variable $env_vars, and it is initialized to contain the values of the special %ENV system hash, which stores the current user's environmental variables.
Next, 2 integer variables $env_var_length and $left_column_width are created, and $left_column_width is initialized to the value 0. A foreach loop iterates through all environmental variables, measuring the string length of each $env_var by the length operator, and using an if conditional statement to test if the current $env_var_length is greater than the existing $left_column_width. If $env_var_length is large enough, then $left_column_width is updated, thereby resulting in the value of $left_column_width being equal to the longest $env_var_length.
After the foreach loop, $left_column_width is incremented by an additional 2 character widths, allowing for 2 or more spaces between the hash keys and their respective values when displayed.
Finally, there is another foreach loop below the first, again iterating through all $env_vars, and printing the keys at the beginning of each output line. The - subtraction operator is called to find the difference between the current key length and the pre-calculated $left_column_width, then the x string repeat operator is called to create the corresponding number of blank spaces as padding between the key and its value. The thin-arrow hash value retrieval syntax $env_vars->{$env_var} is called, and the print operator displays the hash value outputs.
In the OPERATIONS section, the only operation is a call to the sort_env_vars() subroutine.

    #!/usr/bin/perl

    # Learning RPerl, Chapter 6, Exercise 3
    # Print sorted environmental variables

    # [[[ HEADER ]]]
    use RPerl;
    use strict;
    use warnings;
    our $VERSION = 0.001_000;

    # [[[ CRITICS ]]]
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator

    # [[[ SUBROUTINES ]]]

    our void $sort_env_vars = sub {
        my string_hashref $env_vars = {%ENV};

        my integer $env_var_length;
        my integer $left_column_width = 0;
        foreach my string $env_var ( sort keys %{$env_vars} ) {
            $env_var_length = length $env_var;
            if ( $env_var_length > $left_column_width ) {
                $left_column_width = $env_var_length;
            }
        }

        $left_column_width += 2;

        print 'Environmental variables:', "\n";

        foreach my string $env_var ( sort keys %{$env_vars} ) {
            print $env_var;
            print q{ } x ( $left_column_width - ( length $env_var ) );
            print $env_vars->{$env_var}, "\n";
        }
    };

    # [[[ OPERATIONS ]]]

    sort_env_vars();

Example execution, input, and output:

    $ rperl -t LearningRPerl/Chapter6/exercise_3-hash_sort_env_vars.pl 
    Environmental variables:
    COLORTERM                 xfce4-terminal
    DESKTOP_SESSION           xubuntu
    DISPLAY                   :0.0
    GDMSESSION                xubuntu
    GDM_LANG                  en_US
    HOME                      /home/jlpicard
    LANG                      en_US.UTF-8
    LANGUAGE                  en_US
    LOGNAME                   jlpicard
    PATH                      .:script:bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games
    PERL5LIB                  blib/lib:lib:/home/jlpicard/perl5/lib/perl5
    PERL_LOCAL_LIB_ROOT       /home/jlpicard/perl5
    PERL_MB_OPT               --install_base "/home/jlpicard/perl5"
    PERL_MM_OPT               INSTALL_BASE=/home/jlpicard/perl5
    PWD                       /home/jlpicard
    SHELL                     /bin/bash
    TERM                      xterm
    USER                      jlpicard


APPENDIX B: RPERL COMMAND-LINE ARGUMENTS

The `rperl` "command-line interface" (CLI) is a software program which serves as the primary front-end user interface for RPerl. When called for execution, the `rperl` command must be provided with at least one input file name, which tells RPerl which file(s) to compile. In addition, `rperl` may also be provided with one or more optional "command-line arguments", which tell RPerl how to behave and exactly how to compile the input file(s). Command-line arguments are also commonly referred to as "options", or in this specific context just "arguments".

Command-line arguments which are listed as one of the "modes" will modify the way RPerl compiles the input source code file(s). All RPerl modes are written using the longhand format:

--mode foo=BAR

Arguments which are listed as one of the "flags" are written using the shorthand --foo or even shorter -f formats. Most flags are shortcuts to common modes.

Flags and other non-mode arguments which are not shortcuts to common modes will either modify some non-compiling behavior of RPerl (such as enabling additional information output), or cause RPerl to do something other than fully execute and compile input source code files (such as displaying version information then exiting).

Below is a comprehensive list of all RPerl command-line arguments, as reported by the `rperl -?` command.

Additional explanations for each argument are provided with emphasis.

B.1: Help

--help ...OR... -h ...OR... -?
    Print this (relatively) brief help message for command-line usage.
    For additional explanations, run the command `perldoc RPerl::Learning` and see Appendix B.

The help option simply displays the content of this appendix, except for the additional explanations such as this one.

Yes, this is the "Appendix B" you're looking for.

B.2: Version

--version ...OR... -v
--vversion ...OR... -vv
    Print version number and copyright information.
    Repeat as 'vv' for more technical information, similar to `perl -V` configuration summary argument.
    Lowercase 'v' not to be confused with uppercase 'V' in 'Verbose' argument.

The single-v version option displays a brief message similar to the output of the `perl -v` command.

The double-v version option displays a collection of technical information similar to the output of the `perl -V` command, including subcompile flags for the C++ compiler and system paths. This option may be useful to RPerl system develpers when debugging subcompile issues or other problems.

B.3: Input Files

--infile=MyFile.pm ...OR... -i=MyFile.pm
    Specify input file, may be repeated for multiple input files.
    Argument prefix '--infile' may be entirely omitted.
    Argument prefix MUST be omitted to specify wildcard for multiple input files.

The input file option tells RPerl which file(s) to compile, and is the only command-line argument which is always required every time the `rperl` command is fully executed (not just `rperl -?`, `rperl -v`, etc). Even if the argument prefix '--infile' is omitted for convenience, one or more input file names must still be specified to avoid an RPerl error message.

All input files must end in '.pl' for RPerl programs, or '.pm' for RPerl modules.

B.4: Output Files

--outfile=MyCompiledModule ...OR... -o=MyCompiledModule
--outfile=my_compiled_program ...OR... -o=my_compiled_program
    Specify output file prefix, may be repeated for multiple output files.
    RPerl *.pm input file with PERL ops will create MyCompiledModule.pmc output file.
    RPerl *.pl input file with PERL ops will create my_compiled_program (or my_compiled_program.exe on Windows) output file.
    RPerl *.pm input file with CPP  ops will create MyCompiledModule.pmc, MyCompiledModule.cpp, & MyCompiledModule.h output files.
    RPerl *.pl input file with CPP  ops will create my_compiled_program (or my_compiled_program.exe on Windows) & my_compiled_program.cpp output files.
    Argument may be entirely omitted, foo.* input file will default to foo.* output file(s).

The output file option tells RPerl which file(s) to generate by specifying a file prefix. RPerl automatically determines the output file suffixes, depending upon the operations (AKA "ops") mode of either PERL or CPP. The PERL ops mode is a test mode, so only Perl output files are generated; the CPP ops mode is a real compile mode, so C++ output files are generated.

If the output file option is omitted, then the original prefix of each input file is used as the prefix of the output file, as one would expect. For example, without an output file option provided, an input file named 'foo.pl' in CPP ops mode will generate the 'foo.cpp' and 'foo' (or 'foo.exe' in Windows) output files. With an output file option of -o=bar provided, the same 'foo.pl' input file will instead generate the 'bar.cpp' and 'bar' (or 'bar.exe') output files.

B.5: C++ Compiler

--CXX=/path/to/compiler
    Specify path to C++ compiler for use in subcompile modes, equivalent to '--mode CXX=/path/to/compiler' or 'CXX' manual Makefile argument, 'g++' by default.

The C++ compiler option tells RPerl which subcompiler to use for converting C++ source code into binary machine code.

This option is a shorthand provided for brevity, please see: "B.15: Modes, C++ Compiler"

If both the shorthand and longhand forms of the C++ compiler option are omitted, then RPerl will utilize the GNU C++ compiler or give an error if it is not installed.

B.6: Modes, Operations

--mode ops=PERL ...OR... -m ops=PERL
--mode ops=CPP ...OR... -m ops=CPP
    Specify operations mode, CPP by default.
    If set to PERL, generate Perl operations in the source code output file(s).
    If set to CPP, generate C++ operations in the source code output file(s).
    PERL ops mode forces PERL types mode & PARSE or GENERATE compile mode; PERLOPS_PERLTYPES is test mode, does not actually compile.

The two most important RPerl modes are "operations" (AKA "ops") and "data types" (AKA "types").

The ops mode option tells RPerl if it should use Perl operations or C++ operations in the final output. Perl operations are slow, but provide support for high-magic functionality. C++ operations are fast, but only support low-magic functionality.

Normal Perl is considered an interpreted language and uses Perl operations. When an RPerl application is run in Perl operations mode, then the application is interpreted instead of compiled. When an RPerl application runs in C++ operations mode, then it is compiled.

B.7: Modes, Types

--mode types=PERL ...OR... -m types=PERL
--mode types=CPP ...OR... -m types=CPP
--mode types=DUAL ...OR... -m types=DUAL
    Specify data types mode, CPP by default.
    If set to PERL, generate Perl data types in the source code output file(s).
    If set to CPP, generate C++ data types in the source code output file(s).
    If set to DUAL, generate both Perl and C++ data types in the source code output file(s).
    DUAL mode allows generate-once-compile-many types, selected by '#define __FOO__TYPES' in lib/rperltypes_mode.h or `gcc -D__FOO__TYPES` manual subcompile argument.

The types mode option tells RPerl if it should use Perl data types or C++ data types in the final output. Just like RPerl's ops mode, Perl data types are slow and high-magic, while C++ types are fast and low-magic.

Normal interpreted Perl uses Perl types (and Perl ops). When an RPerl application is run in Perl types mode, then the application is compiled but only partial speed optimization is achieved. When an RPerl application runs in C++ types mode, then it is compiled with full speed optimization.

Because RPerl's first goal is performance, support for C++-ops-Perl-types mode and C++-ops-dual-types mode is limited to hand-compiled RPerl applications only, with full support planned for a future version release. Meanwhile, the high-performance C++-ops-C++-types mode is currently supported for compiled RPerl applications, and the slow Perl-ops-Perl-types mode (AKA "test mode") is supported for testing purposes.

B.8: Modes, Integer Type

--mode type_integer=LONG ...OR... -m type_integer=LONG
--mode type_integer=LONG__LONG ...OR... -m type_integer=LONG__LONG
    Specify native C++ integer data type, same as internal Perl type by default.
    If set to LONG, utilize 'long' as native type for 'integer', at least 32 bits;
    If set to LONG__LONG, utilize 'long long' as native type for 'integer', at least 64 bits.

The type_integer mode option tells RPerl which native C++ data type to use as the RPerl 'integer' data type when compiled in CPPOPS_CPPTYPES mode.

According to the C language standard, 'long' will provide at least 32 bits of storage, and 'long long' will provide at least 64 bits.

By default, RPerl will set this mode option to match the internal C data type used by the Perl interpreter itself, in order to produce the same output in both PERLTYPES and CPPTYPES modes.

B.9: Modes, Number Type

--mode type_number=DOUBLE ...OR... -m type_number=DOUBLE
--mode type_number=LONG__DOUBLE ...OR... -m type_number=LONG__DOUBLE
    Specify native C++ number data type, same as internal Perl type by default.
    If set to DOUBLE, utilize 'double' as native type for 'number', usually at least 32 bits, but not guaranteed;
    If set to LONG__DOUBLE, utilize 'long double' as native type for 'number', usually at least 64 bits, but not guaranteed.

The type_number mode option tells RPerl which native C++ data type to use as the RPerl 'number' data type when compiled in CPPOPS_CPPTYPES mode.

According to the C language standard, there is no guaranteed bit length for these data types, although 'long double' will not provide less storage than 'double'.

On some systems, 'double' is 32 bits and 'long double' is 64 bits, while on other systems 'double' is 64 bits and 'long double' is 128 bits. Every system is different, and other bit lengths may also be encountered.

By default, RPerl will set this mode option to match the internal C data type used by the Perl interpreter itself, in order to produce the same output in both PERLTYPES and CPPTYPES modes.

B.10: Modes, Type Checking

--mode check=OFF ...OR... -m check=OFF
--mode check=ON ...OR... -m check=ON
--mode check=TRACE ...OR... -m check=TRACE
    Specify data type checking mode, TRACE by default.
    If set to OFF, do not perform dynamic type checking, only built-in C++ static type checking.
    If set to ON, perform dynamic type checking in addition to built-in C++ static type checking.
    If set to TRACE, perform dynamic type checking in addition to built-in C++ static type checking, with subroutine-and-variable trace information.

The data type checking mode option tells RPerl if it should perform additional tests to ensure correct data types are used as "subroutine arguments" (not to be confused with "command-line arguments"). RPerl subroutines can accept 1 or more arguments (AKA "parameters"), each of which must be of a specific data type.

In C++-ops-C++-types mode, all data types must be determined at compile time and thus can not change (AKA "static"), so the C++ compiler performs all necessary type checking. In any Perl types mode, the data types can not be determined until runtime and thus can change (AKA "dynamic"), so RPerl must itself perform type checking for subroutine arguments.

If the type checking mode is set to TRACE, then the name of the problematic subroutine and argument will be "traced" and provided in the RPerl error message. This setting can be useful for RPerl application developers and debugging purposes.

B.11: Modes, Dependencies

--mode dependencies=OFF ...OR... -m dependencies=OFF
--mode dependencies=ON ...OR... -m dependencies=ON
    Specify dependencies mode, ON by default.
    If set to OFF, do not search for or compile dependencies.
    If set to ON, recursively search for dependencies and subdependencies, include as additional input file(s).
    WARNING: Disabling dependencies will likely cause errors or undefined behavior.

The dependencies mode option tells RPerl if it should compile all the Perl application code which is used by the input RPerl application code via the use operator. If 1 RPerl application input file is provided which has 10 dependencies, and each of those 10 dependencies has 10 sub-dependencies of its own, then the RPerl compiler actually has at least 111 input files to compile, and possibly many more than 111 if any of the sub-dependencies has sub-sub-dependencies, etc.

If your RPerl application depends upon other RPerl code, then all should go as planned. If your RPerl application depends upon other non-RPerl code, then you will likely encounter problems as RPerl attempts to compile the non-RPerl components.

If the dependencies mode option is set to OFF, then you will likely encounter problems as the compiled RPerl application attempts to locate the compiled form of each dependency, which will not be found unless manually compiled or copied from a previous compile. Thus, disabling compilation of dependencies is strongly discouraged, because RPerl will not function properly if any dependency (or sub-dependency, etc) is not compiled.

B.12: Modes, Uncompile

--mode uncompile=OFF ...OR... -m uncompile=OFF
--mode uncompile=SOURCE ...OR... -m uncompile=SOURCE
--mode uncompile=BINARY ...OR... -m uncompile=BINARY
--mode uncompile=INLINE ...OR... -m uncompile=INLINE
--mode uncompile=SOURCE_BINARY ...OR... -m uncompile=SOURCE_BINARY
--mode uncompile=SOURCE_BINARY_INLINE ...OR... -m uncompile=SOURCE_BINARY_INLINE
    Specify uncompile mode, OFF by default.
    If set to SOURCE, delete all generated C++ output source code (not subcompiled) files: *.cpp, *.h, *.pmc
    If set to BINARY, delete all generated C++ output binary (subcompiled) files: *.o, *.a, *.so, *.exe, non-suffixed executables
    If set to INLINE, delete all generated C++ output Inline::CPP files: _Inline/ directory
    If set to SOURCE_BINARY, delete both SOURCE and BINARY files.
    If set to SOURCE_BINARY_INLINE, delete SOURCE, BINARY, and INLINE files.
    For *.pm Perl module input files, BINARY and INLINE are equivalent.

The uncompile mode option tells RPerl if it should do the opposite of compiling, which is to delete any compiled files created by previous executions of RPerl.

Many different files may be created each time RPerl is executed, which are separated into 3 different groups: human-readable RPerl source code files (AKA "SOURCE"), machine-readable RPerl binary files (AKA "BINARY"), and a mixture of both source and binary files created by the Inline software in the "_Inline" directory (AKA "INLINE"). It is recommended to delete all 3 groups using the "SOURCE_BINARY_INLINE" setting, to avoid possible problems with mismatching or partially-compiled components.

RPerl will attempt to overwrite any files generated by previous RPerl executions, so it is generally unnecessary to explicitly use the uncompile option when executing RPerl multiple times with the same input file(s) each time.

B.13: Modes, Compile

--mode compile=OFF ...OR... -m compile=OFF
--mode compile=PARSE ...OR... -m compile=PARSE
--mode compile=GENERATE ...OR... -m compile=GENERATE
--mode compile=SAVE ...OR... -m compile=SAVE
--mode compile=SUBCOMPILE ...OR... -m compile=SUBCOMPILE
    Specify compile mode, SUBCOMPILE by default.
    If set to PARSE, begin with RPerl input source code file(s), and end with RPerl abstract syntax tree output data structure.
    If set to GENERATE, begin with RPerl input source code file(s), and end with RPerl and/or C++ output source code in memory.
    If set to SAVE, begin with RPerl input source code file(s), and end with RPerl and/or C++ output source code file(s) saved to disk.
    If set to SUBCOMPILE, begin with RPerl input source code file(s), and end with C++ output binary file(s).

The compile mode option tells RPerl how far to progress through the compile phase categories of "PARSE", "GENERATE", "SAVE", and "SUBCOMPILE". As detailed in Section 2.3, there are multiple distinct phases for both parsing and saving, while generating and subcompiling are only one phase each. The compile mode option groups all 3 parsing phases together as PARSE, and both saving phases as SAVE.

The OFF, PARSE, and GENERATE phase categories may be useful for RPerl system developers while debugging the RPerl compiler itself. No output files are saved to disk for these 3 phase categories, so they are not particularly useful for RPerl application developers.

Both the SAVE and SUBCOMPILE phase categories save output files to disk, so they may be useful to RPerl application developers. The SAVE phase category does not call the C++ compiler to perform subcompiling, which can be done manually by the developer if they so choose.

B.14: Modes, Subcompile

--mode subcompile=OFF ...OR... -m subcompile=OFF
--mode subcompile=ASSEMBLE ...OR... -m subcompile=ASSEMBLE
--mode subcompile=ARCHIVE ...OR... -m subcompile=ARCHIVE
--mode subcompile=SHARED ...OR... -m subcompile=SHARED
--mode subcompile=STATIC ...OR... -m subcompile=STATIC
--mode subcompile=DYNAMIC ...OR... -m subcompile=DYNAMIC
    Specify subcompile mode, DYNAMIC by default.
    If set to ASSEMBLE, generate *.o object binary output file(s).
    If set to ARCHIVE, generate *.a object archive binary output file(s).
    If set to SHARED, generate *.so shared object binary output file(s).
    If set to STATIC, generate statically-linked *.exe or non-suffixed executable binary output file(s).
    If set to DYNAMIC, generate dynamically-linked *.exe or non-suffixed executable binary output file(s).

The subcompile mode option tells RPerl what output is desired from the C++ compiler. This option is recommended for use by RPerl developers with prior C++ compiler experience.

The "ASSEMBLE", "ARCHIVE", and "SHARED" subcompile modes will generate non-executable binary files from both *.pl RPerl program input files and *.pm RPerl module input files. The generated binary files are reusable components; experienced RPerl and C++ developers may utilize the C++ compiler to "link" (combine) together multiple source and binary files in order to create a final binary output file.

The "STATIC" subcompile mode is invalid for *.pm RPerl module input files; for *.pl RPerl programs, STATIC mode creates a binary executable which contains all necessary components included within 1 file.

For *.pm input files, the "DYNAMIC" subcompile mode will use Inline and PMC file(s) to automatically interface between the compiled RPerl output and any non-compiled Perl code which calls the compiled output. For *.pl input files, DYNAMIC mode creates a binary executable which does not contain all necessary components, and thus must search for external library files such as "libperl.a" or "libperl.so" during every execution.

The C++ compiler and linker can be a bit complicated and confusing, one possible place to start learning more is the GCC compiler documentation:

https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html

B.15: Modes, C++ Compiler

--mode CXX=/path/to/compiler ...OR... -m CXX=/path/to/compiler
    Specify path to C++ compiler for use in subcompile modes, equivalent to '--CXX=/path/to/compiler' or 'CXX' manual Makefile argument, 'g++' by default.

The C++ compiler mode option tells RPerl which C++ compiler to utilize throughout the various phases of compilation. RPerl needs a C++ compiler to function in general, and a good C++ compiler is especially important during the subcompile phases.

Use of the GNU C++ compiler `g++` is strongly recommended, although in theory you should be able to use any C++ compiler which supports the C++11 standard.

https://en.wikipedia.org/wiki/C++11

B.16: Modes, Parallelize

--mode parallel=OFF ...OR... -m parallel=OFF
--mode parallel=OPENMP ...OR... -m parallel=OPENMP
--mode parallel=MPI ...OR... -m parallel=MPI ((( COMING SOON!!! )))
--mode parallel=OPENCL ...OR... -m parallel=OPENCL ((( COMING SOON!!! )))
    Specify automatic parallelization mode, OPENMP by default.
    If set to OFF, do not automatically parallelize any input files.
    If set to OPENMP, automatically parallelize all eligible input files for use on shared-memory OpenMP systems.
    If set to MPI (COMING SOON), automatically parallelize all eligible input files for use on distributed-memory MPI systems.
    If set to OPENCL (COMING SOON), automatically parallelize all eligible input files for use on heterogeneous or GPU systems.

The parallel mode option tells RPerl if it should automatically parallelize the RPerl input file(s) for faster runtime execution performance on parallel computing hardware platforms.

The "OPENMP" parallel mode utilizes the OpenMP software to provide support for shared memory computing hardware platforms, such as multi-core CPUs and supercomputers.

COMING SOON: The "MPI" parallel mode utilizes the MPI software to provide support for distributed memory computing hardware platforms, such as clusters and the cloud.

COMING SOON: The "OPENCL" parallel mode utilizes the OpenCL software to provide support for heterogeneous computing hardware platforms, such as CPU/GPU combinations, GPUs, and FPGAs.

B.17: Modes, Parallelize, Number Of Cores

--mode num_cores=2 ...OR... -m num_cores=2 ...OR... --num_cores=2 ...OR... -num=2
--mode num_cores=4 ...OR... -m num_cores=4 ...OR... --num_cores=4 ...OR... -num=4
--mode num_cores=8 ...OR... -m num_cores=8 ...OR... --num_cores=8 ...OR... -num=8
...ETC...
    Specify number of CPU cores to utilize for OPENMP automatic parallelization mode, 4 by default.

The num_cores mode option tells RPerl how many CPU cores to use during runtime execution of an auto-parallelized RPerl input file.

This option is only applicable when the parallel mode option is set to "OPENMP", for use on shared memory computing hardware platforms.

It may be best to choose a value which is a power of 2, although this is not required.

B.18: Modes, Execute

--mode execute=OFF ...OR... -m execute=OFF
--mode execute=ON ...OR... -m execute=ON
    Specify execute mode, ON by default.
    If set to OFF, do not load or run any user-supplied program(s).
    If set to ON with one *.pl Perl program input file, load and run the program.
    If set to ON with more than one *.pl Perl program input file, do not load or run any programs.

The execute mode option tells RPerl if it should actually run a *.pl RPerl program input file, or just compile it without running.

The default behavior for *.pl program files is to compile-then-execute, in order to provide a similar feel to normal Perl's interpret-while-executing behavior.

When *.pm RPerl module input file(s) are provided, then no execution occurs because module files are not executable.

B.19: Modes, Source Code Labels

--mode label=OFF ...OR... -m label=OFF
--mode label=ON ...OR... -m label=ON
    Specify source section label mode, ON by default.
    If set to OFF, generate minimal output source code, may save disk space.
    If set to ON, generate some informative labels in output source code, may be more human-readable.

The source code label mode option tells RPerl if it should create human-readable labels embedded as comments in the C++ output source code. This option may be useful to RPerl system developers when comparing an RPerl application's original uncompiled source code input with the compiled C++ source code output.

B.20: Flags, Verbose

--Verbose ...OR... -V
--noVerbose ...OR... -noV
    Include additional user information in output, or not.
    If enabled, equivalent to `export RPERL_VERBOSE=1` shell command.
    Disabled by default.
    Uppercase 'V' not to be confused with lowercase 'v' in 'version' argument.

The verbose flag option tells RPerl to display additional user-friendly information during various phases of compilation.

Verbose output is generated using the RPerl::verbose() RPerl system subroutine.

If the verbose and debug flags are not enabled, then a problem-free RPerl compilation will produce no output whatsoever, in order to preserve the "*nix" tradition of displaying no unnecessary output during successful execution of system software.

https://en.wikipedia.org/wiki/*nix

B.21: Flags, Debug

--Debug ...OR... -D
--noDebug ...OR... -noD
    Include debugging & system diagnostic information in output, or not.
    If enabled, equivalent to `export RPERL_DEBUG=1` shell command.
    Disabled by default.
    Uppercase 'D' not to be confused with lowercase 'd' in 'dependencies' argument.

The debug flag option tells RPerl to display additional developer-friendly information during various phases of compilation.

Debugging output is generated using the identical RPerl::debug() & RPerl::diag() RPerl system subroutines.

Use of both the verbose and debug flags `rperl -V -D` is recommended for RPerl system developers.

B.22: Flags, Warnings

--Warnings ...OR... -W
--noWarnings ...OR... -noW
    Include system warnings in output, or not.
    If disabled, equivalent to `export RPERL_WARNINGS=0` shell command.
    Enabled by default.

The warnings flag option tells RPerl if it should display non-fatal warnings.

The default behavior is that RPerl should display warnings, in order to encourage users and developers alike to address problems before they become fatal errors, or cause other unexpected or undefined behavior.

B.23: Flags, Test

--test ...OR... -t
    Test mode: Perl ops, Perl types, Parse & Generate (no Save or Compile)
    If enabled, equivalent to '--mode ops=PERL --mode types=PERL --mode compile=GENERATE' arguments.
    Disabled by default.

The test flag option tells RPerl to operate in test mode, which means RPerl will utilize Perl operations and Perl data types, and the resulting output code will not actually be saved to disk or subcompiled. Because the Perl-ops-Perl-types mode is the fully-implemented reference design for the RPerl language, the test mode may be useful to RPerl application developers in order to check the correctness of an RPerl application which includes some RPerl feature that is not yet implemented in the optimized C++ modes.

B.24: Flags, Dependencies

--dependencies ...OR... -d
--nodependencies ...OR... -nod
    Follow and compile dependencies, or not.
    Enabled by default, equivalent to '--mode dependencies=ON' argument.
    Lowercase 'd' not to be confused with uppercase 'D' in 'Debug' argument.

The dependencies flag option tells RPerl if it should recursively follow and compile all dependencies of all RPerl source code input files.

This option is a shorthand provided for brevity, please see: "B.11: Modes, Dependencies"

B.25: Flags, Uncompile

--uncompile ...OR... -u
--nouncompile ...OR... -nou
--uuncompile ...OR... -uu
--nouuncompile ...OR... -nouu
--uuuncompile ...OR... -uuu
--nouuncompile ...OR... -nouuu
    Uncompile (delete C++ source code and/or binary output files), or not.
    Repeat as 'uu' and 'uuu' for more thorough file removal.
    Do not confuse uncompile with decompile (recreate RPerl source code from C++ source code or binary output files), which does not currently exist.
    '-u' equivalent to '--mode uncompile=SOURCE --mode compile=OFF --mode execute=OFF' arguments.
    '-uu' equivalent to '--mode uncompile=SOURCE_BINARY --mode compile=OFF --mode execute=OFF' arguments.
    '-uuu' equivalent to '--mode uncompile=SOURCE_BINARY_INLINE --mode compile=OFF --mode execute=OFF' arguments.
    Disabled by default.

The uncompile flag option tells RPerl to uncompile the input file(s) instead of compiling them. The "u" of "uncompile" may be repeated as "uu" or "uuu" for greater uncompile effect (more files deleted).

This option is a shorthand provided for brevity, please see: "B.12: Modes, Uncompile"

B.26: Flags, Compile

--compile ...OR... -c
--nocompile ...OR... -noc
    Generate & subcompile C++ source code, or not.
    Enabled by default, equivalent to '--mode compile=SUBCOMPILE' argument.

The compile flag option tells RPerl if it should compile the source code input file(s), which is obviously enabled by default because RPerl is a compiler and thus is designed to compile as its primary purpose.

If disabled via --nocompile or -noc, RPerl will still perform the PARSE and GENERATE compile phases, but will not perform the SAVE or SUBCOMPILE phases, so no output files are saved to disk or subcompiled to binary using the C++ compiler. This compile phase effect is similar to test mode in that files are not saved or subcompiled, but without automatically setting the operations or data types modes to Perl.

This option is a shorthand provided for brevity, please see: "B.13: Modes, Compile"

B.27: Flags, Subcompile, Assemble

--assemble
    Assemble subcompile mode, output *.o object file(s).
    If enabled, equivalent to '--mode subcompile=ASSEMBLE' argument or `gcc -c` manual subcompile argument.
    Disabled by default.

The assemble flag tells RPerl to run the C++ assembler and save non-executable binary *.o object file(s) to disk.

This option is a shorthand provided for brevity, please see: "B.14: Modes, Subcompile"

B.28: Flags, Subcompile, Archive

--archive
    Archive subcompile mode, output *.a object archive file(s).
    If enabled, equivalent to '--mode subcompile=ARCHIVE' argument or `gcc -c` followed by `ar` manual subcompile command.
    Disabled by default.

The archive flag tells RPerl to run the C++ compiler and save non-executable binary *.a archive library file(s) to disk.

This option is a shorthand provided for brevity, please see: "B.14: Modes, Subcompile"

B.29: Flags, Subcompile, Shared Object

--shared
    Shared subcompile mode, output *.so shared object file(s).
    If enabled, equivalent to '--mode subcompile=SHARED' argument or `gcc -shared` manual subcompile command.
    Disabled by default.

The archive flag tells RPerl to run the C++ compiler and save non-executable binary *.so shared object library file(s) to disk.

This option is a shorthand provided for brevity, please see: "B.14: Modes, Subcompile"

B.30: Flags, Subcompile, Static

--static
--nostatic
    Static subcompile mode, output *.exe or non-suffixed statically-linked executable file(s).
    If disabled, equivalent to '--mode subcompile=DYNAMIC' argument or `gcc` manual subcompile command.
    If enabled, equivalent to '--mode subcompile=STATIC' argument or `gcc -static` manual subcompile command.
    Disabled by default.

The static flag tells RPerl to run the C++ compiler and save executable binary *.exe or non-suffixed statically-linked program file(s) to disk.

There is no equivalent --dynamic flag, because dynamic subcompile mode is already the default behavior.

This option is a shorthand provided for brevity, please see: "B.14: Modes, Subcompile"

B.31: Flags, Parallelize

--parallel ...OR... -p
--noparallel ...OR... -nop
    Automatically parallelize input code, or not.
    Enabled by default.
    Equivalent to '--mode parallel=OPENMP' argument.

The parallel flag tells RPerl if it should auto-parallelize the RPerl input file(s).

This option is a shorthand provided for brevity, please see: "B.16: Modes, Parallelize"

B.32: Flags, Execute

--execute ...OR... -e
--noexecute ...OR... -noe
    Run input code after argumental compile, or not.
    Enabled by default for *.pl program input files, always disabled for *.pm module input files or multiple input files.
    Equivalent to '--mode execute=ON' argument.

The execute flag tells RPerl if it should execute a *.pl RPerl program input file.

This option is a shorthand provided for brevity, please see: "B.18: Modes, Execute"


APPENDIX C: RPERL CRITICS

    # DEV NOTE: disable RequireTidyCode because Perl::Tidy is not perfect and may complain even if the code is tidy;
    
    # disable PodSpelling because calling the external spellchecker can cause errors such as aspell's "No word lists can be found for the language FOO";
    
    # disable RequireExplicitPackage because 'use RPerl;' comes before package name(s), and Grammar.eyp will catch any other violations
    
    '-exclude'  => ['RequireTidyCode', 'PodSpelling', 'RequireExplicitPackage'],
    
    
    # [[[ CRITICS ]]]
    
    ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls)  # USER DEFAULT 1: allow numeric values & print operator
    
    ## no critic qw(RequireInterpolationOfMetachars)  # USER DEFAULT 2: allow single-quoted control characters & sigils
    
    ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers)  # USER DEFAULT 3: allow constants
    
    ## no critic qw(ProhibitExplicitStdin)  # USER DEFAULT 4: allow <STDIN> prompt
    
    ## no critic qw(RequireBriefOpen)  # USER DEFAULT 5: allow open() in perltidy-expanded code
    
    ## no critic qw(ProhibitCStyleForLoops)  # USER DEFAULT 6: allow C-style for() loop headers
    
    ## no critic qw(RequireTrailingCommas)  # USER DEFAULT X: no trailing commas in RPerl lists  # NEED ANSWER: RPerl is mostly array refs, do we even need this?
    
    
    ## no critic qw(ProhibitUselessNoCritic PodSpelling)  # DEVELOPER DEFAULT 1a: allow unreachable & POD-commented code, must be on line 1
    
    ## no critic qw(ProhibitUnreachableCode RequirePodSections RequirePodAtEnd)  # DEVELOPER DEFAULT 1b: allow POD & unreachable or POD-commented code, must be after line 1
    
    ## no critic qw(ProhibitStringySplit ProhibitInterpolationOfLiterals)  # DEVELOPER DEFAULT 2: allow string test values
    
    
    ## no critic qw(ProhibitStringyEval)  # SYSTEM DEFAULT 1: allow eval()
    
    ## no critic qw(ProhibitCascadingIfElse)  # SYSTEM DEFAULT 2: allow argument-handling logic
    
    ## no critic qw(Capitalization ProhibitMultiplePackages ProhibitReusedNames)  # SYSTEM DEFAULT 3: allow multiple & lower case package names
    
    ## no critic qw(RequireCheckingReturnValueOfEval)  # SYSTEM DEFAULT 4: allow eval() test code blocks
    
    
    ## no critic qw(ProhibitBooleanGrep)  # SYSTEM SPECIAL 1: allow grep
    
    ## no critic qw(ProhibitAutoloading RequireArgUnpacking)  # SYSTEM SPECIAL 2: allow Autoload & read-only @_
    
    ## no critic qw(ProhibitParensWithBuiltins ProhibitNoisyQuotes)  # SYSTEM SPECIAL 3: allow auto-generated code
    
    ## no critic qw(ProhibitExcessMainComplexity)  # SYSTEM SPECIAL 4: allow complex code outside subroutines, must be on line 1
    
    ## no critic qw(ProhibitExcessComplexity)  # SYSTEM SPECIAL 5: allow complex code inside subroutines, must be after line 1
    
    ## no critic qw(ProhibitPostfixControls)  # SYSTEM SPECIAL 6: PERL CRITIC FILED ISSUE #639, not postfix foreach or if
    
    ## no critic qw(ProhibitDeepNests)  # SYSTEM SPECIAL 7: allow deeply-nested code
    
    ## no critic qw(ProhibitNoStrict)  # SYSTEM SPECIAL 8: allow no strict
    
    ## no critic qw(RequireUseStrict)  # SYSTEM SPECIAL 9: allow omitted strict
    
    ## no critic qw(RequireBriefOpen)  # SYSTEM SPECIAL 10: allow complex processing with open filehandle
    
    ## no critic qw(ProhibitBacktickOperators)  # SYSTEM SPECIAL 11: allow system command execution
    
    ## no critic qw(ProhibitCascadingIfElse)  # SYSTEM SPECIAL 12: allow complex conditional logic
    
    ## no critic qw(RequireCarping)  # SYSTEM SPECIAL 13: allow die instead of croak
    
    ## no critic qw(ProhibitAutomaticExportation)  # SYSTEM SPECIAL 14: allow global exports from Config.pm
    
    
    # COMBO CRITICS
    
    ## no critic qw(ProhibitUselessNoCritic PodSpelling ProhibitExcessMainComplexity)  # DEVELOPER DEFAULT 1a: allow unreachable & POD-commented code; SYSTEM SPECIAL 4: allow complex code outside subroutines, must be on line 1

APPENDIX D: RPERL GRAMMAR

D.1: Eyapp Grammar Format & Sections

RPerl's grammar is written using the Eyapp computer programming language, which is a combination of normal Perl 5 and grammar expressions.

The grammar expression sections in Eyapp source code are written using an implementation of the Extended Backus-Naur Form (EBNF) language.

The file lib/RPerl/Grammar.eyp contains the uncompiled RPerl grammar, which is passed through the `eyapp` compiler command once to generate the output file lib/RPerl/Grammar.pm, which is then used by the `rperl` compiler command to parse RPerl input source code files.

Inside the lib/RPerl/Grammar.eyp file, there are several labeled file sections, which can be grouped into 4 major categories:

For more information, please view the following links:

D.2: Lexicon Token Types

Following is a list of all RPerl tokens in all 4 lexicon sections, along with examples of valid matching lexeme input.

The list must be in correct order for all regexes to match; earlier declarations get tried first, thus highly-specific tokens such as RPerl keywords and built-in operators appear first, while the least-specific tokens such as user-defined words appear last. This ordering can be considered "lexical matching", and is distinct from operator precedence and associativity as covered in the next section.

D.2.1: Whitespace

[[[ LEXICON TOKENS, WHITESPACE ]]]

D.2.2: Types & Reserved Words

[[[ LEXICON TOKENS, TYPES & RESERVED WORDS ]]]

D.2.3: Operators

[[[ LEXICON TOKENS, OPERATORS ]]]

D.2.4: Punctuation & User-Defined Words

[[[ LEXICON TOKENS, PUNCTUATION & USER-DEFINED WORDS ]]]

D.3: Syntax Arity, Fixity, Precedence, Associativity

Operator "arity" is a technical term which means the number of input operands accepted by a specific built-in operator, or the number of input arguments accepted by a user-defined function. An operator or function which accepts 0 input arguments is known as "nullary", 1 argument as "unary", 2 arguments as "binary", 3 arguments as "ternary", and so forth. The exit; operator may be called as nullary; the ++ increment operator is unary; the + addition operator is binary; and the substr operator may be called as ternary. Not to be confused with "a ternary operator", meaning any operator which accepts 3 operands, there is one specific operator known as "the ternary operator", which is a special kind of conditional operator accepting 3 input arguments. An operator or function which may accept more than one number of arguments is known as "variadic". Some RPerl operators are variadic, such as substr which may accept 2, 3, or 4 arguments. RPerl does not currently support variadic user-defined functions.

Operator Arity on Wikipedia

Operator "fixity" is the notation form indicating the location of an operator when placed relative to its own input operands. "Prefix" operators are located before their operands, "infix" between operands, and "postfix" after operands. Additionally, operators which must be placed both before and after their operands are said to be of "closed" fixity (AKA "closefix"), while operators capable of more than one placement location are called "mixfix". Prefix notation is also known as "Polish notation", and postfix is called "Reverse Polish" notation. The abs absolute value is a prefix operator; the + addition operator is infix; and the ++ increment operator can be called as postfix. The -( ) negative-with-parentheses operator is of closed fixity, because the parentheses component must appear both before and after the enclosed operand. Parentheses are always of closed fixity; in normal Perl, the - negative (without parentheses) is a prefix operator, but in RPerl we only allow the closed fixity -( ) negative-with-parentheses operator in order to avoid grammar ambiguity, because the same - dash (AKA hyphen) character is utilized for both the - negative and - subtraction operators. The ++ increment operator may also be called as prefix, so it may be classified as mixfix.

Prefix Notation on Wikipedia

Infix Notation on Wikipedia

Postfix Notation on Wikipedia

Operator "precedence", also known as "order-of-operations", is a methodology used to determine which operator is executed first when 2 or more operators are adjacent to one another and parentheses are not used to explicitly separate them. A numeric precedence from 1 to 24 is assigned to each operator, and the operator with the lowest precedence number is given priority to execute first. Low precedence number equals high priority. The * arithmetic multiplication operator has a precedence number of 7, and + addition has a precedence of 8, so a + b * c is equivalent to a + (b * c), not (a + b) * c.

Operator Precedence on Wikipedia

Operator "associativity" is used to further determine precedence when multiple operators of the same priority are adjacent to one another. Each operator is designated as left-associative, right-associative, or non-associative. (Wikipedia incorrectly identifies associativity as a synonym for fixity, which is different, as described above.) Normal arithmetic operators are left-associative, meaning a - b - c is equivalent to (a - b) - c, not a - (b - c). Some operators such as mathematic power (AKA exponentiation) are right-associative, meaning a ** b ** c is equivalent to a ** (b ** c). Operators which are not meant to be chained together are non-associative, such as the .. list range operator which takes scalar values as input but generates an array as output, so a .. b .. c is incorrect usage and will cause an error.

Operator Associativity on Wikipedia

In the following list of operators copied directly from Grammar.eyp, later declaration gets higher priority, so all precedence numbers appear in strictly descending order from 24 to 1. (Implementation of operator arity and fixity are a bit less straightforward, and are not easily copied-and-pasted in one succinct list directly out of Grammar.eyp.) All operator arity, fixity, precedence, and associativity are taken directly from Perl 5.

Operator Precedence & Associativity in Perl 5 Documentation [1]

[[[ SYNTAX, OPERATOR PRECEDENCE & ASSOCIATIVITY ]]]

    %left       OP24_LOGICAL_OR_XOR
    %left       OP23_LOGICAL_AND
    %right      OP22_LOGICAL_NEG
    %left       OP21_LIST_COMMA
    %left       OP20_HASH_FATARROW
    %right      OP19_LOOP_CONTROL_SCOLON
    %right      OP19_LOOP_CONTROL
    %right      OP19_VARIABLE_ASSIGN_BY
    %right      OP19_VARIABLE_ASSIGN
    %right      OP18_TERNARY
    %nonassoc   OP17_LIST_RANGE
    %left       OP16_LOGICAL_OR
    %left       OP15_LOGICAL_AND
    %left       OP14_BITWISE_OR_XOR
    %left       OP13_BITWISE_AND
    %nonassoc   OP12_COMPARE_EQ_NE
    %nonassoc   OP11_COMPARE_LT_GT
    %nonassoc   OP10_NAMED_UNARY
    %nonassoc   OP10_NAMED_UNARY_SCOLON
    %left       OP09_BITWISE_SHIFT
    %left       OP08_STRING_CAT
    %left       OP08_MATH_ADD_SUB
    %left       OP07_MATH_MULT_DIV_MOD
    %left       OP07_STRING_REPEAT
    %left       OP06_REGEX_MATCH
    %left       OP06_REGEX_PATTERN
    %right      OP05_MATH_NEG_LPAREN
    %right      OP05_LOGICAL_NEG
    %right      OP04_MATH_POW
    %nonassoc   OP03_MATH_INC_DEC
    %left       OP02_HASH_THINARROW
    %left       OP02_ARRAY_THINARROW
    %left       OP02_METHOD_THINARROW_NEW
    %left       OP02_METHOD_THINARROW
    %left       OP01_NAMED
    %left       OP01_NAMED_SCOLON
    %left       OP01_CLOSE
    %left       OP01_OPEN
    %left       OP01_QW
    %left       OP01_NAMED_VOID_SCOLON
    %left       OP01_NAMED_VOID_LPAREN
    %left       OP01_NAMED_VOID
    %left       OP01_PRINT

D.4: Syntax Production Rules

The EBNF metasyntax implemented by Eyapp is of the form:

ProductionRule: First Alternative 'foo' | Second Alternative 'bar' | ... | Last Alternative 'quux' ;

In this example, ProductionRule is a non-terminal left-hand-side (LHS) symbol, is followed by the : reduction metasymbol, and may be reduced (replaced) by any of the right-hand-side (RHS) sequences of terminal and non-terminal symbols, themselves separated by the | alternation (logical or) metasymbol. In other words, each LHS may become any of its corresponding RHS alternatives.

Terminal symbols are enclosed in single quotes as with 'foo', never appear on the LHS, and are taken as literal data with no transformations applied. Eyapp treats terminal symbols as tokens which only match one hard-coded lexeme, which is the string appearing inside the single quotes, foo in this example.

D.4.1: File Formats

[[[ SYNTAX PRODUCTION RULES, FILE FORMATS ]]]

    CompileUnit:             Program | (ModuleHeader Module)+ ;
    Program:                 SHEBANG Critic? USE_RPERL Header Critic* Include* Constant* Subroutine* Operation+ ;
    ModuleHeader:            Critic? USE_RPERL? 'package' WordScoped ';' Header ;
    Module:                  Package | Class ;
    Package:                 Critic* Include* Constant* Subroutine+ LITERAL_NUMBER ';' ;
    Header:                  'use strict;' 'use warnings;' USE_RPERL_AFTER? 'our' VERSION_NUMBER_ASSIGN;
    Critic:                  '## no critic qw(' WORD+ ')';
    Include:                 USE WordScoped ';' | USE WordScoped OP01_QW ';' ;
    Constant:                'use constant' WORD_UPPERCASE OP20_HASH_FATARROW TypeInnerConstant Literal ';' ;
    Subroutine:              'our' Type VARIABLE_SYMBOL '= sub {' SubroutineArguments? Operation* '}' ';' ;
    SubroutineArguments:     LPAREN_MY Type VARIABLE_SYMBOL (OP21_LIST_COMMA MY Type VARIABLE_SYMBOL)* ')' OP19_VARIABLE_ASSIGN '@_;' ;
    Class:                   'use parent qw(' WordScoped ')' ';' Include Critic* Include* Constant* Properties MethodOrSubroutine* LITERAL_NUMBER ';' ;
    Properties:              'our hashref $properties' OP19_VARIABLE_ASSIGN LBRACE HashEntryProperties (OP21_LIST_COMMA HashEntryProperties)* '}' ';' |
                             'our hashref $properties' OP19_VARIABLE_ASSIGN LBRACE '}' ';' ;
    Method:                  'our' TYPE_METHOD VARIABLE_SYMBOL '= sub {' MethodArguments? Operation* '}' ';' ;
    MethodArguments:         LPAREN_MY Type SELF (OP21_LIST_COMMA MY Type VARIABLE_SYMBOL)* ')' OP19_VARIABLE_ASSIGN '@_;' ;
    MethodOrSubroutine:      Method | Subroutine;

Code Examples:

CompileUnit

Class

D.4.2: Operations

[[[ SYNTAX PRODUCTION RULES, OPERATIONS ]]]

    Operation:               Expression ';' | OP01_NAMED_SCOLON | OP10_NAMED_UNARY_SCOLON | Statement ;
    Operator:                LPAREN OP01_PRINT FHREF_SYMBOL_BRACES ListElements ')' |
                             OP01_NAMED SubExpression | LPAREN OP01_NAMED ListElement OP21_LIST_COMMA ListElements ')' |
                             OP01_OPEN MY TYPE_FHREF FHREF_SYMBOL OP21_LIST_COMMA LITERAL_STRING OP21_LIST_COMMA SubExpression |
                             OP01_CLOSE FHREF_SYMBOL | OP03_MATH_INC_DEC Variable | Variable OP03_MATH_INC_DEC | SubExpression OP04_MATH_POW SubExpression |
                             OP05_LOGICAL_NEG SubExpression | OP05_MATH_NEG_LPAREN SubExpression ')' | SubExpression OP06_REGEX_MATCH OP06_REGEX_PATTERN |
                             SubExpression OP07_STRING_REPEAT SubExpression | SubExpression OP07_MATH_MULT_DIV_MOD SubExpression |
                             SubExpression OP08_MATH_ADD_SUB SubExpression | SubExpression OP08_STRING_CAT SubExpression | SubExpression OP09_BITWISE_SHIFT SubExpression |
                             OP10_NAMED_UNARY SubExpression | OP10_NAMED_UNARY | SubExpression OP11_COMPARE_LT_GT SubExpression |
                             SubExpression OP12_COMPARE_EQ_NE SubExpression | SubExpression OP13_BITWISE_AND SubExpression |
                             SubExpression OP14_BITWISE_OR_XOR SubExpression | SubExpression OP15_LOGICAL_AND SubExpression | SubExpression OP16_LOGICAL_OR SubExpression |
                             SubExpression OP17_LIST_RANGE SubExpression | SubExpression OP18_TERNARY VariableOrLiteral COLON VariableOrLiteral |
                             OP22_LOGICAL_NEG SubExpression | SubExpression OP23_LOGICAL_AND SubExpression | SubExpression OP24_LOGICAL_OR_XOR SubExpression ;
    OperatorVoid:            OP01_PRINT (STDOUT_STDERR)? ListElements ';' | OP01_PRINT FHREF_SYMBOL_BRACES ListElements ';' |
                             OP01_NAMED_VOID_SCOLON | OP01_NAMED_VOID_LPAREN ListElements? ')' ';' | OP01_NAMED_VOID ListElements ';' | 
                             OP01_NAMED ListElement OP21_LIST_COMMA ListElements ';' | OP19_LOOP_CONTROL_SCOLON | OP19_LOOP_CONTROL LoopLabel ';' ;
    Expression:              Operator | WORD_UPPERCASE LPAREN ')' | CONSTANT_CALL_SCOPED | WordScoped LPAREN ListElements? ')' |
                             Variable OP02_METHOD_THINARROW LPAREN ListElements? ')' | WordScoped OP02_METHOD_THINARROW_NEW ')' ;
    SubExpression:           Expression | 'undef' | Literal | Variable | ArrayReference | ArrayDereference | HashReference | HashDereference | LPAREN SubExpression ')' ;
    SubExpressionOrInput:    SubExpression | FHREF_SYMBOL_IN | STDIN;
    SubExpressionOrVarMod:   SubExpression | VariableModification;
    Statement:               Conditional | (LoopLabel COLON)? Loop | OperatorVoid | VariableDeclaration | VariableModification ';' ;
    Conditional:             'if' LPAREN SubExpression ')' CodeBlock ('elsif' LPAREN SubExpression ')' CodeBlock)* ('else' CodeBlock)? ;
    Loop:                    LoopFor | LoopForEach | LoopWhile ;
    LoopFor:                 'for' MY TYPE_INTEGER VARIABLE_SYMBOL LPAREN SubExpression OP17_LIST_RANGE SubExpression ')' CodeBlock |
                             'for' LPAREN_MY TYPE_INTEGER VARIABLE_SYMBOL OP19_VARIABLE_ASSIGN OpNamedScolonOrSubExp VARIABLE_SYMBOL OP11_COMPARE_LT_GT OpNamedScolonOrSubExp SubExpressionOrVarMod ')' CodeBlock ;
    LoopForEach:             'foreach' MY Type VARIABLE_SYMBOL LPAREN ListElements ')' CodeBlock ;
    LoopWhile:               'while' LPAREN SubExpression ')' CodeBlock | 'while' LPAREN_MY Type VARIABLE_SYMBOL OP19_VARIABLE_ASSIGN SubExpressionOrInput ')' CodeBlock;
    CodeBlock:               LBRACE Operation+ '}' ;

Code Examples:

Operation

Operator

OperatorVoid

Expression

SubExpression

SubExpressionOrInput

Statement

D.4.3: Variable Data

[[[ SYNTAX PRODUCTION RULES, VARIABLE DATA ]]]

    Variable:                VariableSymbolOrSelf VariableRetrieval* ;
    VariableRetrieval:       OP02_ARRAY_THINARROW SubExpression ']' | OP02_HASH_THINARROW SubExpression '}' | OP02_HASH_THINARROW WORD '}' ;
    VariableDeclaration:     MY Type VARIABLE_SYMBOL ';' | MY Type VARIABLE_SYMBOL OP19_VARIABLE_ASSIGN OpNamedScolonOrSubExpIn | 
                             MY Type VARIABLE_SYMBOL OP02_ARRAY_THINARROW SubExpression ']' OP19_VARIABLE_ASSIGN 'undef' ';' | MY TYPE_FHREF FHREF_SYMBOL ';' ;
    VariableModification:    Variable OP19_VARIABLE_ASSIGN SubExpressionOrInput | Variable OP19_VARIABLE_ASSIGN_BY SubExpression ;
    ListElements:            ListElement (OP21_LIST_COMMA ListElement)* ;
    ListElement:             SubExpression | TypeInner SubExpression | OP01_QW | ARGV;
    ArrayReference:          LBRACKET ListElements? ']' ;
    ArrayDereference:        '@{' Variable '}' | '@{' TypeInner? ArrayReference '}' ;
    HashEntry:               VarOrLitOrOpStrOrWord OP20_HASH_FATARROW TypeInner? SubExpression | HashDereference | ENV ;
    HashEntryProperties:     OpStringOrWord OP20_HASH_FATARROW TypeInnerProperties ;
    HashReference:           LBRACE HashEntry (OP21_LIST_COMMA HashEntry)* '}' | LBRACE '}' ;
    HashDereference:         '%{' Variable '}' | '%{' TypeInner? HashReference '}' ;

Code Examples:

ListElement

D.4.4: User-Defined Words

[[[ SYNTAX PRODUCTION RULES, USER-DEFINED WORDS ]]]

    WordScoped:              WORD | WORD_SCOPED ;
    LoopLabel:               WORD_UPPERCASE ;
    Type:                    WORD | WORD_SCOPED | TYPE_INTEGER ;
    TypeInner:               MY Type '$TYPED_' OpStringOrWord OP19_VARIABLE_ASSIGN ;
    TypeInnerProperties:     MY Type '$TYPED_' OpStringOrWord OP19_VARIABLE_ASSIGN SubExpression | 
                             MY Type '$TYPED_' OpStringOrWord OP02_ARRAY_THINARROW SubExpression ']' OP19_VARIABLE_ASSIGN 'undef' ;
    TypeInnerConstant:       MY Type '$TYPED_' WORD_UPPERCASE OP19_VARIABLE_ASSIGN ;
    VariableOrLiteral:       Variable | Literal ;
    VarOrLitOrOpStrOrWord:   Variable | Literal | OpStringOrWord ;
    VariableSymbolOrSelf:    VARIABLE_SYMBOL | SELF ;
    Literal:                 LITERAL_NUMBER | LITERAL_STRING ;
    OpNamedScolonOrSubExp:   OP01_NAMED_SCOLON | OP10_NAMED_UNARY_SCOLON | SubExpression ';' ;
    OpNamedScolonOrSubExpIn: OP01_NAMED_SCOLON | OP10_NAMED_UNARY_SCOLON | SubExpressionOrInput ';' ;
    OpStringOrWord:          OP24_LOGICAL_OR_XOR | OP23_LOGICAL_AND | OP22_LOGICAL_NEG | OP19_LOOP_CONTROL_SCOLON | OP19_LOOP_CONTROL | OP12_COMPARE_EQ_NE |
                             OP11_COMPARE_LT_GT | OP10_NAMED_UNARY | OP08_MATH_ADD_SUB | OP07_MATH_MULT_DIV_MOD | OP07_STRING_REPEAT | OP01_NAMED | OP01_CLOSE | 
                             OP01_OPEN | OP01_NAMED_VOID | OP01_PRINT | WORD ;

There are no additional code examples for this section, all pertinent examples are contained in the previous sections.


APPENDIX E: BEYOND THE ROADRUNNER

Intermediate RPerl

The Scallion Book


Mastering RPerl

The Sword Book


GLOSSARY

A

Angle Brackets

Used to wrap input streams such as <STDIN> or <$MY_FILEHANDLE>.

Also known as "chevrons"; created using "less-than" < and "greater-than" > characters.

B

Braces

"curly brackets" AKA "curly braces" AKA "braces" { }

See "Brackets"

Brackets

A group of opening and closing character pairs, including:

"square brackets" AKA "brackets" [ ]

"round brackets" AKA "parentheses" ( )

"curly brackets" AKA "curly braces" AKA "braces" { }

"angle brackets" AKA "chevrons" AKA "less-than" and "greater-than" < >

See "Square Brackets"

See "Parentheses"

See "Braces"

See "Angle Brackets"

P

Parentheses

NEED DEFINITION

S

Square Brackets

NEED DEFINITION


SEE ALSO

RPerl

rperl


AUTHOR

William N. Braswell, Jr.

mailto:william.braswell@NOSPAM.autoparallel.com