# [[[ HEADER ]]] use RPerl; package RPerl::Learning; use strict; use warnings; our $VERSION = 0.195_000; # [[[ OO INHERITANCE ]]] # NEED FIX: why does the following 'use parent' command cause $VERSION to become undefined??? #use parent qw(RPerl::CompileUnit::Module::Class); #use RPerl::CompileUnit::Module::Class; # [[[ CRITICS ]]] ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls) # USER DEFAULT 1: allow numeric values & print operator ## no critic qw(ProhibitUnreachableCode RequirePodSections RequirePodAtEnd) # DEVELOPER DEFAULT 1b: allow POD & unreachable or POD-commented code, must be after line 1 # [[[ OO PROPERTIES ]]] our hashref $properties = {}; 1; # end of class __END__ =encoding utf8 =for comment DEV NOTE: BEGIN INLINE CSS DIV =begin html
=end html =head1 NAME Learning RPerl =head1 COPYRIGHT Learning RPerl is Copyright © 2013, 2014, 2015, 2016, 2017, 2018, 2019 William N. Braswell, Jr. All Rights Reserved. Learning RPerl is part of the RPerl Family of software and documentation. =head1 BOOK TITLE =begin text .;,.. .2prp02;'. ,0LRRRLLp1;. .,20LRPEEPRL02'. .'2rREEEEPRRLp1:,. .1pLRPEEEPRRLLrl;. .;2lpLREEEEEPRRLpl2,. .':lrLPEEEPPPPPRRLLpl:,. .'20LRPPPPPPPEEPRLLrpl:'. .2rLRPPRRPPPEEPRRLLrp1;'. .;lpLRRRRRPPPEEEPLLLrr0:'. .,1LRRRLLRPPPRRRRLLLrr01,. .,1pLRRRRLLRRRRRLLLLrrpl:'. .:lrLRRLLRLLLLLLLrrrrp02,. ..:lpLRRRRLLLLLLLrppp002,. .';1pLLRRLLLrpprpp0ppl2,. .'1prLRRLLrpprLrrrLLL0:. .... ..;1pLLLLLLLLLLLLLLLLr0:. '0LLLLr01;.. .;20rrrLLLLLLLLrprLLLrl:'. 'rEEEEEEEEPRL1,. .':10pLLLLLLLLLrp0pprp02;.. ;LPPEPPEEPPPRLLp2. .';1rLLrrrrpppp0000pp0l1;'.. ...',;::2222222::;,'.. 2REEPPPPPPRRLLrrp2. .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0. .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,.. .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'. .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:. ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp. ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0. .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200, .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0, ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1. .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l; .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101' 'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'. .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;. .1RLrRRLLr02:;,........,;:;;;;;,'.. 2r22rLrpp1;. .lL2;1l12' .0L;.2L0. ,2:'. ,rp;,0L0. .,2;.. .:1l00pLLrprRPp2221ll,. .',,;;;,,;:10Lr1'. '0l' .ll' ':::2pp1:,.....',. ..'';2ll1;,;::21l111;.. ..,'... ...',;;... =end text =begin man .;,.. .2prp02;'. ,0LRRRLLp1;. .,20LRPEEPRL02'. .'2rREEEEPRRLp1:,. .1pLRPEEEPRRLLrl;. .;2lpLREEEEEPRRLpl2,. .':lrLPEEEPPPPPRRLLpl:,. .'20LRPPPPPPPEEPRLLrpl:'. .2rLRPPRRPPPEEPRRLLrp1;'. .;lpLRRRRRPPPEEEPLLLrr0:'. .,1LRRRLLRPPPRRRRLLLrr01,. .,1pLRRRRLLRRRRRLLLLrrpl:'. .:lrLRRLLRLLLLLLLrrrrp02,. ..:lpLRRRRLLLLLLLrppp002,. .';1pLLRRLLLrpprpp0ppl2,. .'1prLRRLLrpprLrrrLLL0:. .... ..;1pLLLLLLLLLLLLLLLLr0:. '0LLLLr01;.. .;20rrrLLLLLLLLrprLLLrl:'. 'rEEEEEEEEPRL1,. .':10pLLLLLLLLLrp0pprp02;.. ;LPPEPPEEPPPRLLp2. .';1rLLrrrrpppp0000pp0l1;'.. ...',;::2222222::;,'.. 2REEPPPPPPRRLLrrp2. .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0. .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,.. .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'. .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:. ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp. ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0. .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200, .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0, ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1. .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l; .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101' 'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'. .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;. .1RLrRRLLr02:;,........,;:;;;;;,'.. 2r22rLrpp1;. .lL2;1l12' .0L;.2L0. ,2:'. ,rp;,0L0. .,2;.. .:1l00pLLrprRPp2221ll,. .',,;;;,,;:10Lr1'. '0l' .ll' ':::2pp1:,.....',. ..'';2ll1;,;::21l111;.. ..,'... ...',;;... =end man =for man =begin docbook .;,.. .2prp02;'. ,0LRRRLLp1;. .,20LRPEEPRL02'. .'2rREEEEPRRLp1:,. .1pLRPEEEPRRLLrl;. .;2lpLREEEEEPRRLpl2,. .':lrLPEEEPPPPPRRLLpl:,. .'20LRPPPPPPPEEPRLLrpl:'. .2rLRPPRRPPPEEPRRLLrp1;'. .;lpLRRRRRPPPEEEPLLLrr0:'. .,1LRRRLLRPPPRRRRLLLrr01,. .,1pLRRRRLLRRRRRLLLLrrpl:'. .:lrLRRLLRLLLLLLLrrrrp02,. ..:lpLRRRRLLLLLLLrppp002,. .';1pLLRRLLLrpprpp0ppl2,. .'1prLRRLLrpprLrrrLLL0:. .... ..;1pLLLLLLLLLLLLLLLLr0:. '0LLLLr01;.. .;20rrrLLLLLLLLrprLLLrl:'. 'rEEEEEEEEPRL1,. .':10pLLLLLLLLLrp0pprp02;.. ;LPPEPPEEPPPRLLp2. .';1rLLrrrrpppp0000pp0l1;'.. ...',;::2222222::;,'.. 2REEPPPPPPRRLLrrp2. .,20rLLrrrrrpppppprrrrrrrpl2:221lppprLLRPPPPEEEEEEEEEEPERLL021LEEPPLrprrprrpppLL0. .,1prprprrrLLLLRPPPEEEEPPPPPPRPPRRRRRLLRRPE333EEEE3EE33333EPRPERLpppprp000prLp1:,.. .,20rrppLRPPEEEEEEEEEEEEPPRRRRLLLLLLLRRPPPPPRRRPPEE33333PREEEEEPRLppp0pplll0p0001:'. .';20LPEEEEEEEEE3EEEEEPPRRLLLLLLLLLLRRLLLLLLLRPPEPPEEERLLLLLLLrrrpl0l;'..'',;;::,. '0LPEEEEEEEEEEPRRPPPRRRRLLLLrrLLrrLrprLLLrrLLLrLLL010prrLLrpp00:. ;rRPEE3EPPEERLLLLRPPLLLLLrrp0ll0p0l0p0l112:1lll2:1lll0l0pLLRp. ':lREPPEPPPRLRPEERLLLLrprLLLr0ll01:1l1::12::::2::2::::1120L0. .:0prLPPPPRLLRPPRRLLLrrrLLLLRRPLpll2:;::;,:12::::,,,;;;::;:200, .:0LLRRRPRPEPLLLLRRLrrLRRRRRLLLLrpp00l2:2222112211:,,,'',;:,,2l0, ...'',:1lpLRRLRLLLLLLLREEEEERrppppp0ppl11lp0pp0012:;;,,;;;,;2l1. .,1rRPPPPPPRRPEEEEPLrLLrrpprLLLLrrrLrrp1:;;,;::;;20l; .:LEEEPRrpppppppppprLLRPPPRRRRRLrrp0l2222::22101' 'rPPPLplll121llll0pprrrpppprLr0l12222221lll2'. .;0PPRLLrpll11222:;;,,,,:10rrrrrrrp0ll1:;. .1RLrRRLLr02:;,........,;:;;;;;,'.. 2r22rLrpp1;. .lL2;1l12' .0L;.2L0. ,2:'. ,rp;,0L0. .,2;.. .:1l00pLLrprRPp2221ll,. .',,;;;,,;:10Lr1'. '0l' .ll' ':::2pp1:,.....',. ..'';2ll1;,;::21l111;.. ..,'... ...',;;... =end docbook =for html =for html B =for html ~ or ~ =for html B =for html ~ affectionately known as ~ =for html B =for html . X
... X
..... X
....... X
being X
....... X
..... X
... X
. B ~ for ~ B X
=head1 DEDICATION For Anna. X
=head1 EDITION 0th Edition, Pre-Release Copy X
=head1 TABLE OF CONTENTS: CHAPTERS AT-A-GLANCE =over =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back X
=head1 FOREWORD [ INSERT FOREWORD CONTENT HERE ] X
=head1 PREFACE =head2 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. L L I am 1 of 3 co-founders of the Perl 11 movement. L I am also the President of the Austin Perl Mongers. L Most importantly, I am the creator of the RPerl optimizing compiler for Perl 5, about which you are currently reading! L =head2 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. =head2 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: L Significant GitHub commit dates may be viewed by forking the RPerl git repository and executing the following C command: =for rperl X $ git log --reverse --all --date=short --pretty='%cd: %s' | grep 'Learning RPerl' 2015-07-10: Learning RPerl, Chapter 1, Exercise 1, Hello World ... =for rperl X =head2 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: =over 16 =item * L =item * L =item * L =item * L =item * L =item * L =item * L =back A history of TPF grant #2 may be found at the following links: =over 16 =item * L =item * L Feb 2016 Grant Votes|http://news.perlfoundation.org/2016/02/janfeb-2016-grant-votes.html> =back =head2 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. L =for rperl X 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 =for rperl X =head2 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": L 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... B =head2 Section 0.7: POD "The Pod format is not necessarily sufficient for writing a book." L ~ Saint Larry Wall & Sean M. Burke X
"Challenge accepted." L ~ Will Braswell X
=head1 CHAPTER 1: INTRODUCTION =head2 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, I<"runs really fast">. Throughout this text, the following 14 typography conventions are utilized: =over =item * "Literal Quotation" =item * I<"First Occurrence Of Key Concept"> =item * I =item * B =item * F =item * B> =for html =item * B =item * I =for html =item * L =item * C<$code_snippet = 'unhighlighted';> =item * C<`command_line_program.pl --with --arguments`> (Only Include Characters Between `Backquotes` When Running Command; Discard Backquote Characters Themselves) =item * ... my string $code_block = 'highlighted on RPerl.org & MetaCPAN.org'; # with comments my integer $more_code = 17; # http://www.catb.org/jargon/html/R/random-numbers.html return 'end of indented code block'; =item * ... =for rperl X $ command_line_program.pl --with --arguments Please provide input: foo bar Your output is: howdy howdy howdy =for rperl X =item * ... =for rperl X Documentation referring to `command_line_program.pl --with --arguments` among other things. When executed, the above command accepts as input the string 'foo bar', and displays as output the string 'howdy howdy howdy'. =for rperl X =back =head2 Section 1.2: Learning Perl =begin text This book is purposefully patterned after the popular educational text B, 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 B, but all content is re-written for RPerl. B also copies the same exercise concepts as B, 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 B from our friends at O'Reilly: =end text =begin html

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:

=end html L =head2 Section 1.3: Is This Book A Good Choice For You? =over =item * Are you totally new to computer programming, and you want to learn how to write your first program? =item * Do you already know Perl, and now you want to make your Perl code run faster? =item * Do you already know some other computer language, and Perl has always intrigued you? =item * Do you love learning about new languages and compilers? =item * Do you miss your favorite old language Perl, and you're looking for a legitimate reason to go back? =item * Are you a scientist and you just want your code to run really fast without the headaches of C or C++? =back 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 L L L L. You'll thank us in the morning. =head2 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. =head2 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. =head2 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. =head2 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. =head2 Section 1.8: What Does The Name RPerl Actually Mean? RPerl stands for I<"Restricted Perl">, in that we restrict our use of Perl to those parts which can be made to run fast. RPerl also stands for I<"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 I<"Roadrunner Perl">, in that it I. =head2 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. =head2 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 I<"high magic">, so RPerl is focused on supporting the I<"low magic"> parts of Perl which can be made to run fast. =head2 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. =head2 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: =over =item * YAPC::NA L =item * Austin Perl Mongers L =item * RPerl Website L =item * Github L =item * Facebook Page L =item * Facebook Groups L L =item * Twitter L =item * PerlMonks L =item * Perl Blogs L =item * IRC #perl11 L =back =head2 Section 1.13: What Is The RPerl Community Up To? As of US Independence Day 2016, RPerl v2.0 (codename I) 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": L L =head2 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. =head2 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. =head2 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: =for rperl X $ sudo cpan RPerl =for rperl X You may also choose to use the C<`cpanm`> command for simplicity, or the C 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: =for rperl X $ rperl -v =for rperl X 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: L Unless you are an experienced programmer or system administrator, it is B 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 C<`sudo cpan RPerl`> command as described above. L If you are interested in viewing the source code of RPerl itself, you may find the latest major release of RPerl (stable) on CPAN: L You may find the latest development release of RPerl (possibly unstable) on Github: L =head2 Section 1.17: Where Is Perl Software Stored Online? CPAN is the I<"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. L L Several other programming language communities have copied the success and implementation of CPAN, including JSAN for Javascript, CRAN for R, and CCAN for C. =head2 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 =head2 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: L =head2 Section 1.20: Are There Any Bugs In RPerl? All software has small (or large) problems called I<"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: L Please be sure to include all of the following information in your bug report: =over =item * Pertinent Problem Message Output, If Long Use L =item * Operating System Version C<`cat /etc/issue`> =item * Perl Version C<`perl -v`> =item * RPerl Version C<`rperl -v`> =back Although Github Issues is strongly preferred, the RPerl development team also supports the legacy CPAN ticket system: L =head2 Section 1.21: How Can I Write A Program Using RPerl? Computer programs are written in a human-readable format called I<"source code">. Source code is stored as plain text data inside normal computer files. These are the same kind of text files which you may be already familiar with as ending in the F<.txt> file suffix. The only difference is we simply choose a different file name suffix to identify these specific text files as containing source code. Thus, 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. L 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 I<"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). L L L =head2 Section 1.22: A Sample RPerl Program #!/usr/bin/env 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"; =head2 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 C<#> are comments and can be safely ignored or discarded without affecting the program. The I<"shebang"> section is required, always contains exactly 1 line, and is short for I<"hash bang">; referring to the two leading characters C<#!> of this line. The I<"octothorpe"> character C<#> (tic-tac-toe symbol) is called a I<"pound-sign"> when used on a telephone, and is called a I<"hash"> (or more recently and less accurately I<"hash-tag">) when used on a computer. The exclamation-point character C is called a I<"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 invoked by C) and pass the remaining contents of the text file as input to the command. (Traditionally, the Perl interpreter has been located at F, however we must practice prudence by asking the operating system environment where our Perl interpreter is actually located, in order to support those cases where Perl may be installed in a non-standard directory, such as with Perlbrew or manually-built Perl interpreters. Please see L for more information.) In other words, if the first line of a plain text file is C<#!/usr/bin/env perl> (or C<#!/usr/bin/perl> or something similar), then that file is a Perl program. The I<"header"> section is required and always contains 4 lines for an RPerl I<"program"> file ending in F<.pl>, or 5 lines for an RPerl I<"module"> ending in F<.pm> (covered later in Chapter 11). C is recognized by Perl as a special I<"keyword"> (also a Perl I<"function">) which has 2 primary purposes: to load additional RPerl modules, and to change RPerl settings called I<"pragma"> settings. (Please see L Pragmas & Magic> for more information about I<"pragma"> system configuration modes.) The C line is dual-purpose, it both loads the F module and enables the special RPerl low-magic pragma. (Please see L for more information about low magic versus high magic.) The C and C lines enable basic Perl pragmas which require decent programming practices by the human programmers. The C line sets the version number of this RPerl program. The I<"critics"> section aids in the proper detection of errors in your RPerl source code. This section of source code is only included as necessary, and may contain 1 or more lines beginning with C<## 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" C command allows the use of numeric values such as C<21> and C<12>, as well as the common C command. The C critics command allows the printing of C<'have $foo = '>, where a single-quoted C<'> string literal value contains the the dollar-sign C<$> sigil (covered later in Chapter 2). The I<"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 C line declares a new I<"variable"> named C<$foo>. A variable is simply a place to store your individual pieces of data, identified by a name of your choice. (Please see L for more information about variables.) Every variable in RPerl must be defined as containing exactly one type of data, such as whole numbers or decimal numbers or characters or strings, etc. (In normal Perl, there are no data types.) The variable C<$foo> is defined as containing the data type I<"integer">, which is another word for whole numbers, such as C<0> or C<1> or C<-5_126>. C<$foo> is initialized to contain the arithmetic result of numeric literal values C<21> plus C<12>. The C line does much the same thing, creating a new numeric variable named C<$bar> and initialized with C<23> times C<42> times C<2>. The C line creates a new variable named C<$baz>. This variable contains floating-point numeric data, which is simply another term for decimal numbers such as C<0.1> or C<1.0> or C<-5_126.34>. The variable C<$baz> is initialized to contain the quotient of the C<$bar> and C<$foo> variables. The C RPerl type conversion I<"subroutine"> converts a non-floating-point C value to a floating-point C value. (A subroutine is a user-defined operation, in this case pre-defined by the RPerl development team for your convenience; please see L for more information.) The C, 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. =head3 Section 1.25.3: Performance Of RPerl The question of I<"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: L The most condensed answer is that I<"RPerl is really fast."> Utilizing RPerl's fastest execution modes, we see performance very close to the highly-optimized I programming language, which means RPerl is now among the short list of "world's fastest languages" along with C, C++, and Fortran. =head3 Section 1.25.4: The Low-Magic Perl Commandments The high-magic features of Perl are primarily responsible for the slow speed at which Perl executes general-purpose computations. The I<"R"> in RPerl stands for I<"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 I (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. L =for text The LMPC draw inspiration from, and (wherever possible) work together with Damian Conway's B and Jeffrey Thalhammer's Perl::Critic software. =for 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.

L L =head3 Section 1.25.5: Perlism & The Book Of RPerl I 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.) =for text A I is an adherent to the Perlism religion. Perlism has a revered founder, Saint Larry (himself a devout Christian); a prophet, I (Will); a monastery and shrine, I; commandments, The LMPC; proverbs from Saint Larry including I, I, and I; and canonical scriptures, including Saint Larry's B and The Voice's B. =for html

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.

=for comment START HERE: INSERT MAN & DOCBOOK FORMATS =for comment START HERE: INSERT MAN & DOCBOOK FORMATS =for comment START HERE: INSERT MAN & DOCBOOK FORMATS 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. L =head3 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. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c l l . =end man =for html =begin docbook
Proverbs & Acronyms =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook LMFB (Let Many Flowers Bloom) =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook HTAAOF (Have The Appropriate Amount Of Fun) =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for text }]}, 1); =for man T} =for html
=for docbook 3 Great Virtues Of A Programmer: LIH (Laziness, Impatience, Hubris) =for man T}@T{ =for html =for docbook 3 Greater Virtues Of A Programmer: DPH (Diligence, Patience, Humility) =for text }]}, 1); =for man T} =for html
=for docbook TIMTOWTDI (There Is More Than One Way To Do It) =for man T}@T{ =for html =for docbook TDNNTBMTOWTDI (There Does Not Need To Be More Than One Way To Do It) TIOFWTDI (There Is One Fastest Way To Do It) =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook PTBF (Pick The Best Flowers) =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook DTAAOW (Do The Appropriate Amount Of Work) =for text }]}, 1); =for man T} =for html
=for docbook In addition to St. Larry's official proverbs, there are a number of other commonly-used catch phrases and ideas in the Perl community. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c l l . =end man =for html =begin docbook
Catch Phrases & Acronyms =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Perl Is The Swiss Army Chainsaw =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Perl Is Line-Noise Perl Is A Write-Only Language =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Perl 5 Is The Camel Perl 5 Is The Raptor Perl 6 Is The Butterfly =for man T}@T{ =for html =for docbook RPerl Is The Roadrunner =for text }]}, 1); =for man T} =for html
=for docbook Perl Is The Onion =for man T}@T{ =for html =for docbook RPerl Is The Scallion =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook RPerl Is The Sword =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook RPerl Is Best Practices =for text }]}, 1); =for man T} =for html
=for docbook =head2 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 C<--num_cores=8> command-line argument to double the default number of parallel cores, for example. (Please see L and L 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 L parallelization software. In the near future we will add support for distributed memory platforms, such as clusters and the cloud, by utilizing the L parallelization software, as well as GPUs and other specialty hardware by utilizing the L 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 L (AKA L) for loop parallelization, by utilizing the L 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: =over =item * Generate Stand-Alone Binary Executable Files & Shared Object Files =item * Control Native C++ Types Used For Integer & Number Values =item * Support SSE Data Types & Operations =item * Support GMP Data Types & Operations =item * Monolithic Modules =item * Uncompile (Delete) Unwanted Compiled Files =item * Two-Dimensional Data Structures =back =head2 Section 1.27: Exercises =head3 1. Hello World [ 15 mins ] On a computer with RPerl already installed, create a directory named F containing a sub-directory named F. Using the B> example program as a template, manually type a new RPerl program into a file named F inside the F sub-directory. The sole purpose of your first program is to use the C operator and simply display the following one line of text output, followed by one newline character: =for rperl X Hello, World! =for rperl X Run your new program by issuing the following command at your terminal command prompt: =for rperl X $ rperl -t LearningRPerl/Chapter1/exercise_1-hello_world.pl =for rperl X I command, so your resulting program should be 7 lines long, not counting comments or blank lines.> =head3 2. RPerl Commands [ 15 mins ] First, run the following RPerl command, and observe the output for use in 2a and 2b below: =for rperl X $ rperl -? =for rperl X 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: =for rperl X $ 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 =for rperl X 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? =head3 3. Foo Bar Arithmetic [ 15 mins ] Manually type the entire B> example program into a file named F inside the F sub-directory. (Even if you have already used copy-and-paste on the B> 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 C<$zab>, set its value to C<$foo> divided by C<$bar> (don't forget C), change the starting value of C<$bar>, and use C to generate the following output: =for rperl X have $foo = 33 have $bar = 966 have $baz = 29.272_727_272_727_3 have $zab = 0.034_161_490_683_229_8 =for rperl X Run your program thusly: =for rperl X $ rperl -t LearningRPerl/Chapter1/exercise_3-foo_bar_arithmetic.pl =for rperl X X
=head1 CHAPTER 2: SCALAR VALUES & VARIABLES (NUMBERS & TEXT) Most programming languages include the basic principle of using named I<"variables"> to store data values such as numbers, text strings, and lists of multiple numbers or strings. As stated in L above, a "variable is simply a place to store your individual pieces of data, identified by a name of your choice". The term I<"variable"> is a reference to the fact that the value stored inside a variable may I<"vary"> according to the needs of the programmer. If a stored value will never change, then you should use a I<"constant"> instead of a variable. (Please see section L for more information about constants.) Multiple variables may be created in a computer program, each with a different name such as C<$foo> or C<$bar> or C<$baz>, and each potentially containing a different value. You can choose whatever name you want for each variable you create, such as the following three variables: my integer $some_whole_number = 23; my number $some_decimal_number = 21.12; my string $some_funny_word = 'howdy'; A single piece of data, such as one number or one string, is called a I<"scalar">. Multiple pieces of data combined into a single aggregate structure may be either an I<"array"> or a I<"hash">, described in chapters 3 and 6, respectively. (Although sharing the same terminology, the I data structure is not related to the I C<#> tic-tac-toe character.) In normal Perl, only scalar variable names begin with the dollar-sign C<$> I<"sigil">, while aggregate data structures are stored in variables starting with different sigils like at-sign C<@> or percent-sign C<%>. A sigil is simply a special character prefixed to a word, in order to help us quickly identify different source code components. In RPerl, all variable names begin the C<$> sigil, both scalar types and aggregate structures alike. =for comment DEV NOTE, CORRELATION #rp400: all POD changes must be made in both RPerl.pm & RPerl/Learning.pm RPerl provides 7 scalar data types: =over =item * C =item * C =item * C (core) =item * C =item * C (core) =item * C =item * C (core) =back Of the 7 RPerl scalar data types, 3 are directly (natively) supported by the Perl 5 core: C, C, and C. 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: C and C can be stored within either an C or C; C can be stored within a C; and C is supported by the C wrapper around the C 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 I<"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 =head2 Section 2.1: Numeric Data & Operators RPerl provides 5 numeric data types: =over =item * C S< >S< >S< >S< >a boolean logic value, either 0 or 1 =item * C S< >S< >S< >S< >a positive whole number value, greater-than or equal to 0 =item * C S< >S< >S< >S< >a whole number value, either negative, 0, or positive =item * C S< >S< >S< >S< >a possibly-very-large whole number value, either negative, 0, or positive; may safely exceed your computer's data type limits =item * C S< >S< >S< >S< >a floating-point decimal number value, either negative, 0, or positive =back Perl 5 provides several I<"built-in operators"> designed for use with numeric data, which can be organized into 6 general categories: =over =item * Arithmetic =item * Trigonometry =item * Comparison (Relational & Equality) =item * Logic =item * Bitwise =item * Miscellaneous =back Most of the operators which have names consisting of normal letters (a - z) are classified as I<"functions"> in Perl 5 terminology. Notable exceptions are the logic operators, which are simply classified as "operators" in Perl, along with most of the operators which have names consisting of special characters. For the sake of simplicity, we will only use the term "operator" throughout this textbook. L L Each operator in Perl 5 (and thus RPerl) is assigned 4 important characteristics: I<"arity"> (a number), I<"fixity"> (a placement location), I<"precedence"> (a number) and I<"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: L 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. L =head3 Section 2.1.1: Boolean Literals The most memory-efficient numeric literal is C, which represents a single I<"bit"> (binary digit) of information. A C 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 =head3 Section 2.1.2: Unsigned Integer Literals The second most efficient numeric literal is C, which represents a single whole (non-decimal) number greater-than or equal to 0. An C 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 C 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 =head3 Section 2.1.3: Integer Literals The third most efficient numeric literal is C, which represents a single whole (non-decimal) number. An C 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 =head3 Section 2.1.4: GMP Integer Literals The GNU Multi-Precision (GMP) software library is utilized to provide the C numeric literal, representing a single whole (non-decimal) number which may safely exceed the data type limits of your operating system and hardware. A C 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 =head3 Section 2.1.5: Number Literals The C 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 =head3 Section 2.1.6: Underscore Digit Separators For C, C, C, and C literals, an I<"underscore"> C<_> 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 =head3 Section 2.1.7: Optional Positive Sign For C, C, C, and C literals, an optional C<+> plus sign may be prepended to explicitly indicate a numeric literal is positive (greater-than zero). 1 # positive one +1 # also positive one =for html I =over =item * I =item * I =back =for html +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 X 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 =head3 Section 2.1.8: Scientific Notation For C, C, and C literals, very large or very small numbers may be approximated using I<"scientific notation">, where each number is normalized to have exactly one digit to the left of the decimal point, then a lower-case C character and an appropriate integer power-of-ten is appended to the resulting normalized floating-point number. The C character stands for "exponent", as in "exponent of ten", and the Perl style of scientific notation is sometimes more accurately referred to as I<"scientific e notation">. As with normal integers, negative exponents must be prefixed with a C<-> minus sign and positive exponents may be optionally prefixed with a C<+> 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 =for html I =over =item * I =item * I =item * I =back =for html 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 =head3 Section 2.1.9: Truth Values In the most simple case, a I<"truth value"> may be represented by a boolean literal where the numeric value of C<0> represents the truth value of I<"false">, and numeric C<1> represents I<"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 C<0>, or an empty string value of C. This magic behavior is not supported by C++, and thus not supported by RPerl. In C and C++, only numeric C<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 C<'0'> or C, and empty text C. This ensures the compiled C++ output code will behave identically to the original RPerl input source code, with regard to truth values. B B B, C, C, or C.> 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 =head3 Section 2.1.10: Floating-Point Error A I<"floating-point number"> is any number which includes a decimal point C<.> 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 C. 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 I<"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 C<0.105>, which seems normal enough. Let us further suppose you want to divide C<0.105> by some other number, say C<1_000>, and by the simple rules of arithmetic you would expect to arrive at an answer of C<0.000_105>. Unfortunately, due to the way floating-point numbers are stored in computer memory, the actual result is closer to C<0.000_104_999>, so C<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: =over =item * A floating-point operator which must return a specific, exact result =item * A floating-point variable which must contain a specific, exact value =item * A floating-point value which must exactly equal another floating-point value =back To compensate for unpredictable floating-point error, you should use the I<"floating-point epsilon"> value stored in the constant C, 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 C<-> and absolute value C operators to take the positive difference, then use the less-than C> 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 X 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 B B B to check for approximate equality instead of exact equality.> =head3 Section 2.1.11: Arithmetic Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Arithmetic Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Absolute Value =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook abs =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Natural Exponential Function =for man T}@T{ =for html =for docbook exp =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Exponent AKA Power =for man T}@T{ =for html =for docbook ** =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 04 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Negative with Parentheses =for man T}@T{ =for html =for docbook -( ) =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 05 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Multiply =for man T}@T{ =for html =for docbook * =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 07 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Divide =for man T}@T{ =for html =for docbook / =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 07 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Modulo AKA Modulus =for man T}@T{ =for html =for docbook % =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 07 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Add =for man T}@T{ =for html =for docbook + =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 08 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Subtract =for man T}@T{ =for html =for docbook - =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 08 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Natural Logarithm =for man T}@T{ =for html =for docbook log =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Square Root =for man T}@T{ =for html =for docbook sqrt =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B abs VALUE VALUE is numeric value; If operand VALUE is 0 or positive (greater-than 0), return unchanged; If VALUE is negative (less-than 0), return positive number with equal magnitude (distance from 0) abs 0 # 0 abs 1 # 1 abs -1 # 1 abs 2_112.23 # 2_112.23 abs -2_112.23 # 2_112.23 =back =over =item * B exp VALUE VALUE is numeric value; Raise C (base of natural logarithm) to the power of operand VALUE, return result exp 0 # 1 exp 1 # 2.718_281_828_459_05 exp -1 # 0.367_879_441_171_442 =back =over =item * B VALUE1 ** VALUE2 VALUE1 and VALUE2 are numeric values; Raise first operand VALUE1 to the power of second operand VALUE2, return result 0 ** 0 # 1 0 ** 1 # 0 0 ** 2 # 0 0 ** 3 # 0 1 ** 0 # 1 1 ** 1 # 1 1 ** 2 # 1 1 ** 3 # 1 2 ** 0 # 1 2 ** 1 # 2 2 ** 2 # 4 2 ** 3 # 8 (-1) ** 0 # 1 (-1) ** 1 # -1 (-1) ** 2 # 1 (-1) ** 3 # -1 (-2) ** 0 # 1 (-2) ** 1 # -2 (-2) ** 2 # 4 (-2) ** 3 # -8 0 ** -1 # inf 0 ** -2 # inf 0 ** -3 # inf 1 ** -1 # 1 1 ** -2 # 1 1 ** -3 # 1 2 ** -1 # 0.5 2 ** -2 # 0.25 2 ** -3 # 0.125 (-1) ** -1 # -1 (-1) ** -2 # 1 (-1) ** -3 # -1 (-2) ** -1 # -0.5 (-2) ** -2 # 0.25 (-2) ** -3 # -0.125 =back =over =item * B -( VALUE ) VALUE is numeric value; Change sign of operand VALUE, return result; Negative VALUE becomes positive, and positive VALUE becomes negative; Parentheses must be used, due to ambiguity of hyphen C<-> character as negative operator, subtraction operator, or negative number literal -( 0) # 0 -( 1) # -1 -(-1) # 1 -( 0.25) # -0.25 -(-0.25) # 0.25 -( 2_112.23) # -2_112.23 -(-2_112.23) # 2_112.23 =back =over =item * B VALUE1 * VALUE2 VALUE1 and VALUE2 are numeric values; Multiply first operand VALUE1 by second operand VALUE2, return product 0 * 0 # 0 0 * 1 # 0 0 * -1 # 0 1 * 0 # 0 1 * 1 # 1 1 * -1 # -1 -1 * 0 # 0 -1 * 1 # -1 -1 * -1 # 1 0.5 * 0 # 0 0.5 * 0.5 # 0.25 0.5 * -0.5 # -0.25 0.5 * 1 # 0.5 0.5 * -1 # -0.5 0.5 * 2 # 1.0 0.5 * -2 # -1.0 =back =over =item * B VALUE1 / VALUE2 VALUE1 and VALUE2 are numeric values; Divide first operand VALUE1 by second operand VALUE2, return quotient; Error if attempt to divide by 0 0 / 0 # ERROR 0 / 1 # 0 0 / -1 # 0 1 / 0 # ERROR 1 / 1 # 1 1 / -1 # -1 -1 / 0 # ERROR -1 / 1 # -1 -1 / -1 # 1 0.5 / 0 # ERROR 0.5 / 0.5 # 1 0.5 / -0.5 # -1 0.5 / 1 # 0.5 0.5 / -1 # -0.5 0.5 / 2 # 0.25 0.5 / -2 # -0.25 =back =over =item * B VALUE1 % VALUE2 VALUE1 and VALUE2 are numeric values; Divide integer part of first operand VALUE1 by integer part of second operand VALUE2, return remainder; Error if attempt to modulus by VALUE2 with absolute value less-than 1 0 % 0 # ERROR 0 % 1 # 0 0 % -1 # 0 1 % 0 # ERROR 1 % 1 # 0 1 % -1 # 0 -1 % 0 # ERROR -1 % 1 # 0 -1 % -1 # 0 0.5 % 0 # ERROR 0.5 % 0.5 # ERROR 0.5 % -0.5 # ERROR 0.5 % 1 # 0 0.5 % -1 # 0 0.5 % 2 # 0 0.5 % -2 # 0 =back =over =item * B VALUE1 + VALUE2 VALUE1 and VALUE2 are numeric values; Add first operand VALUE1 to second operand VALUE2, return sum 0 + 0 # 0 0 + 1 # 1 0 + -1 # -1 1 + 0 # 1 1 + 1 # 2 1 + -1 # 0 -1 + 0 # -1 -1 + 1 # 0 -1 + -1 # -2 0.5 + 0 # 0.5 0.5 + 0.5 # 1.0 0.5 + -0.5 # 0 0.5 + 1 # 1.5 0.5 + -1 # -0.5 0.5 + 2 # 2.5 0.5 + -2 # -1.5 =back =over =item * B VALUE1 - VALUE2 VALUE1 and VALUE2 are numeric values; Subtract second operand VALUE2 from first operand VALUE1, return difference 0 - 0 # 0 0 - 1 # -1 0 - -1 # 1 1 - 0 # 1 1 - 1 # 0 1 - -1 # 2 -1 - 0 # -1 -1 - 1 # -2 -1 - -1 # 0 0.5 - 0 # 0.5 0.5 - 0.5 # 0 0.5 - -0.5 # 1.0 0.5 - 1 # -0.5 0.5 - -1 # 1.5 0.5 - 2 # -1.5 0.5 - -2 # 2.5 =back =over =item * B log VALUE VALUE is numeric value; Take logarithm base C of operand VALUE, return result; Constant C is known as Euler's Number and is defined as the limit of C<(1 + 1/$n)**$n> as C<$n> grows to infinity; To instead calculate logarithm using a base other than C, utilize ratio C<(log $operand)/(log $base)>; Error if attempt to take logarithm of VALUE less-than or equal to 0 log 0 # ERROR log 1 # 0 log -1 # ERROR log 2.718_281_828_459_05 # 1 =back =over =item * B sqrt VALUE VALUE is numeric value; Take square root of operand VALUE, return result; Error if attempt to take square root of VALUE less-than 0 sqrt 0 # 0 sqrt 1 # 1 sqrt -1 # ERROR sqrt 2 # 1.414_213_562_373_1 =back =head3 Section 2.1.12: Trigonometry Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Trigonometry Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Cosine =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Arctangent-Divide =for man T}@T{ =for html =for docbook atan2 =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Sine =for man T}@T{ =for html =for docbook sin =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook cos =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B atan2 VALUE1, VALUE2 VALUE1 and VALUE2 are numeric values; Divide first operand VALUE1 by second operand VALUE2, take arctangent of quotient, return result; Attempts to conform to Open Group / IEEE standards: L L To instead calculate tangent of 1 operand (not arctangent of 2 operands), utilize trigonometry identity ratio C<(sin $operand)/(cos $operand)> atan2 0, 0 # 0, MAY BE DIFFERENT ON YOUR SYSTEM atan2 0, 1 # 0 atan2 0, -1 # 3.141_592_653_589_79, DEFINED AS PI atan2 1, 0 # 1.570_796_326_794_9 atan2 1, 1 # 0.785_398_163_397_448 atan2 1, -1 # 2.356_194_490_192_34 atan2 -1, 0 # -1.570_796_326_794_9 atan2 -1, 1 # -0.785_398_163_397_448 atan2 -1, -1 # -2.356_194_490_192_34 =back =over =item * B sin VALUE VALUE is numeric value; Take sine of operand VALUE, return result sin 0 # 0 sin 1 # 0.841_470_984_807_897 sin -1 # -0.841_470_984_807_897 sin 3.141_592_653_589_79 # 0, MAY BE SLIGHTLY OFF DUE TO FLOATING POINT ERROR =back =over =item * B cos VALUE VALUE is numeric value; Take cosine of operand VALUE, return result cos 0 # 1 cos 1 # 0.540_302_305_868_14 cos -1 # 0.540_302_305_868_14 cos 3.141_592_653_589_79 # -1 =back =head3 Section 2.1.13: Comparison (Relational & Equality) Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Comparison (Relational & Equality) Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Less-Than-Or-Equal =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Less-Than =for man T}@T{ =for html =for docbook < =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Greater-Than =for man T}@T{ =for html =for docbook > =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook <= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Greater-Than-Or-Equal =for man T}@T{ =for html =for docbook >= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Equal =for man T}@T{ =for html =for docbook E<61>E<61> =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Not-Equal =for man T}@T{ =for html =for docbook != =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Three-Way Comparison AKA Spaceship =for man T}@T{ =for html =for docbook <=> =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B VALUE1 < VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine relation of operands, return true if first operand VALUE1 is less-than second operand VALUE2, otherwise return false 0 < 0 # false 0 < 1 # true 0 < -1 # false 1 < 0 # false 1 < 1 # false 1 < -1 # false -1 < 0 # true -1 < 1 # true -1 < -1 # false =back =over =item * B VALUE1 > VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine relation of operands, return true if first operand VALUE1 is greater-than second operand VALUE2, otherwise return false 0 > 0 # false 0 > 1 # false 0 > -1 # true 1 > 0 # true 1 > 1 # false 1 > -1 # true -1 > 0 # false -1 > 1 # false -1 > -1 # false =back =over =item * B VALUE1 <= VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine relation of operands, return true if first operand VALUE1 is less-than or equal to second operand VALUE2, otherwise return false 0 <= 0 # true 0 <= 1 # true 0 <= -1 # false 1 <= 0 # false 1 <= 1 # true 1 <= -1 # false -1 <= 0 # true -1 <= 1 # true -1 <= -1 # true =back =over =item * B VALUE1 >= VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine relation of operands, return true if first operand VALUE1 is greater-than or equal to second operand VALUE2, otherwise return false 0 >= 0 # true 0 >= 1 # false 0 >= -1 # true 1 >= 0 # true 1 >= 1 # true 1 >= -1 # true -1 >= 0 # false -1 >= 1 # false -1 >= -1 # true =back =over =item * B VALUE1 == VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine equality of operands, return true if first operand VALUE1 is equal to second operand VALUE2, otherwise return false 0 == 0 # true 0 == 1 # false 0 == -1 # false 1 == 0 # false 1 == 1 # true 1 == -1 # false -1 == 0 # false -1 == 1 # false -1 == -1 # true =back =over =item * B VALUE1 != VALUE2 VALUE1 and VALUE2 are numeric values; Compare to determine equality of operands, return true if first operand VALUE1 is not equal to second operand VALUE2, otherwise return false 0 != 0 # false 0 != 1 # true 0 != -1 # true 1 != 0 # true 1 != 1 # false 1 != -1 # true -1 != 0 # true -1 != 1 # true -1 != -1 # false =back =over =item * B VALUE1 <=> VALUE2 VALUE1 and VALUE2 are numeric values; Perform three-way comparison of operands; Return -1 if first operand VALUE1 is less-than second operand VALUE2, return 0 if operands are equal, or return 1 if VALUE1 is greater-than VALUE2; Randal L. Schwartz coined the operator's nickname based on visual similarity to Darth Vader's TIE Advanced x1 (TIE fighter) personal spacecraft (Thankfully, CoE> and C<[=O=]> are not yet valid Perl 5 syntax) 0 <=> 0 # 0 0 <=> 1 # -1 0 <=> -1 # 1 1 <=> 0 # 1 1 <=> 1 # 0 1 <=> -1 # 1 -1 <=> 0 # -1 -1 <=> 1 # -1 -1 <=> -1 # 0 =back =head3 Section 2.1.14: Logic Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Logic Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Logical Or =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Logical Negation =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Logical And =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Logical Or =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Logical Xor =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Logical Negation =for man T}@T{ =for html =for docbook ! =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 05 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Logical And =for man T}@T{ =for html =for docbook && =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 15 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook || =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 16 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook not =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 22 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook and =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 23 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook or =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 24 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook xor =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 24 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B ! VALUE not VALUE VALUE is numeric value; Take logical negation of operand VALUE, return result; Logical negation operators C and C return the same results, and differ only by precedence ! 0 # true ! 1 # false ! -1 # false not 0 # true not 1 # false not -1 # false =back =over =item * B VALUE1 && VALUE2 VALUE1 and VALUE2 VALUE1 and VALUE2 are numeric values; Take logical conjunction of operands VALUE1 and VALUE2, return result; Logical and operators C<&&> and C return the same results, and differ only by precedence 0 && 0 # false 0 && 1 # false 0 && -1 # false 1 && 0 # false 1 && 1 # true 1 && -1 # true -1 && 0 # false -1 && 1 # true -1 && -1 # true 0 and 0 # false 0 and 1 # false 0 and -1 # false 1 and 0 # false 1 and 1 # true 1 and -1 # true -1 and 0 # false -1 and 1 # true -1 and -1 # true =back =over =item * B VALUE1 || VALUE2 VALUE1 or VALUE2 VALUE1 and VALUE2 are numeric values; Take logical disjunction of operands VALUE1 and VALUE2, return result; Logical or operators C<||> and C return the same results, and differ only by precedence 0 || 0 # false 0 || 1 # true 0 || -1 # true 1 || 0 # true 1 || 1 # true 1 || -1 # true -1 || 0 # true -1 || 1 # true -1 || -1 # true 0 or 0 # false 0 or 1 # true 0 or -1 # true 1 or 0 # true 1 or 1 # true 1 or -1 # true -1 or 0 # true -1 or 1 # true -1 or -1 # true =back =over =item * B VALUE1 xor VALUE2 VALUE1 and VALUE2 are numeric values; Take logical exclusive disjunction of operands VALUE1 and VALUE2, return result 0 xor 0 # false 0 xor 1 # true 0 xor -1 # true 1 xor 0 # true 1 xor 1 # false 1 xor -1 # false -1 xor 0 # true -1 xor 1 # false -1 xor -1 # false =back =head3 Section 2.1.15: Bitwise Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Bitwise Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Bitwise Shift Left =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Bitwise Shift Right =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Bitwise Negation with Parentheses =for man T}@T{ =for html =for docbook ~( ) =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 05 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook << =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 09 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook >> =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 09 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Bitwise And =for man T}@T{ =for html =for docbook & =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 13 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Bitwise Or =for man T}@T{ =for html =for docbook | =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 14 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Bitwise Xor =for man T}@T{ =for html =for docbook ^ =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 14 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook All code examples are shown using 64-bit integers; your results may vary depending upon your C++ compiler and hardware platform. B B B ~(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 B pragma configuration command as well as RPerl's C and C data types must be utilized in correct combination, as described below. Perl relies on the C 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.> B 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 C 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 C 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.> B pragma also affects the results of all arithmetic and comparison operators by discarding the non-integer (fractional) portion of input operands, as if the C 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 C.> B pragma:> L # 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 X # 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 X # 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++ X # 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++ =over =item * B ~( VALUE ) VALUE is numeric value; Negate each bit of operand VALUE, return result; May be used to take one's complement of VALUE; Parentheses must be used, due to ambiguity of tilde C<~> character as used for bitwise negation operator, smartmatch operator C<~~>, or regular expression C<=~> ~(-8) # 7 ~(-2) # 1 ~(-1) # 0 ~( 0) # 18_446_744_073_709_551_615 ~( 1) # 18_446_744_073_709_551_614 ~( 2) # 18_446_744_073_709_551_613 ~( 8) # 18_446_744_073_709_551_607 X use integer; ~(-8) # 7 ~(-2) # 1 ~(-1) # 0 ~( 0) # -1 ~( 1) # -2 ~( 2) # -3 ~( 8) # -9 =back =over =item * B VALUE1 << VALUE2 VALUE1 and VALUE2 are numeric values; Shift left the value of first operand VALUE1 by number of bits specified by second operand VALUE2, return result; May be used to multiply VALUE1 by 2 raised to the power of VALUE2 1 << 0 # 1 1 << 1 # 2 1 << 2 # 4 1 << 3 # 8 2 << 0 # 2 2 << 1 # 4 2 << 2 # 8 2 << 3 # 16 2 << 4 # 32 2 << 5 # 64 X -1 << -8 # 18_374_686_479_671_623_680 -1 << -1 # 9_223_372_036_854_775_808 -1 << 0 # 18_446_744_073_709_551_615 -1 << 1 # 18_446_744_073_709_551_614 -1 << 8 # 18_446_744_073_709_551_360 0 << -8 # 0 0 << -1 # 0 0 << 0 # 0 0 << 1 # 0 0 << 8 # 0 1 << -8 # 72_057_594_037_927_936 1 << -1 # 9_223_372_036_854_775_808 1 << 0 # 1 1 << 1 # 2 1 << 8 # 256 X use integer; -1 << -8 # -72_057_594_037_927_936 -1 << -1 # -9_223_372_036_854_775_808 -1 << 0 # -1 -1 << 1 # -2 -1 << 8 # -256 0 << -8 # 0 0 << -1 # 0 0 << 0 # 0 0 << 1 # 0 0 << 8 # 0 1 << -8 # 72_057_594_037_927_936 1 << -1 # -9_223_372_036_854_775_808 1 << 0 # 1 1 << 1 # 2 1 << 8 # 256 =back =over =item * B VALUE1 >> VALUE2 VALUE1 and VALUE2 are numeric values; Shift right the value of first operand VALUE1 by number of bits specified by second operand VALUE2, return result; May be used to divide VALUE1 by 2 raised to the power of VALUE2 8 >> 0 # 8 8 >> 1 # 4 8 >> 2 # 2 8 >> 3 # 1 64 >> 0 # 64 64 >> 1 # 32 64 >> 2 # 16 64 >> 3 # 8 64 >> 4 # 4 64 >> 5 # 2 64 >> 8 # 1 X -1 >> -8 # 255 -1 >> -1 # 1 -1 >> 0 # 18_446_744_073_709_551_615 -1 >> 1 # 9_223_372_036_854_775_807 -1 >> 8 # 72_057_594_037_927_935 0 >> -8 # 0 0 >> -1 # 0 0 >> 0 # 0 0 >> 1 # 0 0 >> 8 # 0 1 >> -8 # 0 1 >> -1 # 0 1 >> 0 # 1 1 >> 1 # 0 1 >> 8 # 0 X use integer; -1 >> -8 # -1 -1 >> -1 # -1 -1 >> 0 # -1 -1 >> 1 # -1 -1 >> 8 # -1 0 >> -8 # 0 0 >> -1 # 0 0 >> 0 # 0 0 >> 1 # 0 0 >> 8 # 0 1 >> -8 # 0 1 >> -1 # 0 1 >> 0 # 1 1 >> 1 # 0 1 >> 8 # 0 =back =over =item * B VALUE1 & VALUE2 VALUE1 and VALUE2 are numeric values; Take conjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result -1 & -8 # 18_446_744_073_709_551_608 -1 & -1 # 18_446_744_073_709_551_615 -1 & 0 # 0 -1 & 1 # 1 -1 & 8 # 8 0 & -8 # 0 0 & -1 # 0 0 & 0 # 0 0 & 1 # 0 0 & 8 # 0 1 & -8 # 0 1 & -1 # 1 1 & 0 # 0 1 & 1 # 1 1 & 8 # 0 X use integer; -1 & -8 # -8 -1 & -1 # -1 -1 & 0 # 0 -1 & 1 # 1 -1 & 8 # 8 0 & -8 # 0 0 & -1 # 0 0 & 0 # 0 0 & 1 # 0 0 & 8 # 0 1 & -8 # 0 1 & -1 # 1 1 & 0 # 0 1 & 1 # 1 1 & 8 # 0 =back =over =item * B VALUE1 | VALUE2 VALUE1 and VALUE2 are numeric values; Take disjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result -1 | -8 # 18_446_744_073_709_551_615 -1 | -1 # 18_446_744_073_709_551_615 -1 | 0 # 18_446_744_073_709_551_615 -1 | 1 # 18_446_744_073_709_551_615 -1 | 8 # 18_446_744_073_709_551_615 0 | -8 # 18_446_744_073_709_551_608 0 | -1 # 18_446_744_073_709_551_615 0 | 0 # 0 0 | 1 # 1 0 | 8 # 8 1 | -8 # 18_446_744_073_709_551_609 1 | -1 # 18_446_744_073_709_551_615 1 | 0 # 1 1 | 1 # 1 1 | 8 # 9 X use integer; -1 | -8 # -1 -1 | -1 # -1 -1 | 0 # -1 -1 | 1 # -1 -1 | 8 # -1 0 | -8 # -8 0 | -1 # -1 0 | 0 # 0 0 | 1 # 1 0 | 8 # 8 1 | -8 # -7 1 | -1 # -1 1 | 0 # 1 1 | 1 # 1 1 | 8 # 9 =back =over =item * B VALUE1 ^ VALUE2 VALUE1 and VALUE2 are numeric values; Take exclusive disjunction of each bit of first operand VALUE1 with respective bit of second operand VALUE2, return result -1 ^ -8 # 7 -1 ^ -1 # 0 -1 ^ 0 # 18_446_744_073_709_551_615 -1 ^ 1 # 18_446_744_073_709_551_614 -1 ^ 8 # 18_446_744_073_709_551_607 0 ^ -8 # 18_446_744_073_709_551_608 0 ^ -1 # 18_446_744_073_709_551_615 0 ^ 0 # 0 0 ^ 1 # 1 0 ^ 8 # 8 1 ^ -8 # 18_446_744_073_709_551_609 1 ^ -1 # 18_446_744_073_709_551_614 1 ^ 0 # 1 1 ^ 1 # 0 1 ^ 8 # 9 X use integer; -1 ^ -8 # 7 -1 ^ -1 # 0 -1 ^ 0 # -1 -1 ^ 1 # -2 -1 ^ 8 # -9 0 ^ -8 # -8 0 ^ -1 # -1 0 ^ 0 # 0 0 ^ 1 # 1 0 ^ 8 # 8 1 ^ -8 # -7 1 ^ -1 # -2 1 ^ 0 # 1 1 ^ 1 # 0 1 ^ 8 # 9 =back =head3 Section 2.1.16: Miscellaneous Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Miscellaneous Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Random Seed =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Floor with Parentheses =for man T}@T{ =for html =for docbook POSIX::floor( ) =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Ceiling with Parentheses =for man T}@T{ =for html =for docbook POSIX::ceil( ) =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Separate Integer & Fraction Parts with Parentheses =for man T}@T{ =for html =for docbook POSIX::modf( ) =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Integer Part =for man T}@T{ =for html =for docbook int =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Random Number =for man T}@T{ =for html =for docbook rand =for man T}@T{ =for html =for docbook Nullary or Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook srand =for man T}@T{ =for html =for docbook Nullary or Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B POSIX::floor( VALUE ) VALUE is numeric value; If operand VALUE contains fractional part, then return next lowest integer, otherwise return VALUE unchanged; Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C must be called with both the preceding C namespace and parentheses around the operand POSIX::floor( 0) # 0 POSIX::floor( 1) # 1 POSIX::floor(-1) # -1 POSIX::floor(1.1) # 1 POSIX::floor(1.5) # 1 POSIX::floor(1.9) # 1 POSIX::floor(-2.2) # -3 POSIX::floor(-2.6) # -3 POSIX::floor(-2.8) # -3 =back =over =item * B POSIX::ceil( VALUE ) VALUE is numeric value; If operand VALUE contains fractional part, then return next highest integer, otherwise return VALUE unchanged; Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C must be called with both the preceding C namespace and parentheses around the operand POSIX::ceil( 0) # 0 POSIX::ceil( 1) # 1 POSIX::ceil(-1) # -1 POSIX::ceil(1.1) # 2 POSIX::ceil(1.5) # 2 POSIX::ceil(1.9) # 2 POSIX::ceil(-2.2) # -2 POSIX::ceil(-2.6) # -2 POSIX::ceil(-2.8) # -2 =back =over =item * B POSIX::modf( VALUE ) VALUE is numeric value; Break apart operand VALUE into integer part and fraction part, return both, fraction part first; Not a Perl built-in operator, it is a Perl subroutine (which happens to provide an interface to the underlying C subroutine of the same name); thus, C must be called with both the preceding C namespace and parentheses around the operand; Returns more than one return value (always two); thus, must be wrapped in square-brackets C<[ ]> and stored in C data structure, then individual parts accessed via thin-arrow C<-E> array dereference and element retrieval POSIX::modf( 0) # 0, 0 POSIX::modf( 1) # 0, 1 POSIX::modf(-1) # 0, -1 POSIX::modf(1.1) # 0.1, 1 POSIX::modf(1.5) # 0.5, 1 POSIX::modf(1.9) # 0.9, 1 POSIX::modf(-2.2) # -0.2, -2 POSIX::modf(-2.6) # -0.6, -2 POSIX::modf(-2.8) # -0.8, -2 X my number_hashref $retvals = [POSIX::modf(-3.141_59)]; # -0.141_59, -3 my number $integer_part = $retvals->[1]; # -3 my number $fraction_part = $retvals->[0]; # -0.141_59 =back =over =item * B int VALUE VALUE is numeric value; Discard fractional component of operand VALUE, return result B B operator may produce unexpected behavior due to floating-point error; you may instead prefer use of the C, C, and C subroutines.> int 0 # 0 int 1 # 1 int -1 # -1 int 1.1 # 1 int 1.5 # 1 int 1.9 # 1 int -2.2 # -2 int -2.6 # -2 int -2.8 # -2 X int (-4.725 / 0.025) # UNEXPECTED BEHAVIOR: -188 due to floating-point error -189 == (-4.725 / 0.025) # UNEXPECTED BEHAVIOR: false, values in memory do not match printf "%.18f\n", (-4.725 / 0.025) # UNEXPECTED BEHAVIOR: -188.999_999_999_999_971_578 due to floating-point error print (-4.725 / 0.025) # EXPECTED BEHAVIOR: -189 due to automatic floating-point epsilon checking POSIX::floor (-4.725 / 0.025) # EXPECTED BEHAVIOR: -189 due to explicitly forcing to next lowest integer =back =over =item * B rand rand VALUE VALUE is numeric value; Returns pseudo-random floating-point number between 0 and operand VALUE, defaults to VALUE of 1 if omitted; Generated pseudo-random number is based on seed value passed to C operator, and C is called automatically if not called explicitly B B operator is not considered to be cryptographically secure pseudo-random number generator (CSPRNG), and should thus not be utilized for cryptography or other security-sensitive purposes.> rand # between 0 and 1 rand 1 # between 0 and 1 rand 10 # between 0 and 10 =back =over =item * B srand srand VALUE VALUE is numeric value; Seed C operator with operand VALUE, defaults to automatically-selected VALUE if omitted; Entropy (randomness) is decreased if called more than once per program; If C is called with a specific seed value followed by one or more calls to C, then you call C with the same seed value followed by C again, you will receive the same value(s) returned by C after both calls to C srand # seed is automatically chosen srand 1 # seed is 1 srand 10 # seed is 10 srand time # seed is number of non-leap seconds since epoch, usually Unix epoch (19700101 AKA 1970.001 AKA January 1st 1970) X srand 23; print to_string(rand), "\n"; # 0.199_281_135_414_825 print to_string(rand), "\n"; # 0.955_482_658_089_267 print to_string(rand), "\n"; # 0.080_619_594_120_559 srand 23; print to_string(rand), "\n"; # 0.199_281_135_414_825 REPEATED print to_string(rand), "\n"; # 0.955_482_658_089_267 REPEATED print to_string(rand), "\n"; # 0.080_619_594_120_559 REPEATED =back =head2 Section 2.2: Text Data & Operators RPerl provides 2 text data types: =over =item * C S< >S< >S< >S< >a single text character; either a letter, number, or special character =item * C S< >S< >S< >S< >one or more text characters; any combination of letters, numbers, and special characters =back RPerl provides 3 delimiters for enclosing text data: =over =item * Single-Quotes C<'I am a single-quoted string literal'> =back =over =item * Double-Quotes C<"I am a double-quoted string literal"> =back =over =item * q Quotes C =back Perl 5 provides several built-in operators designed for use with text data, which can be organized into 7 general categories: =over =item * Editing =item * Case =item * Comparison (Relational & Equality) =item * Search =item * Formatting =item * Base =item * Miscellaneous =back =head3 Section 2.2.1: Character Literals The most memory-efficient text literal is C, which represents exactly zero characters or one character of information. A C 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 C literal has length zero, meaning it represents zero characters of information, then it is called the I<"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 =head3 Section 2.2.2: String Literals Any text data more than 1 character in length must be represented by a C literal, which is comprised of any combination of valid C literal characters (numeric digits, letters, and special ASCII characters). Like the empty character, if a C literal has length zero then it is called the I<"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 =head3 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 I<"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 C<\\> 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 C<"\n"> or C<"\t"> instead. Do not use single-quotes to represent an empty character or empty string, use q-quotes C instead. In normal Perl, single-backslash characters C<\> are used to create special characters called I<"escape sequences">, the most common of which are the well-known newline C<\n> and tab C<\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 C text literal or a C text literal. (Thus, C<"\n"> and C<"\t"> may both be utilized as either a C or C 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 C<\\>, so the string literal C<'\\'> is interpolated to mean only one single-backslash character C<\>. To represent two backslash characters C<\\>, utilize two double-backslash escape sequences in a row C<'\\\\'>; for three backslashes C<\\\> utilize three escape sequences C<'\\\\\\'>, 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 C<\'> escape sequence may be used to include a single-quote character C<'> within a single-quoted text literal. As stated above, RPerl only supports the double-backslash C<\\> escape sequence within single-quotes, so the backslash single-quote C<\'> escape sequence is thus not supported. Use double-quotes C<"'"> or q-quotes C to represent a single-quote C<'> character in an RPerl string literal. Single-quoted text literals must B contain: =over =item * Single-Quote Character: C<'> =item * Single-Backslash Character: C<\> =item * Odd Number Of Consecutive Backslash Characters: C<\\\> C<\\\\\> C<\\\\\\\> =item * No Characters AKA Empty String =back Single-quoted text literals may contain: =over =item * Double-Quote Character: C<"> =item * Right-Curly-Brace Character: C<}> =item * Double-Backslash Characters: C<\\> =item * Even Number Of Consecutive Backslash Characters: C<\\\\> C<\\\\\\> C<\\\\\\\\> =item * Any Other Characters =back '' # 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 =for html I =over =item * I =back =for html '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 =head3 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 C<"\n"> or tab C<"\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 C<$> or I<"at-sign"> C<@> characters inside of a double-quoted string literal. Because RPerl does not support string interpolation, double-quoted string literals must not contain the C<$> or C<@> characters. Double-quoted string literals must not contain any backslash characters, other than those used in newline C<\n> and tab C<\t> escape sequences, and thus can not represent a single-backslash character C<\>; use single-quotes C<'\\'> or q-quotes C double-backslash escape sequences instead. As with single-quotes, in normal Perl the backslash double-quote C<\"> escape sequence may be used to include a double-quote character C<"> within a double-quoted text literal. As stated above, RPerl only supports the newline C<\n> and tab C<\t> escape sequences within double-quotes, so the backslash double-quote C<\"> escape sequence is thus not supported. Use single-quotes C<'"'> or q-quotes C to represent a double-quote C<"> character in an RPerl string literal. Double-quoted text literals must B contain: =over =item * Double-Quote Character: C<"> =item * Dollar-Sign Character: C<$> =item * At-Sign Character: C<@> =item * Extra Backslash Characters (Other Than C<\n> Or C<\t>): C<\> C<\\> C<\\\> C<\r> C<123\456> =item * No Characters AKA Empty String =back Double-quoted text literals B contain 1 or more: =over =item * Newline Character: C<\n> =item * Tab Character: C<\t> =back Double-quoted text literals may contain: =over =item * Single-Quote Character: C<'> =item * Right-Curly-Brace Character: C<}> =item * Any Other Characters =back "" # 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 =for html I =over =item * I and tab C<\t> characters only, not other normal characters.> =item * I "string concatenation" operator to append one string literal to the other. (Please see L for more information about string concatenation.)> =back =for html "\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 =head3 Section 2.2.5: C Quotes Text literals enclosed in I<"q-quotes"> begin with lowercase letter q and left I<"curly-brace"> characters C, and end with the right curly-brace C<}> character. You must use q-quotes to represent empty text C literals, which contain no characters. Curly braces are also known as I<"curly-brackets"> or just I<"braces"> for short. Normal Perl supports q-quoted string literals using delimiters other than curly-braces, as well as I<"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 C and the difference in delimiters. q-quoted text literals must B contain: =over =item * Right-Curly-Brace Character: C<}> =item * Single-Backslash Character: C<\> =item * Odd Number Of Consecutive Backslash Characters: C<\\\> C<\\\\\> C<\\\\\\\> =back q-quoted text literals may contain: =over =item * Single-Quote Character: C<'> =item * Double-Quote Character: C<"> =item * Double-Backslash Characters: C<\\> =item * Even Number Of Consecutive Backslash Characters: C<\\\\> C<\\\\\\> C<\\\\\\\\> =item * No Characters AKA Empty String =item * Any Other Characters =back 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 =for html I =over =item * I =back =for html '' # 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 =head3 Section 2.2.6: Editing Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Editing Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Substring =for man T}@T{ =for html =for docbook substr =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Repeat =for man T}@T{ =for html =for docbook x =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 07 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Concatenate =for man T}@T{ =for html =for docbook . =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 08 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Length =for man T}@T{ =for html =for docbook length =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B substr EXPR, OFFSET substr EXPR, OFFSET, LENGTH substr EXPR, OFFSET, LENGTH, REPLACEMENT EXPR and REPLACEMENT are string values, OFFSET and LENGTH are integer values; When called with 2 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending at end of first operand; When called with 3 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending after third operand LENGTH characters; When called with 4 operands, return substring of first operand EXPR, beginning at second operand OFFSET character and ending after third operand LENGTH characters, and also edit first operand by replacing original substring with fourth operand REPLACEMENT string; In all variants, OFFSET begins at 0; In all variants, if second operand OFFSET is negative then substring begins absolute value of LENGTH characters before end of first operand EXPR; In 3-operand and 4-operand variants, if third operand LENGTH is negative then substring ends absolute value of LENGTH characters before end of first operand EXPR; In 4-operand variant, return value is original substring before replacement occurs, thus you can retrieve a substring and replace it with one operation; In 4-operand variant, length of substring in third operand LENGTH need not equal length of string in fourth operand REPLACEMENT, length of first operand EXPR will be automatically increased or decreased as needed # common usage my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, 2; # $bar = 'c123!?*' my string $bat = substr $foo, 2, 3; # $bat = 'c12' my string $bax = substr $foo, 2, 3, 'd45'; # $foo = 'abd453!?*', $bax = 'c12' X # negative OFFSET my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, -4; # $bar = '3!?*' my string $bat = substr $foo, -4, 3; # $bat = '3!?' my string $bax = substr $foo, -4, 3, 'd45'; # $foo = 'abc12d45*', $bax = '3!?' X # negative LENGTH my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, 2; # $bar = 'c123!?*' my string $bat = substr $foo, 2, -3; # $bat = 'c123' my string $bax = substr $foo, 2, -3, 'd456'; # $foo = 'abd456!?*', $bax = 'c123' X # negative OFFSET and LENGTH my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, -6; # $bar = '123!?*' my string $bat = substr $foo, -6, -2; # $bat = '123!' my string $bax = substr $foo, -6, -2, 'd456'; # $foo = 'abcd456?*', $bax = '123!' X # LENGTH less-than REPLACEMENT length my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, 2; # $bar = 'c123!?*' my string $bat = substr $foo, 2, 3; # $bat = 'c12' my string $bax = substr $foo, 2, 3, 'd456789'; # $foo = 'abd4567893!?*', $bax = 'c12' X # LENGTH greater-than REPLACEMENT length, and empty replacement string my string $foo = 'abc123!?*'; # $foo = 'abc123!?*' my string $bar = substr $foo, 2; # $bar = 'c123!?*' my string $bat = substr $foo, 2, 3; # $bat = 'c12' my string $bax = substr $foo, 2, 3, q{}; # $foo = 'ab3!?*', $bax = 'c12' =back =over =item * B EXPR x COUNT EXPR is string value, COUNT is unsigned_integer (non-negative whole number) value; Return a new string value comprised of string EXPR repeated COUNT times; Analogous to arithmetic multiply operator C<*>; Consecutive repeat C operators may be chained for multiplicative effect 'a' x 0 # '' (empty string) 'a' x 1 # 'a' 'a' x 2 # 'aa' 'a' x 3 # 'aaa' 'a' x 3 x 2 # 'aaaaaa' 'howdy' x 3 # 'howdyhowdyhowdy' =back =over =item * B EXPR1 . EXPR2 EXPR1 and EXPR2 are string values; Return a new string value comprised of string EXPR1 followed by EXPR2; Analogous to arithmetic add operator C<+>; Consecutive concatenate C<.> operators may be chained for additive (cumulative) effect '' . '' # '' (empty string) 'a' . '' # 'a' '' . 'a' # 'a' 'a' . 'a' # 'aa' 'a' . 'a' . 'a' # 'aaa' 'howdy' . 'howdy' . 'howdy' # 'howdyhowdyhowdy' =back =over =item * B length EXPR EXPR is string value; Return number of characters in string EXPR length '' # 0 length 'a' # 1 length 'aa' # 2 length 'aaa' # 3 length 'howdy' # 5 length 'howdyhowdyhowdy' # 15 =back =head3 Section 2.2.7: Case Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Case Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Lowercase =for man T}@T{ =for html =for docbook lc =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Lowercase First Character =for man T}@T{ =for html =for docbook lcfirst =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Uppercase =for man T}@T{ =for html =for docbook uc =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Uppercase First Character =for man T}@T{ =for html =for docbook ucfirst =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B lc EXPR EXPR is string value; Return new string comprised of all characters in string EXPR converted to lowercase format lc '' # '' (empty string) lc 'a' # 'a' lc 'A' # 'a' lc 'aA' # 'aa' lc 'AA' # 'aa' lc 'AAA' # 'aaa' lc 'howdyHowdyHOWDY' # 'howdyhowdyhowdy' =back =over =item * B lcfirst EXPR EXPR is string value; Return new string comprised of first character in string EXPR converted to lowercase format and remaining characters in EXPR unmodified lcfirst '' # '' (empty string) lcfirst 'a' # 'a' lcfirst 'A' # 'a' lcfirst 'aA' # 'aa' lcfirst 'AA' # 'aA' lcfirst 'AAA' # 'aAA' lcfirst 'HOWDYHOWDYHOWDY' # 'hOWDYHOWDYHOWDY' =back =over =item * B uc EXPR EXPR is string value; Return new string comprised of all characters in string EXPR converted to uppercase format uc '' # '' (empty string) uc 'A' # 'A' uc 'a' # 'A' uc 'Aa' # 'AA' uc 'aa' # 'AA' uc 'aaa' # 'AAA' uc 'HOWDYhOWDYhowdy' # 'HOWDYHOWDYHOWDY' =back =over =item * B ucfirst EXPR EXPR is string value; Return new string comprised of first character in string EXPR converted to uppercase format and remaining characters in EXPR unmodified ucfirst '' # '' (empty string) ucfirst 'A' # 'A' ucfirst 'a' # 'A' ucfirst 'Aa' # 'Aa' ucfirst 'aa' # 'Aa' ucfirst 'aaa' # 'Aaa' ucfirst 'howdyhowdyhowdy' # 'Howdyhowdyhowdy' =back =head3 Section 2.2.8: Comparison (Relational & Equality) Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Comparison (Relational & Equality) Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Less-Than =for man T}@T{ =for html =for docbook lt =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Greater-Than =for man T}@T{ =for html =for docbook gt =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Less-Than-Or-Equal =for man T}@T{ =for html =for docbook le =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Greater-Than-Or-Equal =for man T}@T{ =for html =for docbook ge =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 11 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Equal =for man T}@T{ =for html =for docbook eq =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Not Equal =for man T}@T{ =for html =for docbook ne =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Three-Way Comparison =for man T}@T{ =for html =for docbook cmp =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 12 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B EXPR1 lt EXPR2 EXPR1 and EXPR2 are string values; Compare to determine relation of operands, return true if EXPR1 is stringwise less-than EXPR2, otherwise return false '' lt '' # (false) '' lt 'a' # 1 (true) '' lt 'b' # 1 (true) '' lt 'A' # 1 (true) '' lt 'B' # 1 (true) 'a' lt '' # (false) 'a' lt 'a' # (false) 'a' lt 'b' # 1 (true) 'a' lt 'A' # (false) 'a' lt 'B' # (false) 'aa' lt '' # (false) 'aa' lt 'a' # (false) 'aa' lt 'b' # 1 (true) 'aa' lt 'A' # (false) 'aa' lt 'B' # (false) 'b' lt '' # (false) 'b' lt 'a' # (false) 'b' lt 'b' # (false) 'b' lt 'A' # (false) 'b' lt 'B' # (false) 'bb' lt '' # (false) 'bb' lt 'a' # (false) 'bb' lt 'b' # (false) 'bb' lt 'A' # (false) 'bb' lt 'B' # (false) 'A' lt '' # (false) 'A' lt 'a' # 1 (true) 'A' lt 'b' # 1 (true) 'A' lt 'A' # (false) 'A' lt 'B' # 1 (true) 'AA' lt '' # (false) 'AA' lt 'a' # 1 (true) 'AA' lt 'b' # 1 (true) 'AA' lt 'A' # (false) 'AA' lt 'B' # 1 (true) 'B' lt '' # (false) 'B' lt 'a' # 1 (true) 'B' lt 'b' # 1 (true) 'B' lt 'A' # (false) 'B' lt 'B' # (false) 'BB' lt '' # (false) 'BB' lt 'a' # 1 (true) 'BB' lt 'b' # 1 (true) 'BB' lt 'A' # (false) 'BB' lt 'B' # (false) =back =over =item * B EXPR1 gt EXPR2 EXPR1 and EXPR2 are string values; Compare to determine relation of operands, return true if EXPR1 is stringwise greater-than EXPR2, otherwise return false '' gt '' # (false) '' gt 'a' # (false) '' gt 'b' # (false) '' gt 'A' # (false) '' gt 'B' # (false) 'a' gt '' # 1 (true) 'a' gt 'a' # (false) 'a' gt 'b' # (false) 'a' gt 'A' # 1 (true) 'a' gt 'B' # 1 (true) 'aa' gt '' # 1 (true) 'aa' gt 'a' # 1 (true) 'aa' gt 'b' # (false) 'aa' gt 'A' # 1 (true) 'aa' gt 'B' # 1 (true) 'b' gt '' # 1 (true) 'b' gt 'a' # 1 (true) 'b' gt 'b' # (false) 'b' gt 'A' # 1 (true) 'b' gt 'B' # 1 (true) 'bb' gt '' # 1 (true) 'bb' gt 'a' # 1 (true) 'bb' gt 'b' # 1 (true) 'bb' gt 'A' # 1 (true) 'bb' gt 'B' # 1 (true) 'A' gt '' # 1 (true) 'A' gt 'a' # (false) 'A' gt 'b' # (false) 'A' gt 'A' # (false) 'A' gt 'B' # (false) 'AA' gt '' # 1 (true) 'AA' gt 'a' # (false) 'AA' gt 'b' # (false) 'AA' gt 'A' # 1 (true) 'AA' gt 'B' # (false) 'B' gt '' # 1 (true) 'B' gt 'a' # (false) 'B' gt 'b' # (false) 'B' gt 'A' # 1 (true) 'B' gt 'B' # (false) 'BB' gt '' # 1 (true) 'BB' gt 'a' # (false) 'BB' gt 'b' # (false) 'BB' gt 'A' # 1 (true) 'BB' gt 'B' # 1 (true) =back =over =item * B EXPR1 le EXPR2 EXPR1 and EXPR2 are string values; Compare to determine relation of operands, return true if EXPR1 is stringwise less-than or equal to EXPR2, otherwise return false '' le '' # 1 (true) '' le 'a' # 1 (true) '' le 'b' # 1 (true) '' le 'A' # 1 (true) '' le 'B' # 1 (true) 'a' le '' # (false) 'a' le 'a' # 1 (true) 'a' le 'b' # 1 (true) 'a' le 'A' # (false) 'a' le 'B' # (false) 'aa' le '' # (false) 'aa' le 'a' # (false) 'aa' le 'b' # 1 (true) 'aa' le 'A' # (false) 'aa' le 'B' # (false) 'b' le '' # (false) 'b' le 'a' # (false) 'b' le 'b' # 1 (true) 'b' le 'A' # (false) 'b' le 'B' # (false) 'bb' le '' # (false) 'bb' le 'a' # (false) 'bb' le 'b' # (false) 'bb' le 'A' # (false) 'bb' le 'B' # (false) 'A' le '' # (false) 'A' le 'a' # 1 (true) 'A' le 'b' # 1 (true) 'A' le 'A' # 1 (true) 'A' le 'B' # 1 (true) 'AA' le '' # (false) 'AA' le 'a' # 1 (true) 'AA' le 'b' # 1 (true) 'AA' le 'A' # (false) 'AA' le 'B' # 1 (true) 'B' le '' # (false) 'B' le 'a' # 1 (true) 'B' le 'b' # 1 (true) 'B' le 'A' # (false) 'B' le 'B' # 1 (true) 'BB' le '' # (false) 'BB' le 'a' # 1 (true) 'BB' le 'b' # 1 (true) 'BB' le 'A' # (false) 'BB' le 'B' # (false) =back =over =item * B EXPR1 ge EXPR2 EXPR1 and EXPR2 are string values; Compare to determine relation of operands, return true if EXPR1 is stringwise greater-than or equal to EXPR2, otherwise return false '' ge '' # 1 (true) '' ge 'a' # (false) '' ge 'b' # (false) '' ge 'A' # (false) '' ge 'B' # (false) 'a' ge '' # 1 (true) 'a' ge 'a' # 1 (true) 'a' ge 'b' # (false) 'a' ge 'A' # 1 (true) 'a' ge 'B' # 1 (true) 'aa' ge '' # 1 (true) 'aa' ge 'a' # 1 (true) 'aa' ge 'b' # (false) 'aa' ge 'A' # 1 (true) 'aa' ge 'B' # 1 (true) 'b' ge '' # 1 (true) 'b' ge 'a' # 1 (true) 'b' ge 'b' # 1 (true) 'b' ge 'A' # 1 (true) 'b' ge 'B' # 1 (true) 'bb' ge '' # 1 (true) 'bb' ge 'a' # 1 (true) 'bb' ge 'b' # 1 (true) 'bb' ge 'A' # 1 (true) 'bb' ge 'B' # 1 (true) 'A' ge '' # 1 (true) 'A' ge 'a' # (false) 'A' ge 'b' # (false) 'A' ge 'A' # 1 (true) 'A' ge 'B' # (false) 'AA' ge '' # 1 (true) 'AA' ge 'a' # (false) 'AA' ge 'b' # (false) 'AA' ge 'A' # 1 (true) 'AA' ge 'B' # (false) 'B' ge '' # 1 (true) 'B' ge 'a' # (false) 'B' ge 'b' # (false) 'B' ge 'A' # 1 (true) 'B' ge 'B' # 1 (true) 'BB' ge '' # 1 (true) 'BB' ge 'a' # (false) 'BB' ge 'b' # (false) 'BB' ge 'A' # 1 (true) 'BB' ge 'B' # 1 (true) =back =over =item * B EXPR1 eq EXPR2 EXPR1 and EXPR2 are string values; Compare to determine equality of operands, return true if EXPR1 is stringwise equal to EXPR2, otherwise return false '' eq '' # 1 (true) '' eq 'a' # (false) '' eq 'b' # (false) '' eq 'A' # (false) '' eq 'B' # (false) 'a' eq '' # (false) 'a' eq 'a' # 1 (true) 'a' eq 'b' # (false) 'a' eq 'A' # (false) 'a' eq 'B' # (false) 'aa' eq '' # (false) 'aa' eq 'a' # (false) 'aa' eq 'b' # (false) 'aa' eq 'A' # (false) 'aa' eq 'B' # (false) 'b' eq '' # (false) 'b' eq 'a' # (false) 'b' eq 'b' # 1 (true) 'b' eq 'A' # (false) 'b' eq 'B' # (false) 'bb' eq '' # (false) 'bb' eq 'a' # (false) 'bb' eq 'b' # (false) 'bb' eq 'A' # (false) 'bb' eq 'B' # (false) 'A' eq '' # (false) 'A' eq 'a' # (false) 'A' eq 'b' # (false) 'A' eq 'A' # 1 (true) 'A' eq 'B' # (false) 'AA' eq '' # (false) 'AA' eq 'a' # (false) 'AA' eq 'b' # (false) 'AA' eq 'A' # (false) 'AA' eq 'B' # (false) 'B' eq '' # (false) 'B' eq 'a' # (false) 'B' eq 'b' # (false) 'B' eq 'A' # (false) 'B' eq 'B' # 1 (true) 'BB' eq '' # (false) 'BB' eq 'a' # (false) 'BB' eq 'b' # (false) 'BB' eq 'A' # (false) 'BB' eq 'B' # (false) =back =over =item * B EXPR1 ne EXPR2 EXPR1 and EXPR2 are string values; Compare to determine equality of operands, return true if EXPR1 is stringwise not equal to EXPR2, otherwise return false '' ne '' # (false) '' ne 'a' # 1 (true) '' ne 'b' # 1 (true) '' ne 'A' # 1 (true) '' ne 'B' # 1 (true) 'a' ne '' # 1 (true) 'a' ne 'a' # (false) 'a' ne 'b' # 1 (true) 'a' ne 'A' # 1 (true) 'a' ne 'B' # 1 (true) 'aa' ne '' # 1 (true) 'aa' ne 'a' # 1 (true) 'aa' ne 'b' # 1 (true) 'aa' ne 'A' # 1 (true) 'aa' ne 'B' # 1 (true) 'b' ne '' # 1 (true) 'b' ne 'a' # 1 (true) 'b' ne 'b' # (false) 'b' ne 'A' # 1 (true) 'b' ne 'B' # 1 (true) 'bb' ne '' # 1 (true) 'bb' ne 'a' # 1 (true) 'bb' ne 'b' # 1 (true) 'bb' ne 'A' # 1 (true) 'bb' ne 'B' # 1 (true) 'A' ne '' # 1 (true) 'A' ne 'a' # 1 (true) 'A' ne 'b' # 1 (true) 'A' ne 'A' # (false) 'A' ne 'B' # 1 (true) 'AA' ne '' # 1 (true) 'AA' ne 'a' # 1 (true) 'AA' ne 'b' # 1 (true) 'AA' ne 'A' # 1 (true) 'AA' ne 'B' # 1 (true) 'B' ne '' # 1 (true) 'B' ne 'a' # 1 (true) 'B' ne 'b' # 1 (true) 'B' ne 'A' # 1 (true) 'B' ne 'B' # (false) 'BB' ne '' # 1 (true) 'BB' ne 'a' # 1 (true) 'BB' ne 'b' # 1 (true) 'BB' ne 'A' # 1 (true) 'BB' ne 'B' # 1 (true) =back =over =item * B EXPR1 cmp EXPR2 EXPR1 and EXPR2 are string values; Perform three-way comparison of operands; Return -1 if EXPR1 is stringwise less-than EXPR2, return 0 if operands are equal, or return 1 if EXPR1 is greater-than EXPR2 '' cmp '' # 0 (equal) '' cmp 'a' # -1 (less than) '' cmp 'b' # -1 (less than) '' cmp 'A' # -1 (less than) '' cmp 'B' # -1 (less than) 'a' cmp '' # 1 (greater-than) 'a' cmp 'a' # 0 (equal) 'a' cmp 'b' # -1 (less than) 'a' cmp 'A' # 1 (greater-than) 'a' cmp 'B' # 1 (greater-than) 'aa' cmp '' # 1 (greater-than) 'aa' cmp 'a' # 1 (greater-than) 'aa' cmp 'b' # -1 (less than) 'aa' cmp 'A' # 1 (greater-than) 'aa' cmp 'B' # 1 (greater-than) 'b' cmp '' # 1 (greater-than) 'b' cmp 'a' # 1 (greater-than) 'b' cmp 'b' # 0 (equal) 'b' cmp 'A' # 1 (greater-than) 'b' cmp 'B' # 1 (greater-than) 'bb' cmp '' # 1 (greater-than) 'bb' cmp 'a' # 1 (greater-than) 'bb' cmp 'b' # 1 (greater-than) 'bb' cmp 'A' # 1 (greater-than) 'bb' cmp 'B' # 1 (greater-than) 'A' cmp '' # 1 (greater-than) 'A' cmp 'a' # -1 (less than) 'A' cmp 'b' # -1 (less than) 'A' cmp 'A' # 0 (equal) 'A' cmp 'B' # -1 (less than) 'AA' cmp '' # 1 (greater-than) 'AA' cmp 'a' # -1 (less than) 'AA' cmp 'b' # -1 (less than) 'AA' cmp 'A' # 1 (greater-than) 'AA' cmp 'B' # -1 (less than) 'B' cmp '' # 1 (greater-than) 'B' cmp 'a' # -1 (less than) 'B' cmp 'b' # -1 (less than) 'B' cmp 'A' # 1 (greater-than) 'B' cmp 'B' # 0 (equal) 'BB' cmp '' # 1 (greater-than) 'BB' cmp 'a' # -1 (less than) 'BB' cmp 'b' # -1 (less than) 'BB' cmp 'A' # 1 (greater-than) 'BB' cmp 'B' # 1 (greater-than) =back =head3 Section 2.2.9: Search Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Search Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Index =for man T}@T{ =for html =for docbook index =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Reverse Index =for man T}@T{ =for html =for docbook rindex =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B index STR, SUBSTR index STR, SUBSTR, OFFSET STR and SUBSTR are string values; OFFSET is unsigned_integer (non-negative whole number) value; When called with 2 operands, search within first operand STR for second operand SUBSTR, return character count location of first occurrence; When called with 3 operands, search within first operand STR for second operand SUBSTR, beginning at third operand OFFSET, return character count location of first occurrence; In 3-operand variant, if third operand OFFSET is negative then it will default to 0, or if OFFSET is beyond the end of STR then it will default to the end of STR; If SUBSTR is not located within STR, return -1 my string $foo = 'abc123!?*abc'; my integer $bar = index $foo, 'a'; # $bar = 0 $bar = index $foo, 'c12'; # $bar = 2 $bar = index $foo, '3'; # $bar = 5 $bar = index $foo, '*'; # $bar = 8 $bar = index $foo, 'd'; # $bar = -1 my integer $bat = index $foo, 'a', 0; # $bat = 0 $bat = index $foo, 'a', 1; # $bat = 9 $bat = index $foo, 'a', -1; # $bat = 0 $bat = index $foo, 'a', 20; # $bat = -1 =back =over =item * B rindex STR, SUBSTR rindex STR, SUBSTR, OFFSET STR and SUBSTR are string values; OFFSET is unsigned_integer (non-negative whole number) value; When called with 2 operands, search within first operand STR for second operand SUBSTR, return character count location of last occurrence; When called with 3 operands, search within first operand STR for second operand SUBSTR, beginning at third operand OFFSET, return character count location of last occurrence; In 3-operand variant, if third operand OFFSET is negative then it will default to 0, or if OFFSET is beyond the end of STR then it will default to the end of STR; If SUBSTR is not located within STR, return -1 my string $foo = 'abc123!?*abc'; my integer $bar = rindex $foo, 'a'; # $bar = 9 $bar = rindex $foo, 'c12'; # $bar = 2 $bar = rindex $foo, '3'; # $bar = 5 $bar = rindex $foo, '*'; # $bar = 8 $bar = rindex $foo, 'd'; # $bar = -1 my integer $bat = rindex $foo, 'a', 0; # $bat = 9 $bat = rindex $foo, 'a', 1; # $bat = 9 $bat = rindex $foo, 'a', -1; # $bat = 9 $bat = rindex $foo, 'a', 20; # $bat = -1 =back =head3 Section 2.2.10: Formatting Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Formatting Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook String Formatted Print =for man T}@T{ =for html =for docbook sprintf =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Quote Meta =for man T}@T{ =for html =for docbook quotemeta =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B sprintf FORMAT, LIST FORMAT is string value, LIST is one or more mixed-type values separated by commas; Return string value comprised of element(s) from second operand LIST stringified according to conversion convention(s) in first operand FORMAT my integer $foo = 23; my string $bar = sprintf '%d', $foo; # bar = '23' $bar = sprintf 'single: %d', $foo; # bar = 'single: 23' $bar = sprintf 'single: %d; double: %d', $foo, ($foo * 2); # bar = 'single: 23; double: 46' Accepted conversion conventions: =over =item * C<%%> Percent Sign =item * C<%c> Character With The Given Number =item * C<%s> String =item * C<%d> Signed Integer, In Decimal =item * C<%u> Unsigned Integer, In Decimal =item * C<%o> Unsigned Integer, In Octal =item * C<%x> Unsigned Integer, In Hexadecimal =item * C<%e> Floating-Point Number, In Scientific Notation =item * C<%f> Floating-Point Number, In Fixed Decimal Notation =item * C<%g> Floating-Point Number, In %e Or %f Notation =back =back =over =item * B quotemeta EXPR EXPR is string value; Return new string value comprised of operand EXPR with all non-word characters (not letters or number) backslash-escaped quotemeta 'abc123' # 'abc123' quotemeta 'abc123!?*' # 'abc123\!\?\*' quotemeta '!?*' # '\!\?\*' =back =head3 Section 2.2.11: Base Conversion Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Base Conversion Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Chr =for man T}@T{ =for html =for docbook chr =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Hex =for man T}@T{ =for html =for docbook hex =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Oct =for man T}@T{ =for html =for docbook oct =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Ord =for man T}@T{ =for html =for docbook ord =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 10 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B chr EXPR EXPR is unsigned_integer (non-negative whole number) value; Return character with ASCII order of operand EXPR; To reverse, see C operator chr 33 # '!' chr 65 # 'A' chr 97 # 'a' =back =over =item * B hex EXPR EXPR is string value; Return decimal (base 10) integer value of hexadecimal (base 16) string in operand EXPR hex '0x00' # 0 hex '0x33' # 51 hex '0x66' # 102 hex '0x99' # 153 hex '0xAA' # 170 hex '0xCC' # 204 hex '0xFF' # 255 =back =over =item * B oct EXPR EXPR is string value; If operand EXPR starts with '0x', return decimal (base 10) integer value of hexadecimal (base 16) string in EXPR, same as C operator; If operand EXPR starts with '0b', return decimal (base 10) integer value of binary (base 2) string in EXPR; Otherwise, return decimal (base 10) integer value of octal (base 8) string in operand EXPR # hexadecimal to decimal oct '0x00' # 0 oct '0x33' # 51 oct '0x66' # 102 oct '0x99' # 153 oct '0xAA' # 170 oct '0xCC' # 204 oct '0xFF' # 255 X # binary to decimal oct '0b000' # 0 oct '0b001' # 1 oct '0b010' # 2 oct '0b100' # 4 oct '0b110' # 6 oct '0b111' # 7 X # octal to decimal oct '00' # 0 oct '22' # 18 oct '33' # 27 oct '66' # 54 oct '77' # 63 =back =over =item * B ord EXPR EXPR is string or character value; Return integer ASCII order of first character in operand EXPR; To reverse, see C operator ord '!' # 33 chr 'A' # 65 chr 'a' # 97 =back =head3 Section 2.2.12: Miscellaneous Operators =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Miscellaneous Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook Crypt =for man T}@T{ =for html =for docbook crypt =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B crypt PLAINTEXT, SALT PLAINTEXT and SALT are string values; Perform one-way hash to create "encrypted" digest (short string) of first operand PLAINTEXT using second operand SALT as password, return digest; There is no known way to create a C function to reverse text run through C, thus the label "one-way"; This operator is commonly used to secure and check password validity, or compare contents of 2 strings without transmitting the actual string data crypt 'hidden dragon', 'crouching tiger' # crnzcDddLMkLI crypt 'dihydrogen monoxide', 'sodium chloride' # sol48Jyq9nz1. crypt 'irretrievable data', 'throw away key' # thVMMPVOs6g1I =back =begin text =head2 Section 2.3: RPerlE<39>s Phases, Warnings & Errors =end text =begin man =head2 Section 2.3: RPerlE<39>s Phases, Warnings & Errors =end man =begin html =for DEV NOTE: ppod2html does not support E<39> or E, replaced w/ E =head2 Section 2.3: RPerlEs Phases, Warnings & Errors =end html 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 I<"warning"> occurs when something unexpected happens, but RPerl can continue on without being forced to end prematurely. An I<"error"> occurs when something unexpected happens, and RPerl must end immediately. We will collectively refer to both warnings and errors as I<"problems">, and we will refer to both warning messages and error messages as I<"problem messages">. There are 15 RPerl I<"phases">, most of which are (hopefully unsurprisingly) termed as I<"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 B contain problem messages generated by RPerl itself: =over =item * Install, Base Dependencies =item * Install, CPAN Dependencies =item * B =item * B =item * B =item * B =item * B =item * Compile, Parse Phase 0 (Check Perl Syntax) =item * Compile, Parse Phase 1 (Criticize Perl Syntax) =item * B =item * B =item * B =item * B =item * Compile, Subcompile (Generate Binary) =item * B =back =head3 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 I<"dependency"> is one piece of software which another piece of software requires for proper functionality. One software component is thus said to I<"depend"> upon a second software component, without which the first component would not work correctly. A I<"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 I<"base dependency"> is a software component required for RPerl to function, and is differentiated from a I<"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: L 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: =over =item * No Pre-Built Installation Package Available For Specific Dependency =item * Pre-Built Package(s) Cannot Be Installed =item * Pre-Built Package(s) Installed But Not Functioning Properly =item * Other Miscellaneous Operating System Error =item * Other Miscellaneous Hardware Error =back If you encounter any problems during this step, please consult your operating system's documentation or see: L =head3 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 I<"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 I<"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 C<`cpan`> and C<`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: =over =item * PROBLEM: Front-End Application Not Installed (C<`cpan`> or C<`cpanm`>) =for rperl X cpan: command not found cpanm: command not found =for rperl X I command should come bundled with Perl itself, while C<`cpanm`> is part of the separate "cpanminus" software package. In Ubuntu or other Debian-based Linux operating systems, you can use the commands C<`sudo apt-get install perl`> or C<`sudo apt-get install cpanminus`> for installation. In other operating systems, please refer to the applicable documentation or technical support.> =item * PROBLEM: Dependency or Subdependency Not Installed (C<`cpan`> or C<`cpanm`>) =for rperl X Warning: prerequisite Some::Dependency X.YZ not found. =for rperl X I or C<`cpanm Some::Dependency`> to install the missing dependencies. If an error is encountered while installing a non-RPerl distribution from CPAN, such as the fictitious "Some::Dependency" in our example, then you may still be able to use RPerl by forcing the dependency to install regardless of the error by C<`cpan -f -i Some::Dependency`> or C<`cpanm -f Some::Dependency`>. Please consider submitting a bug report to the maintainer(s) of the problematic CPAN distribution.> =item * PROBLEM: Old Dependency or Subdependency Installed (C<`cpan`> or C<`cpanm`>) =for rperl X Warning: prerequisite Some::Dependency X.YZ not found. We have A.BC. =for rperl X I =item * PROBLEM: Dependency Or Subdependency Build Failure (C<`cpan`>) =for rperl X Running make test Make had some problems, won't test Running make install Make had some problems, won't install Failed during this command: SOMEAUTHOR/Some/Dependency-X.YZ.tar.gz: some_step NO -- some_command =for rperl X I forced installation commands as the "Dependency or Subdependency Not Installed" solution above, and please consider submitting a bug report to the appropriate maintainer(s).> =item * PROBLEM: Dependency Or Subdependency Test Failure (C<`cpan`>) =for rperl X Failed X/Y test scripts, X% okay. make: *** [test_dynamic] Error 255 /usr/bin/make test -- NOT OK Running make install make test had returned bad status, won't install without force =for rperl X I forced installation commands as the "Dependency or Subdependency Not Installed" solution above, and please consider submitting a bug report to the appropriate maintainer(s).> =item * PROBLEM: Dependency Or Subdependency Build Or Test Failure (C<`cpanm`>) =for rperl X --> Working on Some::Dependency Fetching http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz ... OK Configuring Some-Dependency-X.YZ ... OK Building and testing Some-Dependency-X.YZ ... FAIL ! Installing Some::Dependency failed. See /home/someuser/.cpanm/work/123.456/build.log for details. Retry with --force to force install it. # Failed test 'use Some::Dependency;' # at /home/someuser/.cpanm/work/123.456/Some-Dependency-X.YZ/inc/Test/SomeTest.pm line 69. # Tried to use 'Some::Dependency'. # Error: Attempt to reload Some/Dependency.pm aborted. # Compilation failed in require at lib/Some/Dependency.pm line 9. # BEGIN failed--compilation aborted at lib/Some/Dependency.pm line 9. # Compilation failed in require at (eval 350) line 2. # BEGIN failed--compilation aborted at (eval 350) line 2. Bailout called. Further testing stopped: failed: Some::Dependency FAILED--Further testing stopped: failed: Some::Dependency make: *** [test_dynamic] Error 255 -> FAIL Installing Some::Dependency failed. See /home/someuser/.cpanm/work/123.456/build.log for details. Retry with --force to force install it. =for rperl X I forced installation commands as the "Dependency or Subdependency Not Installed" solution above, and please consider submitting a bug report to the appropriate maintainer(s).> =item * PROBLEM: Network Connection Failure (C<`cpan`>) =for rperl X Fetching with LWP: http://cpan.strawberryperl.com/authors/01mailrc.txt.gz LWP failed with code[500] message[Can't connect to cpan.strawberryperl.com:80] Warning: no success downloading 'C:\Perl5.XY\cpan\sources\authors\01mailrc.txt.gz.tmpABC'. Giving up on it. =for rperl X I command. If your network connection appears to be functioning, then either you are behind a firewall of some kind which is interfering with your connection to the CPAN server(s), or there is an issue with the CPAN server(s) themselves. If you are behind a corporate or other firewall, ask your network administrator for assistance or try again from a different network. If you are sure your network connection is working and not blocked by a firewall, then try to select a different CPAN mirror server. You can test your network connection via the C<`cpan -p`> command, and you can see a list of the recommended mirror servers (which should hopefully not have issues) via the C<`cpan -P`> command. Then, you can change your CPAN mirror servers by first running the interactive CPAN shell via the C<`perl -MCPAN -e shell`> command, then when you are presented with the C> prompt, enter the C command to re-run configuration and select one of the recommended mirror servers you were shown by the previous C<`cpan -P`> command.> =item * PROBLEM: Network Connection Failure (C<`cpanm`>) =for rperl X Searching Some::Dependency on cpanmetadb ... --> Working on Some::Dependency Fetching http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz -> FAIL Download http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz failed. Retrying ... -> FAIL Download http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz failed. Retrying ... -> FAIL Download http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz failed. Retrying ... -> FAIL Failed to download http://www.cpan.org/authors/id/S/SO/SOMEAUTHOR/Some-Dependency-X.YZ.tar.gz -> FAIL Failed to fetch distribution Some-Dependency-X.YZ =for rperl X I)" solution above. If the network is not an issue, select a new CPAN mirror server via the same C<`cpan -P`> command as the solution above or some other method of your own choosing, then use the C<`cpanm --mirror`> or C<`cpanm --from`> commands to use the newly-selected mirror server.> =back 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: L and L 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. =head3 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: L Common problem messages in this phase may include: =over =item * PROBLEM: RPerl Error, Test Fails =for rperl X 1..X ok 1 - Program or module does FOO with expected error(s): /.../lib/RPerl/Test/TestDir/TestFile_00.pm not ok 2 - Program or module does FOO without errors: /.../lib/RPerl/Test/TestDir/TestFile_01.pm # Failed test 'Program or module does FOO without errors: /.../lib/RPerl/Test/TestDir/TestFile_01.pm' # at t/XX_foo.t line 123. # Looks like you failed 1 test of X. =for rperl X I or C<`cpanm -f RPerl`>.> X =item * PROBLEM: RPerl Warning, Test Does Not Fail =for rperl X t/XX_foo.t ................ 1/? Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 307. Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 321. Use of uninitialized value $diff_line in numeric eq (==) at t/XX_foo.t line 205. t/XX_foo.t ................ 2/? Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 307. Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 321. Use of uninitialized value $diff_line in numeric eq (==) at t/XX_foo.t line 205. t/XX_foo.t ................ 3/? Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 307. Use of uninitialized value in string eq at /.../blib/lib/RPerl/Compiler.pm line 321. Use of uninitialized value $diff_line in numeric eq (==) at t/XX_foo.t line 205. t/XX_foo.t ................ ok All tests successful. Files=YY, Tests=ZZZZ, XXX wallclock secs Result: PASS =for rperl X I command.> X =back =head3 Section 2.3.4: Initialize, Bootstrap Subcompile Each time the RPerl compiler is called, it may utilize a number of its own internal I<"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 I<"bootstrap subcompile"> phase. In common English usage, I<"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 I<"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: =over =item * PROBLEM: Missing C++ Compiler C<`g++`> =for rperl X Running Mkbootstrap for eval_123_4567 () chmod 644 "eval_123_4567.bs" "/usr/bin/perl" "/usr/share/perl/5.XX/ExtUtils/xsubpp" -typemap "/usr/share/perl/5.XX/ExtUtils/typemap" -typemap "/.../lib/typemap.rperl" eval_123_4567.xs > eval_123_4567.xsc && mv eval_123_4567.xsc eval_123_4567.c g++ -D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -xc++ -c -I"/..." -I/.../lib -Ilib -D_REENTRANT -D_GNU_SOURCE -DDEBIAN -fstack-protector -fno-strict-aliasing -pipe -I/usr/local/include -D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64 -Wno-unused-variable -DNO_XSLOCKS -Wno-deprecated -std=c++11 -Wno-reserved-user-defined-literal -Wno-literal-suffix -D__CPP__TYPES -O3 -fomit-frame-pointer -march=native -g -DVERSION=\"0.00\" -DXS_VERSION=\"0.00\" -fPIC "-I/usr/lib/perl/5.XX/CORE" eval_123_4567.c /bin/sh: 1: g++: not found make: *** [eval_123_4567.o] Error 127 A problem was encountered while attempting to compile and install your Inline CPP code. The command that failed was: "make > out.make 2>&1" with error code 2 The build directory was: /.../_Inline/build/eval_123_4567 To debug the problem, cd to the build directory, and inspect the output files. Environment PATH = '/.../script:.:script:bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' at (eval 426) line 3. ...propagated at /.../perl5/lib/perl5/Inline/C.pm line 869. BEGIN failed--compilation aborted at (eval 426) line 3. at /.../lib/RPerl/DataStructure/Array.pm line 21. INIT failed--call queue aborted. =for rperl X I command to set the correct path to your C++ compiler, or if you do not yet have a C++ compiler installed, then the use of the GNU GCC C<`g++`> compiler is strongly recommended. In Ubuntu or other Debian-based Linux operating systems, you can use the command C<`sudo apt-get install g++`> for installation. In other operating systems, please refer to the applicable documentation or technical support.> I> X =item * PROBLEM: Missing RPerl Helper Function File I =for rperl X /.../_Inline/build/eval_123_4567/Filters98765.c:4:44: fatal error: RPerl/HelperFunctions.h: No such file or directory #include // -> NULL =for rperl X I to search for the missing file "HelperFunctions.h".> X =item * PROBLEM: Missing RPerl Types Mode File I =for rperl X In file included from /.../_Inline/build/eval_123_4567/Filters98765.c:4:4: /.../lib/RPerl/HelperFunctions.h:4:44: fatal error: rperltypes_mode.h: No such file or directory #include // for definitions of __PERL__TYPES or __CPP__TYPES =for rperl X I X =back =head3 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: =over =item * PROBLEM: Multiple Copies Of RPerl Installed =for rperl X WARNING WEXRP00: Found multiple `rperl` executables, using first located, `/.../rperl-latest/script/rperl` =for rperl X I Perl software. You should consider uninstalling or disabling your single-user copy of RPerl, which may be achieved by deleting or renaming the "perl5/" directory in a default C installation; you may also want or need to ask your system administrator for assistance. If you are an RPerl system developer and you have purposefully installed multiple copies of RPerl, then just make sure you are using the correct copy at any one time; debugging the wrong copy of software can be extremely frustrating and confusing!> X =item * PROBLEM: Missing RPerl Compiler C<`rperl`> =for rperl X ERROR EEXRP00: Failed to find `rperl` executable, dying Compilation failed in require at /.../rperl-latest/lib/RPerl/CompileUnit/Module/Class.pm line 5. BEGIN failed--compilation aborted at /.../rperl-latest/lib/RPerl/CompileUnit/Module/Class.pm line 5. Compilation failed in require at /.../rperl-latest/lib/RPerl/AfterSubclass.pm line 10. BEGIN failed--compilation aborted at /.../rperl-latest/lib/RPerl/AfterSubclass.pm line 10. =for rperl X I X =back =head3 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 C<`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 C<`rperl -?`> or C<`rperl -v`> instead of a full RPerl compile command. For details about all of RPerl's command-line arguments, please see Appendix B: L Common problem messages in this phase may include: =over =item * PROBLEM: Invalid Command-Line Argument =for rperl X Unknown option: FOO ERROR EAR00: Failure processing command line arguments, dying Option FOO requires an argument ERROR EAR00: Failure processing command-line arguments, dying =for rperl X I to ensure you are utilizing valid arguments. For example, this is good: C<`rperl --CXX=/path/to/compiler my_program.pl`>; while this is bad: C<`rperl --FOO=/path/to/compiler my_program.pl`>; and this is also bad: C<`rperl --CXX= my_program.pl`>.> X =item * PROBLEM: Missing Command-Line Argument, Input Source Code File =for rperl X ERROR EAR01: No RPerl source code input file(s) specified, dying =for rperl X I> X =item * PROBLEM: Invalid Command-Line Argument Value, Input Source Code File Can Not Be Found =for rperl X ERROR EAR02: Specified RPerl source code input file 'FOO' does not exist, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Argument Value, Input Source Code File Can Not Be Read =for rperl X ERROR EAR03: Specified RPerl source code input file 'FOO' is not readable, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Argument Value, Input Source Code File Is A Special File Of Some Kind =for rperl X ERROR EAR04: Specified RPerl source code input file 'FOO' is not a plain file, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Argument Value, Input Source Code File Does Not End With '.pl' Or '.pm' Suffixes =for rperl X ERROR EAR05: Specified RPerl source code input file 'FOO' is not a Perl program ending in '.pl' or module ending in '.pm', dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Argument Value, Mode Category Does Not Exist =for rperl X ERROR EAR06: Unsupported or invalid mode category 'FOO' specified, supported categories are (CXX, arguments, check, compile, dependencies, execute, label, ops, subcompile, types, uncompile), dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Argument Value, Mode Does Not Exist =for rperl X ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'check' specified, supported modes are (OFF, ON, TRACE), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'compile' specified, supported modes are (GENERATE, OFF, PARSE, SAVE, SUBCOMPILE), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'dependencies' specified, supported modes are (OFF, ON), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'execute' specified, supported modes are (OFF, ON), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'label' specified, supported modes are (OFF, ON), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'ops' specified, supported modes are (CPP, PERL), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'subcompile' specified, supported modes are (ARCHIVE, ASSEMBLE, DYNAMIC, OFF, SHARED, STATIC), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'types' specified, supported modes are (CPP, DUAL, PERL), dying ERROR EAR07: Unsupported or invalid mode 'FOO' in mode category 'uncompile' specified, supported modes are (BINARY, INLINE, OFF, SOURCE, SOURCE_BINARY, SOURCE_BINARY_INLINE), dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Multiple Input Files Incorrectly Specified =for rperl X ERROR EAR08: Both labeled & unlabeled RPerl source code input file argument(s) specified, dying =for rperl X I argument label. For example, this is good: C<`rperl --infile=FOO.pl --infile=BAR.pl`>; and this is bad: C<`rperl --infile=FOO.pl BAR.pl`>.> X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Uncompile & Other Flags =for rperl X ERROR EAR09: Incompatible command-line argument flags provided, both --uncompile and --compile, dying ERROR EAR09: Incompatible command-line argument flags provided, both --uncompile and --execute, dying ERROR EAR09: Incompatible command-line argument flags provided, both --uncompile and --test, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible No-Compile & Other Flags =for rperl X ERROR EAR10: Incompatible command-line argument flags provided, both --nocompile and --assemble, dying ERROR EAR10: Incompatible command-line argument flags provided, both --nocompile and --archive, dying ERROR EAR10: Incompatible command-line argument flags provided, both --nocompile and --shared, dying ERROR EAR10: Incompatible command-line argument flags provided, both --nocompile and --static, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Assemble Subcompile & Other Flags =for rperl X ERROR EAR11: Incompatible command-line argument flags provided, both --assemble and --archive, dying ERROR EAR11: Incompatible command-line argument flags provided, both --assemble and --shared, dying ERROR EAR11: Incompatible command-line argument flags provided, both --assemble and --static, dying ERROR EAR11: Incompatible command-line argument flags provided, both --assemble and --execute, dying ERROR EAR11: Incompatible command-line argument flags provided, both --assemble and --test, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Archive Subcompile & Other Flags =for rperl X ERROR EAR12: Incompatible command-line argument flags provided, both --archive and --shared, dying ERROR EAR12: Incompatible command-line argument flags provided, both --archive and --static, dying ERROR EAR12: Incompatible command-line argument flags provided, both --archive and --execute, dying ERROR EAR12: Incompatible command-line argument flags provided, both --archive and --test, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Shared Object Subcompile & Other Flags =for rperl X ERROR EAR13: Incompatible command-line argument flags provided, both --shared and --static, dying ERROR EAR13: Incompatible command-line argument flags provided, both --shared and --execute, dying ERROR EAR13: Incompatible command-line argument flags provided, both --shared and --test, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Static Subcompile & Test Flags =for rperl X ERROR EAR14: Incompatible command-line argument flags provided, both --static and --test, dying =for rperl X I X =item * PROBLEM: Invalid Command-Line Arguments, Incompatible Static Subcompile Flag & Perl Module Input File =for rperl X ERROR EAR15: Incompatible command-line arguments provided, both --static subcompile mode flag and *.pm Perl module input file(s), dying =for rperl X I X =item * PROBLEM: Missing Command-Line Argument Value, C++ Compiler =for rperl X ERROR EAR16: Undefined, empty, or all-whitespace CXX command-line argument provided, dying =for rperl X I option. For example, this is good: C<`rperl --CXX=/path/to/compiler`>; and this is bad: C<`rperl --CXX=' '`>.> X =item * PROBLEM: Invalid Command-Line Argument Value, Bad Output File Name =for rperl X ERROR EAR17: Invalid RPerl source code output file command-line argument specified, dying =for rperl X I characters. For example, this is good: C<`rperl --outfile=foo`>; and this is bad: C<`rperl --outfile=foo.exe`>. If Perl detects your operating system as Microsoft Windows, then RPerl will automatically append a '.exe' file name suffix to all output executables.> X =item * PROBLEM: Invalid Command-Line Argument Value, Bad Compile Or Subcompile Modes =for rperl X ERROR EAR18: Invalid compile mode 'FOO' and/or subcompile mode 'BAR' command-line arguments specified, dying =for rperl X I X =item * PROBLEM: Uncompile, Compiled Source Code File Can Not Be Deleted =for rperl X ERROR EUNFI00, UNCOMPILER, FILE SYSTEM: Cannot delete existing file 'FOO', dying: OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: Uncompile, Compiled Inline Directory Or File Can Not Be Deleted =for rperl X ERROR EUNFI01, UNCOMPILER, FILE SYSTEM: Cannot delete folder '_Inline', general error, dying: OPERATING_SYSTEM_ERROR ERROR EUNFI01, UNCOMPILER, FILE SYSTEM: Cannot delete folder '_Inline', error deleting file 'FOO', dying: OPERATING_SYSTEM_ERROR =for rperl X I X =back =head3 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 I<"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 C 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 C<--nodependencies> or C<--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: =over =item * PROBLEM: Invalid Dependency, Source Code File Can Not Be Found, Detailed Warning =for rperl X WARNING WCOCODE00, COMPILER, FIND DEPENDENCIES: Failed to eval-use package 'Bad::Dependency' ... Can't locate Bad/Dependency.pm in @INC (you may need to install the Bad::Dependency module) (@INC contains: blib/lib lib /etc/perl /usr/lib/perl5 /usr/share/perl5 /usr/local/lib/site_perl .) at (eval 1234) line 1, <> line 15. BEGIN failed--compilation aborted at (eval 1234) line 1, <> line 15. =for rperl X I operators and the corresponding RPerl module file names. The RPerl source code C will cause Perl (and RPerl) to search for the file 'Dependency.pm' located in the directory 'Some', which would be written in *nix operating systems as 'Some/Dependency.pm'. May be accompanied by the "Invalid Dependency, Source Code File Can Not Be Found" (ERROR ECOCODE03) problem message.> X =item * PROBLEM: Can't Perform Dependency Check, Input Source Code File Can Not Be Found =for rperl X ERROR ECOCODE00, COMPILER, FIND DEPENDENCIES: File not found, 'FOO', dying =for rperl X I found the source code input file, but then the dependency checker in the C module failed to find the same input file. Instead, you should see the error described by "Invalid Command-Line Argument Value, Input Source Code File Can Not Be Found" (ERROR EAR02) in section 2.3.6 above.> X =item * PROBLEM: Can't Perform Dependency Check, Input Source Code File Can Not Be Opened =for rperl X ERROR ECOCODE01, COMPILER, FIND DEPENDENCIES: Cannot open file 'FOO' for reading, OPERATING_SYSTEM_ERROR, dying =for rperl X I opened the source code input file, but then the dependency checker in the C module failed to open the same input file. Instead, you should see the error described by "Invalid Command-Line Argument Value, Input Source Code File Can Not Be Read" (ERROR EAR03) in section 2.3.6 above.> X =item * PROBLEM: Invalid Dependency Configuration, Attempted C Operator =for rperl X ERROR ECOCODE02, COMPILER, FIND DEPENDENCIES: 'use lib...' not currently supported, please set @INC using the PERL5LIB environment variable, file 'FOO', dying =for rperl X I include path list by utilizing the C operator; instead, add or modify the paths in the C environmental variable. In *nix operating systems, you can add '/some/new/path' by running the command C<`export PERL5LIB=$PERL5LIB:/some/new/path`>. Perl (and RPerl) will search each directory in the path list when attempting to locate a dependency's source code file.> X =item * PROBLEM: Invalid Dependency, Source Code File Can Not Be Found =for rperl X ERROR ECOCODE03, COMPILER, FIND DEPENDENCIES: Failed to find package file 'Bad/Dependency.pm' in %INC, file 'FOO', dying =for rperl X I operators and the corresponding RPerl module file names, using the same process as the "Invalid Dependency, Source Code File Can Not Be Found, Detailed Warning" (WARNING WCOCODE00) solution above. May be accompanied by the WARNING WCOCODE00 problem message.> X =item * PROBLEM: Can't Perform Dependency Check, Input Source Code File Can Not Be Closed =for rperl X ERROR ECOCODE05, COMPILER, FIND DEPENDENCIES: Cannot close file 'FOO' after reading, OPERATING_SYSTEM_ERROR, dying =for rperl X I module successfully opened the input file for reading, but then failed to close the same input file when done. It may also be possible that something else in your operating system has deleted, renamed, or moved your input files, or changed the permissions or ownership of your input files.> X =item * PROBLEM: Invalid Dependency, SSE Not Supported By ARM Hardware =for rperl X ERROR ECOCODE06, COMPILER, FIND DEPENDENCIES: 'use rperlsse;' command found but SSE not supported on ARM architecture, file 'FOO', dying =for rperl X I> X =back =head3 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 I<"parse"> means to read through some structured data input such as human-readable plain-text source code, and a I<"full parse"> results in the computer storing some I<"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 I<"strictures"> enabled, as well as all warnings enabled and set to I<"fatal">, via the C<`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 C 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: =over =item * Official Perl Documentation, L =item * Internet Search Engine, Using Error Message As Search Query =item * Internet Relay Chat (IRC), Server C, Channel C<#perl-help>, L =item * Perl Monks, L =item * Stack Overflow, L =back Common problem messages in this phase may include: =over =item * PROBLEM: Perl Syntax Error =for rperl X ERROR ECOPAPL02, RPERL PARSER, PERL SYNTAX ERROR Failed normal Perl strictures-and-fatal-warnings syntax check with the following information: File Name: FOO Return Value: 2 Error Message(s): syntax error at FOO line 23, near "BAR" FOO had compilation errors. =for rperl X I X =item * PROBLEM: Perl Syntax Warning =for rperl X ERROR ECOPAPL03, RPERL PARSER, PERL SYNTAX WARNING Failed normal Perl strictures-and-fatal-warnings syntax check with the following information: File Name: FOO Warning Message(s): Name "BAR" used only once: possible typo at ./FOO line 23. =for rperl X I X =back =head3 Section 2.3.9: Compile, Parse Phase 1 (Criticize Perl Syntax) =for text This phase of compilation checks the input source code files to make sure they all follow Perl I<"best practices"> as originated in Damian Conway's book B 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. =for html

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 C<## 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: L 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: L 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: L You will also likely want to refer to the list of Perl::Critic policies and the explanations thereof: L Common problem messages in this phase may include: =over =item * PROBLEM: Perl Critic Policy Violation =for rperl X ERROR ECOPAPC02, RPERL PARSER, PERL CRITIC VIOLATION Failed Perl::Critic brutal review with the following information: File Name: FOO Line number: 23 Policy: Perl::Critic::Policy::Bar Description: Bar policy violated with extreme prejudice Explanation: See Perl Best Practices page(s) 321 =for rperl X I X =back =head3 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: L Technical support for commercial RPerl users is provided by APTech, as detailed here: L Free technical support for non-commercial users is provided by the RPerl community, as detailed here: L Common problem messages in this phase may include: =over =item * PROBLEM: RPerl Syntax Error =for rperl X ERROR ECOPARP00, RPERL PARSER, RPERL SYNTAX ERROR Failed RPerl grammar syntax check with the following information: File Name: FOO Line Number: 23 Unexpected Token: BAR Expected Token(s): %{ ) ; @{ CONSTANT_CALL_SCOPED LBRACE LBRACKET LITERAL_NUMBER LITERAL_STRING LPAREN OP01_CLOSE OP01_NAMED OP01_OPEN ... SELF VARIABLE_SYMBOL WORD WORD_SCOPED WORD_UPPERCASE ] undef } =for rperl X I X =item * PROBLEM: RPerl Syntax Error With Helpful Hint =for rperl X ERROR ECOPARP00, RPERL PARSER, RPERL SYNTAX ERROR Failed RPerl grammar syntax check with the following information: File Name: FOO Line Number: 23 Unexpected Token: 0 Expected Token(s): OP01_CLOSE OP01_NAMED OP01_NAMED_VOID OP01_OPEN OP01_PRINT OP07_MATH_MULT_DIV_MOD OP07_STRING_REPEAT OP08_MATH_ADD_SUB OP10_NAMED_UNARY OP11_COMPARE_LT_GT OP12_COMPARE_EQ_NE OP19_LOOP_CONTROL OP19_LOOP_CONTROL_SCOLON OP22_LOGICAL_NEG OP23_LOGICAL_AND OP24_LOGICAL_OR_XOR WORD Helpful Hint: Possible case of PBP RequireNumberSeparators (see below) Policy: Perl::Critic::Policy::ValuesAndExpressions::RequireNumberSeparators Description: Long number not separated with underscores Explanation: See Perl Best Practices page(s) 59 =for rperl X I X =back =head3 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 I<"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 I<"operation tree"> (AKA I<"optree">) or other languages' I<"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 I<"decompiling"> or I<"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 I<"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 I<"translate"> process. When computer language translation is utilized as part of a compiler, the software is called a I<"transpiler"> or "translating compiler". RPerl is a transpiler. =begin comment START HERE: update error messages under development START HERE: update error messages under development START HERE: update error messages under development Common problem messages in this phase may include: =over =item * PROBLEM: Attempt To Use Incomplete RPerl Feature =for rperl X WARNING WCOGEDI00, RPERL GENERATOR, DIFF CHECK: Dummy source code found, attempt to utilize incomplete RPerl feature, abandoning check =for rperl X I X =item * PROBLEM: Invalid Difference Check, Input Source Code File Can Not Be Found =for rperl X ERROR ECOGEDI00, RPERL GENERATOR, DIFF CHECK: File not found, 'FOO', dying =for rperl X I X =item * PROBLEM: Invalid Difference Check, Input Source Code File Can Not Be Read =for rperl X ERROR ECOGEDI01, RPERL GENERATOR, DIFF CHECK: Cannot open file 'FOO' for reading, OPERATING_SYSTEM_ERROR, dying =for rperl X I X =item * PROBLEM: Can't Perform Difference Check, Source Code File Can Not Be Closed =for rperl X ERROR ECOGEDI02, RPERL GENERATOR, DIFF CHECK: Cannot close file 'FOO' after reading, OPERATING_SYSTEM_ERROR, dying =for rperl X I X =item * PROBLEM: Can't Perform Difference Check, Perl::Tidy Major Failure In Pre-Existing Source Code File =for rperl X ERROR ECOGEDI03: Perl::Tidy major failure in file 'FOO' with the following STDERR output, dying PERLTIDY_ERROR =for rperl X I X =item * PROBLEM: Can't Perform Difference Check, Perl::Tidy Minor Failure In Pre-Existing Source Code File =for rperl X ERROR ECOGEDI04: Perl::Tidy minor failure in file 'FOO' with the following STDERR output, dying PERLTIDY_ERROR =for rperl X I X =item * PROBLEM: Can't Perform Difference Check, Perl::Tidy Major Failure In Generated Source Code String =for rperl X ERROR ECOGEDI05: Perl::Tidy major failure in generated source code string with the following STDERR output, dying PERLTIDY_ERROR =for rperl X I X =item * PROBLEM: Can't Perform Difference Check, Perl::Tidy Minor Failure In Generated Source Code String =for rperl X ERROR ECOGEDI06: Perl::Tidy minor failure in generated source code string with the following STDERR output, dying PERLTIDY_ERROR =for rperl X I X =item * PROBLEM: Invalid Data Types Mode, No Mode Specified, Perl Operations Mode =for rperl X ERROR ECOGEMO00, RPERL GENERATOR, RPERL TYPES MODE: 'PERL' types mode expected in PERL ops mode, but undefined/null value found, dying =for rperl X I X =item * PROBLEM: Invalid Data Types Mode, Bad Mode Specified, Perl Operations Mode =for rperl X ERROR ECOGEMO01, RPERL GENERATOR, RPERL TYPES MODE: 'PERL' types mode expected in PERL ops mode, but non-matching value 'FOO' found, dying =for rperl X I X =item * PROBLEM: Invalid Data Types Mode, No Mode Specified, C++ Operations Mode =for rperl X ERROR ECOGEMO02, C++ GENERATOR, RPERL TYPES MODE: 'PERL' or 'CPP' types mode expected in CPP ops mode, but undefined/null value found, dying =for rperl X I X =item * PROBLEM: Invalid Data Types Mode, Bad Mode Specified, C++ Operations Mode =for rperl X ERROR ECOGEMO03, C++ GENERATOR, RPERL TYPES MODE: 'PERL' or 'CPP' types mode expected in CPP ops mode, but non-matching value 'FOO' found, dying =for rperl X I X =item * PROBLEM: Internal RPerl System Error, Source Group Type Mismatch =for rperl X ERROR ECOGE00, GENERATOR: Source group entries type mismatch, 'FOO' is different than 'BAR', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGE01, GENERATOR: Grammar rules map, failed to create pre-mapped namespace, dying' . "\n" . $EVAL_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGE02, GENERATOR: Grammar rules map, failed copy subroutines into mapped namespace, dying' . "\n" . $EVAL_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGENG00, GENERATOR: Attempt to generate output source code from non-generating class ' . ::class($self) . ', croaking =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP000, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Grammar rule ' . ($self_class) . ' found where Module_25 or Class_76 expected, dying ERROR ECOGEASCP000, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Grammar rule ' . ( ref $self ) . ' found where TypeInnerProperties_245 or TypeInnerProperties_246 expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP001, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named void operator '} . $operator_void_name . q{' found where } . ( join ', ', ( sort keys %{$NAMES} ) ) . ' expected, dying ERROR ECOGEASCP001, CODE GENERATOR, ABSTRACT SYNTAX TO C++: unsupported or unrecognized named void operator '} . $operator_void_name . q{' found where } . ( join ', ', ( sort keys %{$NAMES} ) ) . ' expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP002, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL:' . "\n" . 'Argument count ' . $argument_count . ' falls below minimum argument limit ' . ARGUMENTS_MIN() . ' for operation ' . q{'} . NAME() . q{'} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP003, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL:' . "\n" . 'Argument count ' . $argument_count . ' exceeds maximum argument limit ' . ARGUMENTS_MAX() . ' for operation ' . q{'} . NAME() . q{'} . ', dying ERROR ECOGEASCP003, CODE GENERATOR, ABSTRACT SYNTAX TO C++:' . "\n" . 'Argument count ' . $argument_count . ' exceeds maximum argument limit ' . ARGUMENTS_MAX() . ' for operator ' . q{'} . NAME_PERLOPS_PERLTYPES() . q{'} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP004, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL:' . "\n" . 'Attempt to return dereferenced array, please return arrayref instead, dying ERROR ECOGEASCP004, CODE GENERATOR, ABSTRACT SYNTAX TO C++:' . "\n" . 'Attempt to return dereferenced array, please return arrayref instead, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP005, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL:' . "\n" . 'Attempt to return dereferenced hash, please return hashref instead, dying ERROR ECOGEASCP005, CODE GENERATOR, ABSTRACT SYNTAX TO C++:' . "\n" . 'Attempt to return dereferenced hash, please return hashref instead, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP006, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL, VARIABLE-CHECKING MISMATCH: C-style for() loop header, initial-condition variable ' . q{'} . $variable_symbol0 . q{'} . ' is different than exit-condition variable ' . q{'} . $variable_symbol1 . q{'} . ', dying ERROR ECOGEASCP006, CODE GENERATOR, ABSTRACT SYNTAX TO C++, VARIABLE-CHECKING MISMATCH: C-style for() loop header, initial-condition variable ' . q{'} . $variable_symbol0 . q{'} . ' is different than exit-condition variable ' . q{'} . $variable_symbol1 . q{'} . ' , dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP007, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: package name ' . ($package_name) . ' must not start with underscore, dying ERROR ECOGEASCP007, CODE GENERATOR, ABSTRACT SYNTAX TO C++: package name ' . ($package_name) . ' must not start with underscore, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP008, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: subroutine name ' . ($name) . ' must not start with underscore, dying ERROR ECOGEASCP008, CODE GENERATOR, ABSTRACT SYNTAX TO C++: subroutine name ' . ($name) . ' must not start with underscore, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP009, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: method name ' . ($name) . ' must not start with underscore, dying ERROR ECOGEASCP009, CODE GENERATOR, ABSTRACT SYNTAX TO C++: method name ' . ($name) . ' must not start with underscore, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP010, CODE GENERATOR, ABSTRACT SYNTAX TO C++: OO property ' . $property_key . ' already declared in this scope, namespace ' . $modes->{_symbol_table}->{_namespace} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP012, CODE GENERATOR, ABSTRACT SYNTAX TO C++: variable ' . $variable_symbol . ' already declared in this scope, namespace ' . $modes->{_symbol_table}->{_namespace} . ', subroutine/method ' . $modes->{_symbol_table}->{_subroutine} . '(), dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP871, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Array dereference of array reference must provide data type for array reference in CPPOPS_CPPTYPES mode, but no data type provided, dying =for rperl X I X =item * PROBLEM: Internal RPerl System Error, BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP013, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named operator '} . $operator_name . q{' found where } . ( join ', ', ( sort keys %{$NAMES} ) ) . ' expected, operator may not be properly listed in $RPerl::Operation::Expression::Operator::Named::NAMES, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP014, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Named operator ' . $operator_named->{children}->[1] . ' does not accept multiple arguments, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP015, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Named operator ' . $operator_named->{children}->[0] . ' does not accept arguments, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP016, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Named operator 'FOO' requires exactly one argument, dying ERROR ECOGEASCP016, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Named operator 'FOO' requires exactly one argument, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP017, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Named operator ' . $operator_named->{children}->[0] . ' requires one or more arguments, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP018, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Named operator ' . $operator_named->{children}->[0] . ' requires multiple arguments, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP019, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: unsupported or unrecognized named operator '} . $operator_name . q{' found where } . ( join ', ', ( sort keys %{$NAMES} ) ) . ' expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP020, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL, TYPE-CHECKING MISMATCH: ' . q{'} . $type . q{'} . ' type is different than ' . q{'} . $constructor_type . q{'} . ' constructor type, dying ERROR ECOGEASCP020, CODE GENERATOR, ABSTRACT SYNTAX TO C++, TYPE-CHECKING MISMATCH: ' . q{'} . $type . q{'} . ' type is different than ' . q{'} . $constructor_type . q{'} . ' constructor type, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP021, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL, NAME-CHECKING MISMATCH: redundant inner type name ' . q{'} . $property_name . q{'} . ' does not equal OO properties key ' . q{'} . $property_key . q{'} . ', dying ERROR ECOGEASCP021, CODE GENERATOR, ABSTRACT SYNTAX TO C++, NAME-CHECKING MISMATCH: redundant inner type name ' . q{'} . $property_name . q{'} . ' does not equal OO properties key ' . q{'} . $property_key . q{'} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP022, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL, NAME-CHECKING MISMATCH: redundant inner type name ' . q{'} . $type_inner_name . q{'} . ' does not end with OO properties or hash key ' . q{'} . $key_name . q{'} . ', dying ERROR ECOGEASCP022, CODE GENERATOR, ABSTRACT SYNTAX TO C++, NAME-CHECKING MISMATCH: redundant inner type name ' . q{'} . $type_inner_name . q{'} . ' does not end with OO properties or hash key ' . q{'} . $key_name . q{'} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP023, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: invalid hash key ' . q{'} . $key_name . q{'} . ' does not start with a lowercase letter a-z, dying ERROR ECOGEASCP023, CODE GENERATOR, ABSTRACT SYNTAX TO C++: invalid hash key ' . q{'} . $key_name . q{'} . ' does not start with a lowercase letter a-z, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP024, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: invalid OO properties name (hash key) ' . q{'} . $property_key . q{'} . ' does not start with a lowercase letter a-z, dying ERROR ECOGEASCP024, CODE GENERATOR, ABSTRACT SYNTAX TO C++: invalid OO properties name (hash key) ' . q{'} . $property_key . q{'} . ' does not start with a lowercase letter a-z, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP025, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: invalid redundant name ' . q{'} . $name . q{'} . ' does not start with a lowercase letter a-z, dying ERROR ECOGEASCP025, CODE GENERATOR, ABSTRACT SYNTAX TO C++: invalid redundant name ' . q{'} . $name . q{'} . ' does not start with a lowercase letter a-z, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP026, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: loop control operator ' . $self->{children}->[0] . ' found where next; or last; expected, dying ERROR ECOGEASCP026, CODE GENERATOR, ABSTRACT SYNTAX TO C++: loop control operator ' . $self->{children}->[0] . ' found where next; or last; expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP027, CODE GENERATOR, ABSTRACT SYNTAX TO C++: loop control operator ' . $loop_control . ' found where next, last, or redo expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP028, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: output stream ' . $stdout_stderr_optional->{children}->[0]->{attr} . ' found where {*STDOUT} or {*STDERR} expected, dying ERROR ECOGEASCP028, CODE GENERATOR, ABSTRACT SYNTAX TO C++: output stream ' . $stdout_stderr_optional->{children}->[0]->{attr} . ' found where {*STDOUT} or {*STDERR} expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP029, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: comparison operator ' . $self->{children}->[1] . ' found where ==, !=, <=>, eq, ne, or cmp expected, dying ERROR ECOGEASCP029, CODE GENERATOR, ABSTRACT SYNTAX TO C++: comparison operator ' . $self->{children}->[1] . ' found where ==, !=, <=>, eq, ne, or cmp expected, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP030, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Variable retrieval, can not retrieve data subcomponent from scalar type ' . $types->[$i] . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP031, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Variable retrieval, can not retrieve invalid OO property ' . $number_or_string_literal . ' in user-defined class ' . $types->[$i] . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP032, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Variable retrieval, can not determine OO property name (and thus type) from non-literal subexpression...' . "\n" . $subexpression_generated . "\n" . '...in user-defined class ' . $types->[$i] . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP033, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Variable retrieval, can not use arrayref retrieval on object of user-defined class ' . $types->[$i] . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP034, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: ModuleHeader found without first finding Module for previous ModuleHeader, dying ERROR ECOGEASCP034, CODE GENERATOR, ABSTRACT SYNTAX TO C++, CPPOPS_CPPTYPES: ModuleHeader found without first finding Module for previous ModuleHeader, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASRP035, CODE GENERATOR, ABSTRACT SYNTAX TO RPERL: Module found without first finding ModuleHeader, dying ERROR ECOGEASCP035, CODE GENERATOR, ABSTRACT SYNTAX TO C++, CPPOPS_CPPTYPES: Module found without first finding ModuleHeader, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP040, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Compile-time optimization, loop iterator ' . $variable_symbol . ' declared as non-integer type ' . $modes->{_loop_iterators}->{$variable_symbol} . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP050, CODE GENERATOR, ABSTRACT SYNTAX TO C++: string literal started with single-quote but not terminated with single-quote, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP051, CODE GENERATOR, ABSTRACT SYNTAX TO C++: string literal started with q-left-brace single-quote but not terminated with right-brace, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP060, CODE GENERATOR, ABSTRACT SYNTAX TO C++: first argument missing, constructor for type ' . $type . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP061, CODE GENERATOR, ABSTRACT SYNTAX TO C++: second argument missing, constructor for type ' . $type . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP062, CODE GENERATOR, ABSTRACT SYNTAX TO C++: constructor called for recognized but currently unsupported type ' . $type . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP063, CODE GENERATOR, ABSTRACT SYNTAX TO C++: constructor called for unrecognized type ' . $type . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEASCP870, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Named operator 'FOO' requires ArrayDereference argument, received 'BAR' instead, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOGEPPRP20, CODE GENERATOR, PURE PERL TO RPERL, NAME-CHECKING MISMATCH: redundant inner type name ' . q{'} . $object_property_inner_type_name . q{'} . ' does not equal OO properties key ' . q{'} . $object_property_key . q{'} . ', dying =for rperl X I X =back =end comment =head3 Section 2.3.12: Compile, Save Phase 0 (Final File Modifications) During this phase, a number of changes and updates may be made to the output files. Most of these changes were delayed from previous phases, due to as-yet-incomplete compile-time information. This is the final phase during which RPerl directly generates output source code. =begin comment START HERE: update error messages under development START HERE: update error messages under development START HERE: update error messages under development Common problem messages in this phase may include: =over =item * PROBLEM: FOO_PROBLEM_LABEL =for rperl X ERROR ECOCOFI00, COMPILER, SAVE OUTPUT FILES: Expecting file name for suffix '$suffix_key', but received empty or no value, croaking =for rperl X I X =item * PROBLEM: BAR_PROBLEM_LABEL =for rperl X ERROR ECOCOFI01, COMPILER, SAVE OUTPUT FILES, MODULE TEMPLATE COPY: Received non-empty PMC source, dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI02, COMPILER, SAVE OUTPUT FILES, MODULE TEMPLATE COPY: File not found, ' . q{'} . $module_pmc_filename_manual . q{'} . "\n" . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI03, COMPILER, SAVE OUTPUT FILES, MODULE TEMPLATE COPY: Cannot open file ' . $module_pmc_filename_manual . ' for reading, ' . OPERATING_SYSTEM_ERROR . ', dying =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI04, COMPILER, SAVE OUTPUT FILES, MODULE TEMPLATE COPY: Cannot close file ' . $module_pmc_filename_manual . ' after reading, ' . OPERATING_SYSTEM_ERROR . ', dying =for rperl X I X =back =end comment =head3 Section 2.3.13: Compile, Save Phase 1 (Format & Write Files To Disk) This phase may utilize source code formatting software, including Perl::Tidy for Perl output code as well as the Artistic Style formatter for C++ output code. If an error occurs with one of these third-party code formatters, please review the applicable documentation. After the output files have been formatted, they are saved to your computer's storage, which usually means the output files are written to hard-disk or the equivalent. Please be sure you have free disk space and the proper disk permissions to save files, etc. =begin comment START HERE: update error messages under development START HERE: update error messages under development START HERE: update error messages under development Common problem messages in this phase may include: =over =item * PROBLEM: FOO_PROBLEM_LABEL =for rperl X ERROR ECOCOFI05, COMPILER, SAVE OUTPUT FILES: Expecting source code for suffix '$suffix_key', but received empty or no value, croaking =for rperl X I X =item * PROBLEM: BAR_PROBLEM_LABEL =for rperl X ERROR ECOCOFI06, COMPILER, FILE SYSTEM: Attempting to save new file '$file_name', can not write to file,\ncroaking: OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI07, COMPILER, FILE SYSTEM: Attempting to save new file '$file_name', can not delete existing file,\ncroaking: OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI08, COMPILER, FILE SYSTEM: Attempting to save new file '$file_name', can not open file for writing,\ncroaking: OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI09, COMPILER, FILE SYSTEM: Attempting to save new file '$file_name', can not close file,\ncroaking: OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOFI10, COMPILER, FILE SYSTEM: Cannot delete Artistic Style original file ' . q{'} . $file_name . '.orig' . q{'} . ',' . "\n" . 'croaking:' . OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X WARNING WCOCOFO00, COMPILER, PERL CODE FORMATTING: Perltidy command `perltidy` not found, abandoning formatting =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X WARNING WCOCOFO01, COMPILER, C++ CODE FORMATTING: Artistic Style command `astyle` not found, abandoning formatting =for rperl X I X =back =end comment =head3 Section 2.3.14: Compile, Subcompile (Generate Binary) The final compile phase utilizes your pre-installed C++ compiler software, thus it is termed the subcompile phase. Please be sure you have a subcompiler installed which supports the C++11 standard, such as GNU GCC v4.7 and Clang v3.3, among others. If an error occurs during this phase, please refer to the applicable subcompiler documentation. =begin comment START HERE: update error messages under development START HERE: update error messages under development START HERE: update error messages under development Common problem messages in this phase may include: =over =item * PROBLEM: FOO_PROBLEM_LABEL =for rperl X ERROR ECOCOSU00, COMPILER, SUBCOMPILE: Received incorrect subcompile mode OFF while inside subcompile subroutine, croaking =for rperl X I X =item * PROBLEM: BAR_PROBLEM_LABEL =for rperl X ERROR ECOCOSU01, COMPILER, SUBCOMPILE: Received invalid subcompile mode ' . q{'} . $modes->{subcompile} . q{'} . ' while inside subcompile subroutine, croaking =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOSU02, COMPILER, SUBCOMPILE: Perl source code CORE directory or CORE/perl.h file not found in @INC path listing, croaking =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOSU03, COMPILER, SUBCOMPILE: Cannot delete temporary object file ' . q{'} . $cpp_output_file_name_group->{O} . q{'} . ',' . "\n" . 'croaking:' . OPERATING_SYSTEM_ERROR =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ECOCOSU04, COMPILER, SUBCOMPILE: C++ compiler returned error code,' . "\n" . 'please run again with `rperl -D` command or RPERL_DEBUG=1 environmental variable for error messages if none appear above,' . "\n" . 'croaking =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X WARNING WCOCOSU00, COMPILER, SUBCOMPILE: C++ compiler returned success code but produced output which may indicate an error,' . "\n" . 'please run again with `rperl -D` command or RPERL_DEBUG=1 environmental variable for error messages or other output if none appear above =for rperl X I X =back =end comment =head3 Section 2.3.15: Execute If RPerl has been provided with exactly one file as input, and if that file is an executable Perl program file ending with C<.pl>, then RPerl may optionally execute the program after all previous phases have been completed. If RPerl is utilized in test mode, then the original non-compiled Perl program input file will be executed via the Perl interpreter with RPerl extensions. If RPerl is utilized in normal compile mode, then the compiled Perl program output file will be executed without the Perl interpreter. =begin comment START HERE: update error messages under development START HERE: update error messages under development START HERE: update error messages under development Common problem messages in this phase may include: =over =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EBV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nboolean value expected but undefined/null value found,\ncroaking ERROR EBV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nboolean value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EBV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nboolean value expected but non-boolean value found,\ncroaking ERROR EBV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nboolean value expected but non-boolean value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EUV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nunsigned_integer value expected but undefined/null value found,\ncroaking ERROR EUV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nunsigned_integer value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EUV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nunsigned_integer value expected but non-unsigned_integer value found,\ncroaking ERROR EUV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nunsigned_integer value expected but non-unsigned_integer value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EIV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ninteger value expected but undefined/null value found,\ncroaking ERROR EIV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ninteger value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EIV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ninteger value expected but non-integer value found,\ncroaking ERROR EIV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ninteger value expected but non-integer value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but undefined/null value found,\ncroaking ERROR EMPV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-hashref value found,\ncroaking ERROR EMPV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-hashref value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV02, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-object (blessed hashref) value found,\ncroaking ERROR EMPV02, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-object (blessed hashref) value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV03, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-Math::BigInt-derived object value found,\ncroaking ERROR EMPV03, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-Math::BigInt-derived object value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV04, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-gmp_integer object value found,\ncroaking ERROR EMPV04, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer external wrapper value expected but non-gmp_integer object value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV05, MISSING HASH ENTRY, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped object in hash entry expected at key 'value' but no hash entry exists,\ncroaking ERROR EMPV05, MISSING HASH ENTRY, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped object in hash entry expected at key 'value' but no hash entry exists,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV06, MISSING HASH ENTRY, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped hash entry expected at key 'value' but no hash entry defined,\ncroaking ERROR EMPV06, MISSING HASH ENTRY, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped hash entry expected at key 'value' but no hash entry defined,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV07, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but undefined/null value found,\ncroaking ERROR EMPV07, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV08, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but non-object (blessed hashref) value found,\ncroaking ERROR EMPV08, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but non-object (blessed hashref) value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name); } =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV09, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but non-Math::BigInt::GMP object value found,\ncroaking ERROR EMPV09, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ngmp_integer internal wrapped value expected but non-Math::BigInt::GMP object value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EMPV10, CONSTRUCTOR RETURN VALUE MISMATCH, CPPOPS_CPPTYPES:\nexactly 1 return value expected but %"INTEGER" return value(s) found,\ncroaking", callback_retval_count =for rperl X I X =item * PROBLEM: FOO_PROBLEM_LABEL =for rperl X ERROR ENV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nnumber value expected but undefined/null value found,\ncroaking ERROR ENV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nnumber value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAR_PROBLEM_LABEL =for rperl X ERROR ENV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nnumber value expected but non-number value found,\ncroaking ERROR ENV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nnumber value expected but non-number value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ETV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ncharacter value expected but undefined/null value found,\ncroaking ERROR ETV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ncharacter value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR ETV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ncharacter value expected but non-character value found,\ncroaking ERROR ETV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\ncharacter value expected but non-character value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EPV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nstring value expected but undefined/null value found,\ncroaking ERROR EPV00, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nstring value expected but undefined/null value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X ERROR EPV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nstring value expected but non-string value found,\ncroaking ERROR EPV01, TYPE-CHECKING MISMATCH, CPPOPS_PERLTYPES & CPPOPS_CPPTYPES:\nstring value expected but non-string value found,\nin variable %s from subroutine %s,\ncroaking", variable_name, subroutine_name =for rperl X I X =item * PROBLEM: BAZ_PROBLEM_LABEL =for rperl X =for comment [ START HERE: continue adding data structure errors, then go back and check if additional data type errors needs to be found in *.cpp or *.pm files ] =for comment [ START HERE: continue adding data structure errors, then go back and check if additional data type errors needs to be found in *.cpp or *.pm files ] =for comment [ START HERE: continue adding data structure errors, then go back and check if additional data type errors needs to be found in *.cpp or *.pm files ] BAZ_PROBLEM_MESSAGE =for rperl X I X =back =end comment =head2 Section 2.4: Variables With Scalar Values An RPerl I<"expression"> is any general-purpose language component which either returns a value or is a literal value itself. An RPerl I<"statement"> is any general-purpose language component which performs some action(s). An RPerl I<"named operator"> is any of the 220+ Perl named operators, although RPerl only supports the low-magic forms of each operator. An RPerl I<"operation"> is the equivalent of a single sentence in human language, and may be either an expression followed by a C<;> semicolon punctuation character, or a named operator followed by a semicolon, or a statement. The equal-sign C<=> is the assignment operator, used to set the variable on its left to store the value of the expression on its right. Perl's C keyword is used to declare a new variable, and optionally initialize it to a starting value when combined with the C<=> assignment operator. Normal Perl does not support specific data types, so in Perl one variable named C<$foo> may be initialized with a numeric value, then the same C<$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 I 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 C, along with a built-in operator named C which can be used to test if a variable contains the special C value. RPerl does not support the C value, nor use of the C operator with scalar variables, because C++ does not fully support the concept of undefined values, and RPerl's high-speed components are written using C++. Future versions of RPerl will likely provide a flexible C data type, which will offer the trade-off of higher memory usage in exchange for the ability to use one variable with multiple possible data types. Currently, all RPerl variables must hold exactly one specific data type only. Data types make your code much more readable and much, much faster. Learn to love data types. Now. :-) =head3 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. =for html I =over =item * I =item * I =back =for html You may not choose to utilize an all-uppercase variable name, because RPerl reserves that format for the names of constants; please see L 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: =for html I =over =item * I =item * I =item * I =back =for html The first of these three best practices is for your variable names to be meaningful, so you should never actually choose C<$foo> or C<$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 C<$r> (too short) or C<$rounding_error_from_perl_arithmetic_operators> (too long); instead, how about C<$rounding_error> (just right)? To be fair, there are a number of commonly-accepted single-letter variable names including C<$i> and C<$j> and C<$k> for loop iterators (see L for more information), as well as traditional mathematics variables such as C<$n> (a "number" of items) and C<$x> and C<$y> and C<$z> (Cartesian coordinates). The third and final best practice is for your variable names to be simple, so you should usually choose C<$golden_ratio> instead of C<$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 C<$circumference>, so you probably do not need to utilize the longer name C<$perimeter_length> instead. Try your best to choose good variable names, you will thank yourself for it later. =head3 Section 2.4.2: Boolean Data Type The most efficient data type is C, which is a numeric type which stores a single I<"bit"> (binary digit) of information. A C 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 =head3 Section 2.4.3: Unsigned Integer Data Type The second most efficient numeric data type is C, which stores a single whole (non-decimal) number which must have a value of 0 or greater. An C 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 unsigned_integer $foo = -23; # error in RPerl, compiled (non-test) modes my unsigned_integer $bar = 0; # fine my unsigned_integer $baz = 42_230; # fine my unsigned_integer $bax = 42.1; # error in RPerl, compiled (non-test) modes my unsigned_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 =head3 Section 2.4.4: Integer Data Type The third most efficient data type is C, which stores a single whole (non-decimal) number. An C 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 =head3 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 C 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 C 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 C can be considered a combination of a normal C data type and a special software component known as an I<"object">. (Please see L for more information on objects.) When we declare a new variable of the C 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 C variable and pre-initialize it with a special subroutine called a I<"constructor">, which is achieved by calling Cnew()> in your RPerl source code. The second initialization statement completes the procedure by calling one of the three following GMP initialization subroutines: =over =item * C =item * C =item * C =back The C subroutine sets the variable's value to a default of C<0>. The C and C subroutines set the variable's value to the provided numeric literal value. When you utilize the three example subroutine calls above, you should replace C<$new_gmp_var> with the name of your own C variable which has already been pre-initialized via Cnew()>, and also replace C or C with an actual numeric literal value. In the source code example below, we create three new C variables which are named C<$foo>, C<$bar>, and C<$baz>, and which are initialized to the values of C<0>, C<23>, and C<-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 L for more information. =head3 Section 2.4.6: Number Data Type The C 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 =head3 Section 2.4.7: Character Data Type The C 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 =head3 Section 2.4.8: String Data Type The C 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 =head3 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: =over =item * boolean =item * unsigned_integer =item * integer =item * gmp_integer =item * number =item * character =item * string =back The name and calling convention of each subroutine takes the form C, where C is replaced by the current data type from which you are converting, C is replaced by the future data type to which you wish to convert, and the argument C is replaced by the input data which should have the data type of C. Your C 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 C, 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 C variable named C<$foo> to the output of a C data type, then you simply call C. If you want to store the C return value of this type conversion, then you must utilize a variable of C 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/env 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: =for rperl X have $bar = 723.555_777 have $double_bar = 1_447.111_554 =for rperl X =for html I =over =item * I data type before being passed to C or otherwise displayed or saved.> =back =for html If we do not call the C subroutine before the values of C<$bar> and C<$double_bar> are processed by the C 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: =for rperl X have $bar = 723.555777 have $double_bar = 1447.111554 =for rperl X In most cases, the shorthand subroutine C may be used instead of one of the other C type conversion subroutines. The special C 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 C with C in our example above: print 'have $bar = ', to_string($bar), "\n"; print 'have $double_bar = ', number_to_string($double_bar), "\n"; =for html I =over =item * I data type.> =back =for html If the variable C<$foo> was a C instead of a C, then RPerl would give an C parse error and complain of C. However, since C<$foo> is of the C data type, then it is not checked for proper numeric underscores, and thus we can omit the underscore in the value of C<$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 C subroutine: =over =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =item * C =back 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 =head3 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: =over =item * I<"Scope"> is the region of source code within which a variable may be utilized. =item * I<"Type"> is the kind of data stored in the variable, such as C or C or C. =item * I<"Name"> is how you access the variable, such as C<$foo> or C<$bar>. =item * I<"Value"> is the the data stored in the variable. =back The I<"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 C keyword, globally-scoped variables declared using the C keyword, and state variables declared using the C keyword. (Old Perl 4 programmers also made use of the C keyword, now replaced by C.) 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 C, all variables in RPerl are locally-scoped using the C keyword. RPerl does not currently support C variables. The I<"type"> of a variable is simply the data type which is stored inside the variable, as described in detail throughout the preceeding subsections of L. A variable's type must be set during declaration and may not be altered thereafter. Remember there are 7 scalar data types in RPerl: C, C, C, C, C, C, and C. The I<"name"> of a variable is the word or phrase you type after a dollar-sign C<$> 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 I<"namespace"> of a variable, which is a named group of variables and constants and possibly other things; except where specified in L, all RPerl variables exist outside of any namespace, which is to say that normal RPerl variables do not have a namespace. The I<"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 C, C, C and C. These four subroutines provide the ability to perform I<"introspection"> on RPerl variables, which means your RPerl application can access information about itself, specifically about its own variables. The C subroutine is not used for scalar data types as discussed in this chapter, please see L and L for more information. The following source code example shows a simple C variable named C<$foo> (as usual), which we then pass as an argument to the introspection subroutines and display the results: #!/usr/bin/env 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: =for rperl X have $foo = howdy have type($foo) = string have name($foo) = $foo have scope_type_name_value($foo) = my string $foo = 'howdy'; =for rperl X =head3 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 C<+> operator, followed by the assignment C<=> operator: $foo = $foo + 1; We can shorten this example from two operators to only one by utilizing a I<"binary assignment operator">, in this case the I<"plus-equals"> C<+=> operator: $foo += 1; We can achieve this effect for the four arithmetic operators addition C<+>, subtraction C<->, multiplication C<*>, and division C, as well as the string concatenation C<.> operator. The right-hand side argument is not limited to numeric literals such as C<1> in the above example, any expression can be utilized as long as it is of a compatible data type, as always. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Binary Assignment Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Add Assign =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook += =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 19 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Subtract Assign =for man T}@T{ =for html =for docbook -= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 19 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Multiply Assign =for man T}@T{ =for html =for docbook *= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 19 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Divide Assign =for man T}@T{ =for html =for docbook /= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 19 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook String Concatenate Assign =for man T}@T{ =for html =for docbook .= =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 19 =for man T}@T{ =for html =for docbook Right =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B $VARIABLE += VALUE $VARIABLE is a numeric variable; VALUE is numeric value; Add VALUE to existing $VARIABLE, store result back in $VARIABLE; Also known as the I<"Plus Equal"> operator my integer $foo = 2; print '$foo = ', $foo, "\n"; $foo += 3; print '$foo = ', $foo, "\n"; Running the code example above will produce the following output: =for rperl X $foo = 2 $foo = 5 =for rperl X =back =over =item * B $VARIABLE -= VALUE $VARIABLE is a numeric variable; VALUE is numeric value; Subtract VALUE from existing $VARIABLE, store result back in $VARIABLE; Also known as the I<"Minus Equal"> operator my integer $foo = 5; print '$foo = ', $foo, "\n"; $foo -= 3; print '$foo = ', $foo, "\n"; Running the code example above will produce the following output: =for rperl X $foo = 5 $foo = 2 =for rperl X =back =for comment [ START HERE: need add post-table examples ] =for comment [ START HERE: need add post-table examples ] =for comment [ START HERE: need add post-table examples ] =head3 Section 2.4.12: Auto-Increment & Auto-Decrement Operators =for comment [ START HERE: need add pre-table content ] =for comment [ START HERE: need add pre-table content ] =for comment [ START HERE: need add pre-table content ] 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 C<1>, we can shorten this example even further to eliminate the numeric literal. This is achieved by using the post-increment C<++> operator: $foo++; =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Auto-Increment & Auto-Decrement Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Pre-Increment =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook ++ =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 03 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Post-Increment =for man T}@T{ =for html =for docbook ++ =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Postfix =for man T}@T{ =for html =for docbook 03 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Pre-Decrement =for man T}@T{ =for html =for docbook -- =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 03 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook Post-Decrement =for man T}@T{ =for html =for docbook -- =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Postfix =for man T}@T{ =for html =for docbook 03 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Yes =for text }]}, 1); =for man T} =for html
=for docbook =for comment [ START HERE: need add post-table examples ] =for comment [ START HERE: need add post-table examples ] =for comment [ START HERE: need add post-table examples ] =over =item * B Add 1 to operand, then return incremented value =back ++$i # 0 =head3 Section 2.4.13: C & C Operators =for comment [ START HERE: need add tables ] =for comment [ START HERE: need add tables ] =for comment [ START HERE: need add tables ] Often you will want to remove the special newline character C<"\n"> from the end of a string variable, which can be achieved safely by using the C operator. When you pass some variable as the operand to C, 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 C<$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 C operator has an effect on the value of the C<$foo> variable. When you run this example source code, you should receive the following output: =for rperl X howdy howdy howdyhowdyhowdyhowdy =for rperl X 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 C operator, which is likened to a non-safe variant of C. Obviously, C and C 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 C operator instead of C: 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 C, and then the final 'y' character of C<'howdy'> is deleted on the second call to the C operator. This generates the following output, notice the missing 'y' characters: =for rperl X howdy howdy howdyhowdyhowdhowd =for rperl X =head3 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 C 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 C command. =for comment [ START HERE: need add tables & examples ] =for comment [ START HERE: need add tables & examples ] =for comment [ START HERE: need add tables & examples ] 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 =head2 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 I<"constant data"> or just a I<"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/env 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 C 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 C operator with a hard-coded data value; see L for more information.) In all RPerl source code files which contain constants, we must include the "USER DEFAULT 3" C 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 I<"file handles"> must be all-uppercase; see L 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 C command, followed by the all-uppercase constant name, a fat-arrow (AKA fat-comma) C<=E>, the C command, the desired data type, a variable named C<$TYPED_> with the same all-uppercase name appended, the equal-sign C<=> 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 =head2 Section 2.6: Displaying Output Using The C Operator You will often want to display some text output while your RPerl application is running, and for this we use the C operator: print 'Hello, World!', "\n"; Unsurprisingly, calling C as shown above will display the 13-character global greeting, followed by a special I<"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 I<"line feed">, I<"carriage return">, and pressing the I<"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 C operator by separating them with commas. The above example passes 2 operands to be received by the C operator, first the greeting literal and second the newline character. You may pass as many operands to C 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(); =head3 Section 2.6.1: C & C When you call the C operator, it sends all output to the operating system's default output data stream, which is a special component called I<"standard output"> or just I<"standard out"> for short, written using the C keyword in Perl. You may explicitly specify C for any C operator, although this is not necessary because it is already the default behavior. When specified, the output stream has an asterisk C<*> 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 C<{*STDOUT}>; you should only type a blank space character, and then specify the first operand. Other than that, the C operator works exactly the same both with and without the extra C included. In addition to C, there is a second output data stream provided by your operating system, which is called I<"standard error"> and is written using the C 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 C to send output to C; if you want execution to immediately stop after displaying an error message, then you will need to explicitly add a termination operator such as C or C or C. The operand value of C<1> passed to the C 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 C 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 C<$foo> variable, so your users want to see the value of C<$foo> when the program is finished running. Your code also utilizes the secondary variables named C<$bar>, C<$bat>, and C<$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 C for both normal output to C (by default), as well as diagnostic output to C: #!/usr/bin/env 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 C, or C, or both. Here we see a normal execution of the program with both output streams displayed: =for rperl X $ ./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 =for rperl X Next, we execute the same program again; this time we append C /dev/null> after our program name, which discards all C output by redirecting it to a I<"null"> or empty device. (In the Windows operating system, replace C /dev/null> with C nul>.) This results in only the C output being displayed: =for rperl X $ ./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 =for rperl X Lastly, we run the same program a third time, now with C<2E /dev/null> appended to discard all C output, so we only see C: =for rperl X $ ./my_program.pl 2> /dev/null $foo = 17.450_980_392_156_9 =for rperl X It is easy to simply insert a hash character (AKA octothorpe) C<#> in front of each C operator to comment it out, thereby disabling the diagnostic output but allowing it to be re-enabled again by future developers: #!/usr/bin/env 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 C output, and our program will run faster: =for rperl X $ ./my_program.pl $foo = 17.450_980_392_156_9 =for rperl X =head2 Section 2.7: Program Control Using The C Conditional Statement Often you will want to perform a task, but only if some specific I<"condition"> is met; this is called a I<"conditional statement"> or just I<"conditional"> for short, and is implemented using the C statement in Perl. You may also refer to the C statement as a I<"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 C statement's task is actually performed is determined by the truth value of its condition, which is specified in the loop's I<"header">, contained within parentheses immediately after the C keyword; please review L 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 I<"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; C statements are also commonly referred to as I<"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. =head3 Section 2.7.1: Conditional Chaining With C & C & C So, what if you also want to perform a different task when your C statement's condition is evaluated as false? Then use the C 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 C<$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 C or C statement is appended to an C statement, it is called a I<"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 C<$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/env 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: =for rperl X $heart = 0 $heart = 3 =for rperl X By studying the source code and output above, we can see there are five opportunities for the value of the C<$heart> variable to be incremented via the C<++> operator, but only three of them are actually executed. This is because the truth value of C<$heart E 3> is true while C<$heart> is equal to 0, 1, and 2, but then the truth value of C<$heart E 3> becomes false once the value of C<$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 C<$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 C 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: =for rperl X $heart = 0 $heart = 1 $heart = 2 $heart = 3 $heart = 3 $heart = 3 =for rperl X From this more informative output, we can see the final two C operators are called, but the final two increment C<++> operators are not called, so "$heart = 3" is repeated twice. Each of the five C 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 C> operators are evaluated every time this program runs, even if only three of the five C 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 C 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 C statements to be C 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 C operators because each C keyword must follow immediately after the preceding conditional body. Also, we can't link more than three C 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: =for rperl X $heart = 0 $heart = 1 =for rperl X This time only the first of the three increment C<++> operators was executed, so the value of C<$heart> only increased from 0 to 1. This is because an C statement's condition will automatically default to a truth value of false if any preceding C or C truth values in its conditional chain are evaluated as true. In other words, both C statements in this example were totally skipped or I<"short-circuited"> without even evaluating their less-than C> operators, because the condition of the starting C 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 C statements completely. Can you quickly tell what the output will be for the following example, where we have simply added an C 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 C as does for the C statements in this and the previous example, so our output is unchanged: =for rperl X $heart = 0 $heart = 1 =for rperl X The longest conditional chain allowable by Perl Best Practices is four members long and is comprised of an C statement, followed by two C statements, followed by an C 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 C<$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 L for more information. If your conditions are not all simple equivalence tests via the equals C<==> operator, as in our C<$heart> examples where the conditions include less-than C> operators, then Perl Best Practices directs us to use a C statement instead of any C or C statements at all. However, RPerl does not yet support C, 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 C statements without triggering a Perl Best Practices violation error via Perl::Critic. This is achieved by the inclusion of the special "USER DEFAULT 9" C command, which disables the "ProhibitCascadingIfElse" policy. If we attempt to run this source code without the proper critic command, we will receive an error: =for rperl X $ 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 =for rperl X However, with the proper "USER DEFAULT 9" C command in place, we receive no errors and the same output as before: =for rperl X $heart = 0 $heart = 1 =for rperl X =head3 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 C<++> operator or a single C 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"; } =head3 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 C<$bar> variable outside of the conditional body where it was declared, so we receive an error: =for rperl X 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. =for rperl X If we simply remove the last line where C<$bar> is incorrectly accessed, then our code runs fine: =for rperl X outside conditional, have $foo = 0 inside conditional, have $bar = 2 outside conditional, have $foo = 1 =for rperl X =head2 Section 2.8: Receiving Input From The User & C When you want the users of your software to provide some keyboard input, then you will need to use the C keyword in Perl, which represents the I<"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 C 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 C operator, which will remove the trailing newline character collected by C. When used in Perl, we wrap C with I<"angle-brackets">, which start with the less-than C> character and end with the greater-than C> character. In this context, the less-than and greater-than characters are not used as tests for numeric inequality. Also, when using C in RPerl we must always include the "USER DEFAULT 4" C command, which enables use of C in general. Along with the two output streams C and C, the input stream C 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/env 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 prompt # [[[ OPERATIONS ]]] print 'Please input your first name: '; my string $first_name = ; 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: =for rperl X Please input your first name: Will Hello Will, nice to meet you! =for rperl X 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 = ; 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 C 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: =for rperl X Please input your age in years: 34 You are 34 years old. In one year from now, you will be 35 years old. =for rperl X You may receive input from C as many times as needed: print 'Please input your favorite band or musician: '; my string $favorite_band = ; chomp $favorite_band; print 'Please input your favorite movie: '; my string $favorite_movie = ; chomp $favorite_movie; print 'Please input your favorite TV show: '; my string $favorite_show = ; 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: =for rperl X 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!) =for rperl X =head2 Section 2.9: Program Control Using The C 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 I<"loop statement"> or just a I<"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 C loop statement. Just like an C conditional statement, a C loop has both a header containing only a condition, and a body of operations. There is only one difference between C and C statements: C executes once when the condition is true, and C 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 C<1>, which has a truth value of true. This is called an I<"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 C conditional statement, a C loop's condition may be any truth value, which is usually generated by a numeric comparison operator such as less-than C> and greater-than C> and equals C<==>, or a logical operator such as C and C and C. Also like a conditional statement, a loop's body may include as many operations as needed, on as many lines as needed. =head3 Section 2.9.1: Loop Iterator Variables Many loops use a designated variable called an I<"iterator">, utilized for the sole purpose of keeping track of the current iteration count. Traditionally this variable is named C<$i>, and its value is increased by one via the increment C<++> operator called as the last operation in a loop body. The value of C<$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 C<$i> to start counting at a hard-coded numeric literal value of C<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 C<$i> starts at 0 and uses a less-than C> operator to be compared to a certain maximum iteration value, then your C loop will iterate exactly that many times. When we run the code above, we receive the following output: =for rperl X Hello, World #0! Hello, World #1! Hello, World #2! Hello, World #3! Hello, World #4! =for rperl X If you really want to start C<$i> at 1 instead of 0, then you have to use a less-than-or-equal C=> 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 C<$i> is no longer starting at 0: =for rperl X Hello, World #1! Hello, World #2! Hello, World #3! Hello, World #4! Hello, World #5! =for rperl X In order to have our iterator C<$i> start at 0, and also have our output make sense to a human, we call the addition C<+> operator within parentheses as part of the C operator: my integer $i = 0; while ( $i < 5 ) { print 'Hello, World #', ( $i + 1 ), q{!}, "\n"; $i++; } Now we receive the desired output with C<$i> starting at 0: =for rperl X Hello, World #1! Hello, World #2! Hello, World #3! Hello, World #4! Hello, World #5! =for rperl X =head3 Section 2.9.2: Nested Loops As with the C conditional statements, multiple C 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 C<$i> for the outer-most loop, then iterator C<$j> for the next loop nested within the C<$i> loop, and then iterator C<$k> for the loop nested within the C<$j> loop. If you need more or different iterators, you may choose any variable names which you find appropriate. Also as with C conditional statements, when a variable is declared inside the body of a C 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 C<$i> is declared before the loop, so it may be accessed or modified outside the loop. In the next example, the variable C<$j> is declared within the outer loop, so C<$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 C<$i> loop, the second number is from the middle C<$j> loop, and the last number is from the inner-most C<$k> loop: =for rperl X 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)! =for rperl X =head3 Section 2.9.3: Loop Control Operators C & C Sometimes you need to skip to the next loop iteration immediately, without finishing the current iteration. For this, we use the C 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 C conditional statements with C loop statements. When we run the code above, the C operator at the bottom of the loop's body is reached only when the incremented C<$i> is even, because odd values of C<$i> will cause the modulo C<%> operator to evaluate as a truth value of true, which then calls the C operator: =for rperl X 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 =for rperl X Sometimes you need to exit a loop immediately, without finishing the current iteration; for this, we use the C operator. Let's take the previous example and simply replace the C operator with C 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 C 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 C<$i> is odd and will cause the modulo C<%> operator to evaluate as true, which then immediately calls the C operator: =for rperl X before loop, have current $i = 0 top of loop, have current $i = 0 after loop, have current $i = 1 =for rperl X =head3 Section 2.9.4: Loop Labels & Loop Control Operator C 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 C operator. However, before we use the C 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 C 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 C operator at all. Let's take the previous example again, add the loop label C, and simply replace the C operator with C 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 C operator provides the exact same behavior as C in this case, but that only applies to some C loops and will not always be true. (In the next chapter we will learn about another kind of loop, where C and C never behave the same.) =for rperl X 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 =for rperl X The C 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 C operator does execute the loop's header, which in the case of C is comprised only of checking the loop's condition. The following source code example is comprised of a C loop containing an C 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 C operator inside the loop, because the C operator causes the loop's condition to be checked and the loop stops iterating before C<$i> reaches a value greater-than C<10>. In fact, we could totally delete the C line as well as the entire C conditional statement, and we would still receive the same output: =for rperl X 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 =for rperl X In the following code, we have simply replaced C with C: 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 C conditional statement is never executed because C<$i> never reaches a value higher than 10. Perhaps unsurprisingly, running this code produces a relatively short output: =for rperl X before loop, have current $i = 0 top of loop, have current $i = 0 after loop, have current $i = 1 =for rperl X Of course, we will now replace C with C: 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 C operator does not cause the C loop's header to be executed, so the C<$i E 5> condition is only checked the very first iteration. Therefore, the value of C<$i> continues to increase until it is greater-than C<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: =for rperl X 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 =for rperl X Now we will look at at a simple nested loop example; we have 2 loops with the C 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 C<$j> is less-than C<2>. This is because when the C operator is called without a loop label, then it is applied to most immediate loop, which means C is applied to the inner loop in this case: =for rperl X 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 =for rperl X Now let's take the same nested loops, add loop labels, and replace C with C 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 C operator is being applied to the outer loop instead of the inner loop: =for rperl X 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 =for rperl X If we replace C with C, then we will see the same default behavior as when C is called with no loop label. What do you think will happen if we place C with C or C in these example cases? I will leave it up to you to experiment and find out for yourself! (Hint: C and C will cause two different kinds of infinite loop.) =head3 Section 2.9.5: Combining C & C Sometimes you want to accept multiple lines of user input via C, instead of just one line at a time as in previous examples. To achieve this, we put the call to C inside the loop's condition: #!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] my string $input_strings = q{}; print 'Please input zero or more strings, separated by , ended by on a blank line:', "\n"; while ( my string $input_string = ) { $input_strings .= $input_string; } print "\n"; print 'after loop, have $input_strings = ', "\n", $input_strings, "\n"; As displayed by the first C operator above, the users must press the two-keystroke combination CTRL-D in order to signal the I<"EOF"> or I<"End Of File"> condition, which tells the C loop to stop iterating. Also, we must remember to include the "USER DEFAULT 4" C command, thereby enabling use of C. When we run the code above, we can see all user input has been combined into one variable C<$input_strings> via the string concatenation C<.> operator: =for rperl X Please input zero or more strings, separated by , ended by on a blank line: howdy dowdy doo after loop, have $input_strings = howdy dowdy doo =for rperl X =head2 Section 2.10: Exercises =head3 1. Constant Pi & Calculated Circumference Of A Circle [ 30 mins ] In the same F directory from the chapter 1 exercises, create a new sub-directory named F. In the new sub-directory, create an RPerl program file named F, which contains constant data for the approximate value of pi equal to C<3.141_592_654>. In your program, utilize the C operator and RPerl's data type conversion subroutines to display your hard-coded value of pi. Next, create a variable named C<$radius> with a value of C<12.5>, and a second variable named C<$circumference> which contains the properly-calculated circumference for a circle with the corresponding radius value. Use C and the type conversion subroutines to display all your values: =for rperl X Pi = 3.141_592_654 Radius = 12.5 Circumference = 2 * Pi * Radius = 2 * 3.141_592_654 * 12.5 = 78.539_816_35 =for rperl X Run your new program by issuing the following command at your terminal command prompt: =for rperl X $ rperl -t LearningRPerl/Chapter2/exercise_1-circumference_of_specific_radius.pl =for rperl X I commands, and your program should be at least 13 lines long.> =head3 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 F. (Don't just edit your previous program file without making a copy, or you will not receive full credit.) Use C to prompt the user to enter a custom value for C<$radius>, then use the C keyword to receive one input value into a new variable named C<$radius_string> of C data type. Next, use an RPerl data type conversion subroutine to convert the C data type and store it in the original C<$radius> variable of C data type. As in the previous exercise, end by using the C operator to display all your values: =for rperl X $ 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 =for rperl X I command, and a total of at least 3 or 4 extra lines of code.> =head3 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 F. Using an C and C 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: =for rperl X $ 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 =for rperl X =head3 4. Product Of Two Numbers [ 20 mins ] Write a new RPerl program named F, 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 C to C types again, before passing a numeric value to the C operator. An example execution of this exercise should display: =for rperl X $ 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 =for rperl X =head3 5. String Repetition [ 15 mins ] Create a new program named F, which will prompt the user for one input string followed by one input integer. Your program should then use the string repetition operator C 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: =for rperl X $ 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. =for rperl X =head3 6. Looping Integer Sum [ 35 mins ] Create a program named F, 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 C conditional statement to perform an error check, and call the C operator if the input integer is less-than 0. Then utilize a C loop to compute the actual sum to be displayed as a result. Store your input integer in a variable named C<$n>, and your final result in a variable named C<$sum>, both of the C data type. As with all loop iterators, the C<$i> variable is also an integer. Two possible executions of this exercise follow: =for rperl X $ 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 =for rperl X =head3 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 F. Modify the new program to remove the C 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 C 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 C 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: =for rperl X $ 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 =for rperl X I operator to check for odd input integers; if found, initialize a temporary variable named C<$n_odd> to the value of C<$n>, decrement C<$n> to become even, and add C<$n_odd> to your original C<$sum> result.> X
=head1 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 I<"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 I<"element">. In normal Perl, a variable may contain (represent) an array directly I<"by value">, or indirectly I<"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 I<"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 C<@> as its sigil, and the assigned data is enclosed within parentheses C<( )> characters. When an array is stored by reference, the corresponding variable has a dollar-sign C<$> as its sigil, and the assigned data is enclosed within I<"square-bracket"> C<[ ]> characters, also known as just I<"brackets">. If an array is stored by value and is then passed as input to an operation, it is said the array is I<"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 I<"passed by reference">. =for comment DEV NOTE, CORRELATION #rp401: all POD changes must be made in both RPerl.pm & RPerl/Learning.pm 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 C<_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 I<"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 C<@{ }>. Because all arrays in RPerl are stored by reference, only necessary uses of the dereference syntax are supported by the RPerl compiler. (Please see L & C Operators> for more information on C.) 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 I<"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 C<*_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: =for rperl X $foo = [23, 42, 2_112] =for rperl X RPerl currently supports the following array stringification subroutines, with support for all RPerl array data types coming soon: =over =item * C =item * C =item * C =back =head2 Section 3.1: Lists vs Arrays In Perl, we use the comma C<,> character to separate elements in a C<"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 L 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 Perl, 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 C<[ ]>, then we have a stored-by-reference I<"array literal">, which represents the literal value which may be assigned to an RPerl variable. Likewise, when a list is enclosed within parentheses C<( )> 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 C<( )> 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 C<[ ]>, not parentheses C<( )>.) 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 I<"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 C<[$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 C<[22, 13, 24]> below is an array of literals, because all its elements are literal values themselves. At the same time, the variable C<$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 C<[22, 13, 24]>" should be read as "array literal C<[22, 13, 24]>", because we can see an enclosed list of comma-separated values. The phrase "array C<$frob>" should be read as "array assigned to variable C<$frob>", because we can see a dollar-sign C<$> 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 I<"programming jargon"> or even the mocking I<"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 C<$frob> and C<[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. =head2 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 C<_arrayref>. In the preceeding examples, you have already seen the three most common RPerl array data types, which are C, C, and C. 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 I<"vector">, I<"sequence">, and I<"set">; please see Wikipedia for more information. (For example, in the MathPerl software suite, which is part of the RPerl Family of software, the C data structure is simply a specially-packaged C.) In some cases, it may also be useful to visualize a 1-D array as a single I<"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: =over =item * C =item * C =item * C =item * C Coming Soon =item * C =item * C =item * C =back 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 As mentioned in L, future versions of RPerl will likely provide the C data type and also the C data structure, which will provide the ability to use one array reference to store elements with non-matching data types. Currently, RPerl arrays must store elements which all have the exact same data type as one another. Please see L for more RPerl array data types. =head2 Section 3.3: How To Access Array Elements Please take a few moments to review L at this time. Closely related to the loop concept of an iterator variable is that of an C<"array index">. 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 I<"index"> for short. (Depending upon context or tradition, you may argue the "i" in C<$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 integer value used to specify an array element, and may be either a variable or a hard-coded numeric literal. An iterator can always be used as an index, and often is; however, the reverse is not true.) What a normal person would think of as being the "first" element in an array is actually not at index value of C<1>, but is actually at index C<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 C<1> instead of index C<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"; =for rperl X The first born is Chico The middle child is Groucho =for rperl X In the example above, note the "first born" is located at index value of C<0> (not C<1>), and the "middle child" is at index C<2> (not C<3>). Also, note the thin-arrow-square-brackets C<-E[ ]> syntax for accessing the individual elements. The thin-arrow C<-E> is Perl's I<"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 C<[ ]> 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 C<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 =head2 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 C operator, combined with Perl's closed-fixity at-sign-curly-braces C<@{ }> 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 C operator forces the dereferenced array to be evaluated in I<"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"; =for rperl X have $greetings_length = 3 =for rperl X 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"; =for rperl X have $greeting_final = howdy =for rperl X 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"; =for rperl X Use of uninitialized value $greeting_final in print... have $greeting_final = =for rperl X As you can see in the output above, an attempt to access the C<$greetings> element at index value C<3> results in an C error message, because the highest valid index value is actually C<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 C<-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 C 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"; =for rperl X have $greeting_final = howdy =for rperl X If you want to access each array element in reverse order, simply count downward with indices starting at C<-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"; =for rperl X have $greetings->[-1] = howdy have $greetings->[-2] = hi have $greetings->[-3] = hello =for rperl X =head2 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 I<"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 I<"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 C<[ ]> and the singleton array C<[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: =over =item * C Coming Soon =item * C Coming Soon =item * C =item * C Coming Soon =item * C =item * C Coming Soon =item * C =back 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 I<"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 C<$rows_and_columns_2D> given in this section, then you should receive the following output: =for rperl X have $row_3_column_0_combined = 9 have $row_3 = [9, 8, 7, 6, 5] have $row_3_column_0_separated = 9 =for rperl X 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: =for rperl X have $column_3 = [6, 7, 1, 6, 5] =for rperl X 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 C<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 C<9>, taken from C<$foo_1D> and then C<$foo_2D>, respectively: =for rperl X have 1-D single dereference = 9 have 2-D double dereference = 9 =for rperl X =head2 Section 3.6: Quote Word C 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 I<"quote word"> operator C. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Quote Word C<qw()> Operator =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Quote Word =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook qw( ) =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Closed =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B qw(LIST) LIST is whitespace-separated list of string literals; Split list elements by whitespace, return list of each element as a single-quoted string literal; Shortcut to avoid typing single-quote C<'> and comma C<,> characters in lists of string literals; May be utilized anywhere a list is accepted # the following two lines are equivalent qw(foo bar bat baz quux) 'foo', 'bar', 'bat', 'baz', 'quux' =back Let's return to a source code example from L, which shows a common use of the C 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 C operator. The benefit of using C 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"; =for rperl X 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'] =for rperl X As we can see in the output above, the data stored by the C operator is identical to the data stored by the normal quotes and commas technique, and C requires fewer characters of source code when there are at least 2 string array elements. =head2 Section 3.7: Array Assignment As mentioned in L, normal Perl allows you to perform a special kind of array assignment with multiple variables on the left (receiving) side of the equal-sign C<=> 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; =head2 Section 3.8: C & C Operators Often you will want to append one or more elements to the end of an existing array, and equally often you will want to remove one or more elements from the end of an array. For these use cases, you may choose the C and C operators. (The end of an array is sometimes called the I<"tail"> of the array, and likewise the beginning of an array is sometimes called its I<"head">.) The C operator will add one or more new elements to the end of a dereferenced array, and will return the new array length. The C operator will remove one element from the end of a dereferenced array, and will return the removed element. You may optionally ignore the return value of either operator. Both the C and C operators require array arguments to be dereferenced, which means you must always use the closed-fixity at-sign-curly-braces C<@{ }> array dereference operator for arrays, as demonstrated in the code examples below. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
C<push> & C<pop> Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Push =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook push =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Pop =for man T}@T{ =for html =for docbook pop =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B push ARRAY, LIST ARRAY is dereferenced array; LIST is comma-separated list of expressions; Append elements of LIST after final element of ARRAY; In non-void context, return new ARRAY length, operator and operands must be enclosed in parentheses my integer_arrayref $foo = [17]; push @{$foo}, 21, 12, 23; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; =for rperl X have $foo = [17, 21, 12, 23] =for rperl X my integer_arrayref $frob = []; my integer $frob_length = ( push @{$frob}, 21, 12, 23 ); print 'have $frob = ', integer_arrayref_to_string($frob), "\n"; print 'have $frob_length = ', $frob_length, "\n"; =for rperl X have $frob = [21, 12, 23] have $frob_length = 3 =for rperl X =back =over =item * B pop ARRAY ARRAY is dereferenced array; Remove final element of ARRAY and return my integer_arrayref $foo = [17, 21, 12, 23]; pop @{$foo}; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; =for rperl X have $foo = [17, 21, 12] =for rperl X my integer_arrayref $frob = [21, 12, 23]; my integer $frob_pop = pop @{$frob}; $frob_length = scalar @{$frob}; print 'have $frob_pop = ', $frob_pop, "\n"; print 'have $frob = ', integer_arrayref_to_string($frob), "\n"; print 'have $frob_length = ', $frob_length, "\n"; =for rperl X have $frob_pop = 23 have $frob = [21, 12] have $frob_length = 2 =for rperl X =back =head2 Section 3.9: C & C Operators In the previous section, we saw how to append and remove elements from the end of an array, using C and C. In this section, we will work with the beginning of an array instead of the end, using the C and C operators. The C operator will remove one element from the beginning of a dereferenced array, and will return the removed element, in the same way the C operator works on the end of an array. The C operator will add one or more elements to the beginning of a dereferenced array, and like C will return the new array length. Like the C and C operators, both C and C require array arguments to be dereferenced, so don't forget to use the at-sign-curly-braces C<@{ }> array dereference operator every time. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
C<shift> & C<unshift> Operators =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Shift =for man T}@T{ =for html =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook shift =for man T}@T{ =for html =for docbook Unary =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook Unshift =for man T}@T{ =for html =for docbook unshift =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B shift ARRAY ARRAY is dereferenced array; Remove starting element of ARRAY and return my integer_arrayref $foo = [17, 21, 12, 23]; shift @{$foo}; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; =for rperl X have $foo = [21, 12, 23] =for rperl X my integer_arrayref $frob = [21, 12, 23]; my integer $frob_shift = shift @{$frob}; $frob_length = scalar @{$frob}; print 'have $frob_shift = ', $frob_shift, "\n"; print 'have $frob = ', integer_arrayref_to_string($frob), "\n"; print 'have $frob_length = ', $frob_length, "\n"; =for rperl X have $frob_shift = 21 have $frob = [12, 23] have $frob_length = 2 =for rperl X =back =over =item * B unshift ARRAY, LIST ARRAY is dereferenced array; LIST is comma-separated list of expressions; Append elements of LIST before starting element of ARRAY; In non-void context, return new ARRAY length, operator and operands must be enclosed in parentheses my integer_arrayref $foo = [17]; unshift @{$foo}, 21, 12, 23; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; =for rperl X have $foo = [21, 12, 23, 17] =for rperl X my integer_arrayref $frob = []; my integer $frob_length = ( unshift @{$frob}, 21, 12, 23 ); print 'have $frob = ', integer_arrayref_to_string($frob), "\n"; print 'have $frob_length = ', $frob_length, "\n"; =for rperl X have $frob = [21, 12, 23] have $frob_length = 3 =for rperl X =back =head2 Section 3.10: Range C<..> Operator Often you will want to generate a list of integers increasing by one. For this purpose, the natural choice the range operator C<..>, sometimes called I<"dot-dot">. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
Range C<..> Operator =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Range =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook .. =for man T}@T{ =for html =for docbook Binary =for man T}@T{ =for html =for docbook Infix =for man T}@T{ =for html =for docbook 17 =for man T}@T{ =for html =for docbook Non =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B VALUE1 .. VALUE2 VALUE1 and VALUE2 are numeric values; Return list of integers starting at VALUE1, increasing by 1, and ending at VALUE 2; If VALUE1 is greater than VALUE2, returns empty list; If VALUE1 or VALUE2 is not an integer, only integer part is utilized; May be utilized anywhere a list is accepted # the following two lines are equivalent 1 .. 10 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 =back Remember, if you pass value C<0> as the first argument for the range operator C<..>, whether for use as an array index or loop iterator variable or any other purpose, then you will generate a list of length 1-greater than the operator's second argument. So, a list from C<1> to C<5> has length 5, and a list from C<0> to C<5> has length 6. As an extension of the array-indices-start-at-zero issue, this can be a common mistake or mixup for new programmers. my integer_arrayref $foo = [1 .. 5]; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; print 'have $foo length = ', (scalar @{$foo}), "\n"; =for rperl X have $foo = [1, 2, 3, 4, 5] have $foo length = 5 =for rperl X my integer_arrayref $foo = [0 .. 5]; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; print 'have $foo length = ', (scalar @{$foo}), "\n"; =for rperl X have $foo = [0, 1, 2, 3, 4, 5] have $foo length = 6 =for rperl X my integer_arrayref $foo = [0 .. 5]; push @{$foo}, 21, 12, 23; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; print 'have $foo length = ', (scalar @{$foo}), "\n"; =for rperl X have $foo = [0, 1, 2, 3, 4, 5, 21, 12, 23] have $foo length = 9 =for rperl X my integer_arrayref $foo = [0 .. 5]; push @{$foo}, 20 .. 25; print 'have $foo = ', integer_arrayref_to_string($foo), "\n"; print 'have $foo length = ', (scalar @{$foo}), "\n"; =for rperl X have $foo = [0, 1, 2, 3, 4, 5, 20, 21, 22, 23, 24, 25] have $foo length = 12 =for rperl X =head2 Section 3.11: Converting From Array To String The terms I<"stringify">, I<"stringification">, and I<"pretty print"> refer to type conversion from any non-string data type or data structure into a string data type. As mentioned in this chapter's opening section L, RPerl currently provides the following array stringification subroutines, with support for all RPerl array data types coming soon: =over =item * C =item * C =item * C =back The internals of the C subroutine are implemented by the copied-and-pasted section of RPerl source code below, for Perl operations & Perl data types mode: # change this to hold your own data my integer_arrayref $input_avref = [8, 23, 17]; # [ BEGIN COPIED-AND-PASTED CODE ] # declare local variables, av & sv mean "array value" & "scalar value" as used in Perl core my integer $input_av_length; my integer $input_av_element; my string $output_sv; my boolean $i_is_0 = 1; # compute length of (number of elements in) input array $input_av_length = scalar @{$input_avref}; # begin output string with left-square-bracket, as required for all RPerl arrays $output_sv = '['; # loop through all valid values of $i for use as index to input array for my integer $i ( 0 .. ( $input_av_length - 1 ) ) { # retrieve input array's element at index $i $input_av_element = $input_avref->[$i]; # append comma & space to output string for all elements except index 0 if ($i_is_0) { $i_is_0 = 0; } else { $output_sv .= ', '; } # stringify individual integer element, append to output string $output_sv .= integer_to_string($input_av_element); } # end output string with right-square-bracket, as required for all RPerl arrays $output_sv .= ']'; # [ END COPIED-AND-PASTED CODE ] # display stringified output print $output_sv; In the RPerl system source code above, you will see at least 1 new concept: the usage of a C loop. The input to this source code is an C accessed via the variable C<$input_avref>, and the output generated is a string in the variable C<$output_sv>. (The term "avref" refers to "Array Value Reference", and likewise "sv" refers to "Scalar Value"; these terms are used in the internals of the Perl 5 interpreter itself, and copied in RPerl's internals for consistency.) The C loop is used to access each individual element of the input array, one at a time; each element is then, in turn, stringified and appended to the output string. You will note the C stringification subroutine is called from within the C subroutine, which makes sense because an C data structure is obviously composed of individual C data types. Running the code example above generates the following output string from C<$output_sv>, which is an exact replica of the original RPerl C input data from C<$input_avref>: =for rperl X [8, 23, 17] =for rperl X (Please see L Intermittent Variables> for the full subroutine C.) =head2 Section 3.12: Program Control Using The C & C Loops In the previous section, you saw a C loop control structure used to stringify an array in the C subroutine. In this section, we'll learn more about the C loop and its closely-related counterpart, the C loop. Please take a few minutes to review L Loop> if you have not yet done so; this should prove helpful because the C and C loops share some things in common with the C loop control structure. When compared with the much more loosely-structured C loop, the RPerl compiler may have more opportunities to perform automatic optimizations on C and C loop control structures. Unlike loop iterator variables in a C loop, iterators in a C or C loop should only be modified in the loop header, in order to avoid hard-to-diagnose behavior and also to increase the opportunities for automatic optimization. =for html I =over =item * I or C loop instead of a C loop.> =item * I or C loop, never modify the loop iterator variable inside the loop body, only inside the loop header.> =back =for html In normal Perl, there is no difference whatsoever between the C and C loops; the 2 keywords are synonymous and you may freely interchange them as you like. This follows the Perl philosophy of TIMTOWTDI (There Is More Than One Way To Do It). In RPerl, the C and C loops are used for separate, but related, purposes. This follows the RPerl philosophies of TDNNTBMTOWTDI (There Does Not Need To Be More Than One Way To Do It) and TIOFWTDI (There Is One Fastest Way To Do It). In RPerl, the C loop itself is actually 2 different control structures: the I<"range"> C loop and the I<"C-style"> C loop. The range C loop is so named due to its use of the range operator C<..>, which you may recall from L Operator>. The C-style C loop derives its name from its origins in the foundational programming language I<"C">, which is the language used to build most modern technology such as Linux and Perl and RPerl. (Of course we prefer programming in Perl over C, so that's why we created RPerl in the first place, because RPerl generates the C and C++ code for us!) =head3 Section 3.12.1: The Range C Loop Often you will want your loop iterator variable to simply increase by one each time the loop iterates, starting and ending at some specific values. For this purpose, you may choose the range C loop control structure. for my integer $i ( 1 .. 5 ) { print 'have $i = ', $i, "\n"; } =for rperl X have $i = 1 have $i = 2 have $i = 3 have $i = 4 have $i = 5 =for rperl X Range C loop control structures always take the following form: for my integer $i ( $lower .. $upper ) { # PERFORM OPERATIONS INSIDE LOOP } In the source code example above, C<$i> is the loop iterator variable, which you will hopefully recall from L. By definition, a loop iterator variable must always be a variable, although it may be named something other than C<$i> if you like. The C<$lower> and C<$upper> variables are the two operands to the infix range operator C<..>, and they may be any expression, literal, or variable which produces a numeric value. The number of times this loop will iterate is C<($upper - $lower) + 1>, and each time the loop iterates it will effectively cause the value of C<$i> to increase by one, starting at C<$lower> and ending at C<$upper>. In all range C loops, the iterator variable (C<$i> in this example) is I<"lexically scoped"> by virtue of Perl's C keyword, which means this specific instance of C<$i> is valid within this specific loop header and body only. Any other independent loop(s) within the same Perl program may also utilize an iterator variable with the exact same name C<$i>, but it will be a totally new instance of C<$i>, and thus will not be connected in any way other than the coincidence of sharing an iterator variable name. Also, once you utilize a variable name as a loop iterator, then you must not declare or utilize that same variable name except within other independent loops (as just described), or within a totally different scope such as a different source code file, etc. Failure to do so will result in a C++ compile-time error, as illustrated in the next two source code examples. The following example shows multiple instances of the loop iterator variable C<$i>, without any errors: for my integer $i ( 0 .. 10 ) { # do stuff inside first loop, using $i; fine } # do stuff outside loops, not using $i; fine my integer $x = 100; # fine for my integer $i ( 20 .. 30 ) { # do stuff inside second loop, # using totally independent instance of $i } The following example shows multiple instances of the loop iterator variable C<$i>, with an error: for my integer $i ( 0 .. 10 ) { # do stuff inside first loop, using $i; fine } # do stuff outside loops, using $i; causes error in second loop below my integer $i = 100; # ERROR ECOGEASCP012, CODE GENERATOR, ABSTRACT SYNTAX TO C++: # variable i already declared in this scope, namespace main::, subroutine/method main(), dying for my integer $i ( 20 .. 30 ) { # do stuff inside second loop, # using totally independent instance of $i } We have recently seen the range C loop in L, used inside the C subroutine. Here is the header and first operation of that same range C loop, isolated from the rest of the code: # loop through all valid values of $i for use as index to input array for my integer $i ( 0 .. ( $input_av_length - 1 ) ) { # retrieve input array's element at index $i $input_av_element = $input_avref->[$i]; # PERFORM OPERATIONS USING $input_av_element } In the source code example above, the range operator C<..> begins at C<0> and ends at C<( $input_av_length - 1 )>; remember, array indices start at 0, so we must always be careful to subtract one from the array's length when calculating the range operator's second operand. (If you forget to subtract one from the second operand, then your code will probably attempt to access one element beyond the end of the array, which generally causes errors, crashes, or unexpected behavior.) Inside the loop body, we access the element of array C<$input_avref> located at index C<$i>, and store the element inside the C<$input_av_element> variable for further use in the loop (not shown). This loop will access each and every element of the array, in order, one at a time. =head3 Section 3.12.2: The C-Style C Loop Sometimes you need more control over your loop iterator variable than the range C loop can provide; for this, you may choose the C-style C loop. However, the additional complexity of C-style C loop control structures may result in fewer opportunities for the RPerl compiler to perform automatic optimizations when compared with range C loops. =for html I =over =item * I loop instead of a C-style C loop.> =back =for html In the range C loop, there is one operation in the loop header, which is the range operator C<..>. In the C-style C loop header, there are three operations which all pertain to the loop iterator variable, separated by semicolon C<;> characters: initialization, continuation condition, and incrementation. The initialization operation is an integer variable declaration which is only executed once, before the very first loop iteration. The continuation condition operation is an inequality operator which is evaluated for boolean truth value before each loop iteration, and the loop will continue iterating as long as the condition evaluates to true. The incrementation operation is generally an arithmetic incrementation operator which executes once at the end of every loop iteration. All RPerl source code files which utilize a C-style C loop must also include a specific C<## no critic qw(ProhibitCStyleForLoops)> directive to avoid triggering an RPerl syntax error. ## no critic qw(ProhibitCStyleForLoops) for ( my integer $i = 1; $i <= 5; $i++ ) { print 'have $i = ', $i, "\n"; } =for rperl X have $i = 1 have $i = 2 have $i = 3 have $i = 4 have $i = 5 =for rperl X In the source code example above, the initialization operation is C, which achieves the same outcome as the C and C<1 ..> components in the previous section's range C loop header. The continuation condition is C<$i E= 5>, which is equivalent to the range C loop header's C<.. 5> component. Finally, the incrementation operation is C<$i++>, which equivalent to the implied increment-by-one of the range operator C<..> itself. C-style C loop control structures always take the following form: ## no critic qw(ProhibitCStyleForLoops) for ( my integer $i = $lower; $i <= $upper; $i++ ) { # PERFORM OPERATIONS INSIDE LOOP } In the source code example above, C<$i> is the loop iterator variable, which you may name something other than C<$i>, as with the range C loop. The C<$lower> and C<$upper> variables may be any expression, literal, or variable which produces a numeric value. The less-or-equal C=> operator may be any comparison operator; if less-or-equal is used as shown in this example, then the number of times this loop will iterate is C<($upper - $lower) + 1>, again matching the behavior of the simpler range C loop control structure. The C<$i++> auto-increment operator may be any operation, although the obvious goal should be to increment or modify the loop iterator variable in some way. As with the range C loop example in the previous section, each time this loop iterates it will cause the value of C<$i> to increase by one, starting at C<$lower> and ending at C<$upper>. As with range C loops, all C-style C loops have lexically scoped iterator variables. If you attempt to utilize a loop iterator variable outside of a loop, you will likely experience a C++ compile-time error. Let's return again to our example from the C subroutine, now converted to a C-style C loop: ## no critic qw(ProhibitCStyleForLoops) # loop through all valid values of $i for use as index to input array for ( my integer $i = 0; $i < $input_av_length; $i++ ) { # retrieve input array's element at index $i $input_av_element = $input_avref->[$i]; # PERFORM OPERATIONS USING $input_av_element } In this modified source code example, the loop header's initialization operation is C. The continuation condition has been simplified and optimized by removing the subtract-one C<- 1> operation and utilizing a less-than C> operator instead of a less-or-equal C=> operator. (RPerl is usually capable of automatically performing this specific optimization on the range operator's second operand in range C loops, where applicable.) The incrementation operation is a simple C<$i++> auto-increment operator which increases the value of iterator variable by one after each loop iteration. The loop body remains unchanged, and we can access the elements of array C<$input_avref> in the exact same manner as in the original example. This C-style C loop will access each element of the array in order, and is functionally equivalent to the original range C loop. =head3 Section 3.12.3: The C Loop Sometimes you do not need a loop iterator variable at all, and instead you just need to access each element of an array in order; for this, you may choose the C loop control structure. By utilizing a C loop, you can rest assured that no code inside your loop body will cause problems by modifying your iterator variable, because there is no iterator to begin with! =for html I =over =item * I loop instead of a C or C loop.> =back =for html In the range C loop header there is one operation; in the C-style C loop header there are three operations; and in the C loop header there is one operation, the element variable declaration, followed by a list of elements. Because the C loop has no iterator variable, we can skip directly to initializing the variable which will store each loop iteration's respective element, and this now occurs in the loop header instead of inside the loop body. The list of elements in a C loop header is where we get the individual elements accessible during each loop iteration. foreach my string $element ( 'smile', 'frown', 'blank stare', 'wince', 'pucker' ) { print 'have $element = ', $element, "\n"; } =for rperl X have $element = smile have $element = frown have $element = blank stare have $element = wince have $element = pucker =for rperl X In the source code example above, the declaration operation is C, followed by the element list containing three string literals which describe common facial expressions. C loop control structures always take the following form: foreach my string $element ( 'first', 'second', 'third' ) { # PERFORM OPERATIONS INSIDE LOOP } In the source code example above, C<$element> is the loop element variable of data type C, which you may name something other than C<$element> and give any data type as appropriate. The list elements C<'first', 'second', 'third'> may be any expression(s), literal(s), or variable(s) which produce a valid list. It is also quite common to utilize the at-sign-curly-braces array dereference operator C<@{ }> within the loop header's parentheses, in order to load list elements from within a pre-existing array variable (as seen in the next example below). The number of times this loop will execute is equal to the number of elements in the list, which is three in the current example. As with the iterator variables in C loops, all the element variables in C loops are lexically scoped. If you attempt to utilize a loop element variable outside of a loop, you will likely experience a C++ compile-time error. Let's return once more to our example from the C subroutine, now finally converted to a C loop: # loop through all valid elements in input array foreach my integer $input_av_element ( @{$input_avref} ) { # PERFORM OPERATIONS USING $input_av_element } In this re-modified source code example, the loop header's declaration operation is C. The list elements are taken directly from the C<$input_avref> variable by use of the array dereference operator C<@{ }>. The loop iterator variable is completely removed, as are the range operator, the continuation condition inequality operator (including subtract-one operation), and the incrementation operator in the loop header, as well as the array element retrieval operation inside the loop body. The resulting code is significantly simpler, cleaner, and less error-prone than before. =head2 Section 3.13: Punctuation Variables & Magic In normal Perl, you may access and modify a number of I<"punctuation variables"> AKA I<"special variables">, which are created by the Perl language itself and may be utilized to achieve many different goals. Perl punctuation variables derive their collective name from their sometimes-cryptic combinations of punctuation characters, such as the dollar-sign C<$>, at-sign C<@>, percent-sign C<%>, underscore C<_>, and exclamation-point C characters. A semi-random (and relatively tiny) selection of Perl's numerous punctuation variables follows: =over =item * C<$_> AKA C<$ARG> =item * C<@_> AKA C<@ARG> =item * C<$!> AKA C<$OS_ERROR> AKA C<$ERRNO> =item * C<%!> AKA C<%OS_ERROR> AKA C<%ERRNO> =item * C<$$> AKA C<$PROCESS_ID> AKA C<$PID> =back In the list above, the left-most item on each line is the punctuation form of each punctuation variable, followed by the plain-English equivalent(s). Out of all these (and the many other unlisted) punctuation variables, only C<@ARG> is utilized in RPerl, and then only in the plain-English format, never the C<@_> punctuation format. Please see L for more information on the C<@ARG> special variable. Practically all of the punctuation variables' functionality is based on Perl's high-magic software components. You may recall the mention of Perl's magic in the following sections: =over =item * L "The most complex and flexible parts of Perl are called I<"high magic">, so RPerl is focused on supporting the I<"low magic"> parts of Perl which can be made to run fast." =item * L "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." =item * L "The high-magic features of Perl are primarily responsible for the slow speed at which Perl executes general-purpose computations." =back The Low-Magic Perl Commandments (LMPCs) put an even finer point on it: =over =item * L "11. Thou Shalt Not Use ... High-Magic Perl" =item * L "23. Thou Shalt Not Use ... Punctuation Variables" =back In keeping with the 23rd LMPC, RPerl does not support the use of punctuation variables. Further, in keeping with the 11th LMPC, RPerl does not support the use of any high-magic Perl features, which is the basis of RPerl's ability to produce super-high-speed output. Future versions of RPerl may include support for medium-magic Perl features, and perhaps even high-magic features some day, but the default RPerl compile mode will always be based on the low-magic RPerl grammar, which generates the most high-performance output code possible. Please review all of L for more information about which Perl features are high-magic and which are low-magic. =head2 Section 3.14: C Operator Sometimes you will want to reverse the order in which a list or array's elements are stored, whereby the last element becomes first, and vice-versa. For this purpose, you may choose the C operator. Like C & C & friends, the C operator requires array arguments to be dereferenced, so don't forget to use the closed-fixity at-sign-curly-braces C<@{ }> array dereference operator where appropriate. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
C<reverse> Operator =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Reverse =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook reverse =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B reverse LIST LIST is comma-separated list of expressions; Reverse order of list elements, return reversed list; May be utilized anywhere a list is accepted # the following two lines are equivalent reverse 'foo', 'bar', 'bat', 'baz', 'quux' 'quux', 'baz', 'bat', 'bar', 'foo' X # reverse array elements my integer_arrayref $forward = [2, 8, 24, 76, 238, 748]; my integer_arrayref $reversed = [reverse @{$forward}]; print 'have $forward = ', integer_arrayref_to_string($forward), "\n"; print 'have $reversed = ', integer_arrayref_to_string($reversed), "\n"; =for rperl X have $forward = [2, 8, 24, 76, 238, 748] have $reversed = [748, 238, 76, 24, 8, 2] =for rperl X =back =head2 Section 3.15: C Operator Sometimes you will want to sort the order in which a list or array's elements are stored, whereby the element with the lowest value becomes first, and the element with the highest value is last. For this purpose, you may choose the C operator. Like C, the C operator requires arrays to be dereferenced, so you must use the closed-fixity at-sign-curly-braces C<@{ }> array dereference operator for array arguments. =begin text my $z = q{<<< BEGIN TEXT EVAL >>>}; use Text::ASCIITable; my Text::ASCIITable $table = Text::ASCIITable->new({alignHeadRow => 'center', drawRowLine => 1}); $table->setCols(splice @{[split /\s*\n\s*/, q{ =end text =begin man .TS allbox tab(@) ; c c c c c c c l l l l r l l . =end man =for html =begin docbook
C<sort> Operator =end docbook =for man T{ =for html =for docbook B =for man T}@T{ =for html =for docbook =for docbook =for text $table->addRow(splice @{[split /\s*\n\s*/, q{ =for man T{ =for html =for docbook Sort =for man T}@T{ =for html =for docbook =begin text return $table->draw( ['.=','=.','=','='], # .=============. ['|','|','|'], # | info | info | ['|-','-|','=','='], # |-===========-| ['|','|','|'], # | info | info | ["'=","='",'=','='], # '=============' ['|-','-|','-','+'] # rowseperator ); $z = q{<<< END TEXT EVAL >>>}; =end text =for man .TE =for html
=for docbook
=for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for man T}@T{ =for html =for docbook B =for text }]}, 1); =for man T} =for html
=for docbook
=for docbook sort =for man T}@T{ =for html =for docbook Variadic =for man T}@T{ =for html =for docbook Prefix =for man T}@T{ =for html =for docbook 01 =for man T}@T{ =for html =for docbook Left =for man T}@T{ =for html =for docbook Coming Soon =for text }]}, 1); =for man T} =for html
=for docbook =over =item * B sort LIST LIST is comma-separated list of expressions which all produce scalar values; Sort order of list elements, return sorted list; May be utilized anywhere a list is accepted # the following two lines are equivalent sort 'foo', 'bar', 'bat', 'baz', 'quux' 'bar', 'bat', 'baz', 'foo', 'quux' X # sort array elements my integer_arrayref $random = [6, 4, 8, 1, 5, 0, 9, 2, 7, 3]; my integer_arrayref $sorted = [sort @{$random}]; print 'have $random = ', integer_arrayref_to_string($random), "\n"; print 'have $sorted = ', integer_arrayref_to_string($sorted), "\n"; =for rperl X have $random = [6, 4, 8, 1, 5, 0, 9, 2, 7, 3] have $sorted = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] =for rperl X =back =head2 Section 3.16: Scalar & Array Contexts In normal Perl, usually there is no explicit indication of the data type of an expression's return value; in other words, normal Perl code doesn't know ahead of time if any particular expression will return a string or an integer or an array, etc. RPerl solves this issue once-and-for-all by providing a fully-fledged data type system, as you have been learning about throughout this book. Normal Perl attempts to approach this issue through a few different mechanisms, one of which is I<"context">, meaning the requirements or expectations of the receiving operation. In other words, Perl tries to guess what kind of data you want, and may even change your data without telling you, based on the requirements of your own code. In this section we will consider scalar context, and how it relates to array context (AKA list context). All three lines of code in the following example enforce scalar context on the right-hand-side of the equal-sign C<=>, because the receiving operation on the left-hand-side is a scalar (integer) variable modification and thus requires a scalar value as input: my integer $i = 3; # scalar variable receiving scalar value, context match, fine in Perl, fine in RPerl my integer $j = scalar @{[2, 4, 6]}; # scalar variable receiving scalar value, context match, fine in Perl, fine in RPerl my integer $k = @{[2, 4, 6]}; # scalar variable receiving array value, context mismatch, fine in Perl, error in RPerl compiled modes print 'have $i = ', $i, "\n"; print 'have $j = ', $j, "\n"; print 'have $k = ', $k, "\n"; When executing the source code above in non-compiled mode, the following output is generated: =for rperl X have $i = 3 have $j = 3 have $k = 3 =for rperl X However, when we try to compile the source code, we experience an error: =for rperl X ERROR ECOGEASCP871, CODE GENERATOR, ABSTRACT SYNTAX TO C++: Array dereference of array reference must provide data type for array reference in CPPOPS_CPPTYPES mode, but no data type provided, dying =for rperl X In non-compiled mode, the normal Perl interpreter will detect the context mismatch and force an implicit context switch from the array C<@{[2, 4, 6]}> to the scalar C<$k>. This same array-to-scalar context switch is achieved explicitly via the C operator. Both implicit and explicit context switches have the same effect, an array value put into scalar context will simply return the number of array elements. The ability for Perl to guess and imply context is derived from high-magic features. Once again, the Low-Magic Perl Commandments are clear on the issue: =over =item * L "57. Thou Shalt Not Use Scalar Operations In List Context & Vice-Versa" =back In keeping with the 57th LMPC, RPerl does not support the use of implied or mismatched context. When you need to force an array or list into scalar context, which is the same as asking for an element count, then simply utilize the C operator as demonstrated above. Do not try to force a scalar into an array context, it makes no sense in RPerl and will only produce errors in your code. =head2 Section 3.17: C & Arrays When we combine a C loop control structure with the CSTDINE> input data stream, then the C loop is able to detect a special signal from the operating system, known as I<"End-Of-Transmission"> (EOT) or I<"End-Of-File"> (EOF), which tells the loop there is no more user input available. The EOF condition is triggered when a user presses the key combination on their keyboard. Data collected from CSTDINE> is always of the C data type, and each collected line always contains an extra newline C<"\n"> character at the end, due to the user pressing the key after each line. (If the user presses only and not after the last line of input, then the extra newline character will be missing on the last line collected.) We can use the safe C operator to remove any trailing newline(s) characters if present, and push each collected line of input onto an array: my string_arrayref $input_strings = []; print 'Please input zero or more strings, separated by , ended by :', "\n"; while (my string $input_string = ) { chomp $input_string; push @{$input_strings}, $input_string; } print "\n"; print 'have $input_strings = ', string_arrayref_to_string($input_strings), "\n"; When we run the source code example above, we will be prompted for input until we signal EOF: =for rperl X Please input zero or more strings, separated by , ended by : alpha beta gamma delta epsilon have $input_strings = ['alpha', 'beta', 'gamma', 'delta', 'epsilon'] =for rperl X If we press immediately, then no input is collected and we have an empty array, zero elements: =for rperl X Please input zero or more strings, separated by , ended by : have $input_strings = [] =for rperl X If we press once before pressing , then a blank line of input is collected and we have an array with one element, an empty string: =for rperl X Please input zero or more strings, separated by , ended by : have $input_strings = [''] =for rperl X If you want to accept only a certain number of input lines, instead of allowing the user to end input with , then one option would be to replace the C loop with a C loop instead. This is left as an exercise for the reader. =head2 Section 3.18: Exercises =head3 1. Reverse Collected Array Of Strings [ 30 mins ] In the same F directory from the chapter 1 & 2 exercises, create a new sub-directory named F. In the new sub-directory, create an RPerl program file named F. Use a C loop to collect data from CSTDINE> until the user signals EOF, storing the collected strings in an array variable named C<$input_strings>. Use the C operator and store the new data in a different array variable named C<$input_strings_reversed>. Finally, use a C loop to print all the elements in reverse order, one-at-a-time. (Do not use the C subroutine.) Your program should produce exactly the following output, when provided with the first seven letters of the alphabet as input: =for rperl X $ rperl -t LearningRPerl/Chapter3/exercise_1-stdin_strings_reverse.pl Please input zero or more strings, separated by , ended by : a b c d e f g Strings in reverse order: g f e d c b a =for rperl X =head3 2. Collect Array Indices [ 45 mins ] Use the C operator to store the following list of words in an array variable named C<$flintstones_and_rubbles>, in exactly this order: =over =item * fred =item * betty =item * barney =item * dino =item * wilma =item * pebbles =item * bamm-bamm =back Next, use a C loop to collect data from CSTDINE> until the user signals EOF, converting the collected strings to integers and storing them in an array variable named C<$input_indices>. Finally, use a C loop to print all the elements of C<$flintstones_and_rubbles> which correspond to the collected user input array indices, with the caveat that we do not expect the user to know array indices begin at zero, so the element C is displayed by user input C<1> instead of C<0>. Your program should produce exactly the following output, when provided with the first four odd integers as input: =for rperl X $ 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 , ended by : 1 3 5 7 Flintstones & Rubbles: fred barney wilma bamm-bamm =for rperl X =head3 3. Sort & Display Collected Array Of Strings [ 45 mins ] Create a constant boolean value named C, and set it to C<0>. Next, use a C loop to collect data from CSTDINE> until the user signals EOF, storing the collected strings in an array variable named C<$input_strings>. Use the C operator and store the new data in a different array variable named C<$input_strings_sorted>. Finally, use a C loop containing a nested C statement and C operator, in order to print all the elements in sorted order. If the value of C is true, separate the elements by one space and display all on one line of output; otherwise, display each element on a new line of output. Your program should produce exactly the output below, when C is set to C<0> and the following strings are provided as input: =for rperl X $ rperl -t LearningRPerl/Chapter3/exercise_3-stdin_strings_sort.pl Please input zero or more strings, separated by , ended by : gygax grue gorn galactus galadriel Strings in ASCIIbetical order: galactus galadriel gorn grue gygax =for rperl X Now, set the value of C to C<1> and you should see the following: =for rperl X $ rperl -t LearningRPerl/Chapter3/exercise_3-stdin_strings_sort.pl Please input zero or more strings, separated by , ended by : gygax grue gorn galactus galadriel Strings in ASCIIbetical order: galactus galadriel gorn grue gygax =for rperl X X
=head1 CHAPTER 4: ORGANIZING BY SUBROUTINES As we have seen in the preceding chapters, Perl is an operator-rich language, meaning there are a relatively large number of built-in operators available to Perl programmers. However, sometimes you will want to create your own user-defined operation, which may be utilized like a built-in operator and which provides some custom functionality that's not already available. In these cases, you may create a new I<"subroutine">. As you may have expected, our first subroutine example will be our old favorite, "Hello, World!", implemented in RPerl: our void $hello_world = sub { print 'Hello, World!', "\n"; }; In the source code example above, we have defined a very simple subroutine named C, which may be called as follows: hello_world(); When called, this subroutine simply prints the output: =for rperl X Hello, World! =for rperl X Now let's dissect the above source code example into its individual components: First, we see the keyword C, which is used in normal Perl to denote a global variable, and is used in RPerl for only a few specific purposes, most commonly to begin the definition of a subroutine. (We have already utilized the C keyword to declare the C<$VERSION> variable in the header section of an RPerl program.) The definitions of all RPerl subroutines begin with the C keyword. Second, we see the C data type, which provides the I<"return type"> of the subroutine. All RPerl subroutines must specify exactly one return type, which is the data type of the value returned when the subroutine is finished running. A return type of C means this subroutine does not actually return any data whatsoever, which makes sense because all we have is a single C statement inside the subroutine, and generally the C statement is not considered to be an operator which returns a (useful) value. Normal Perl does not provide a type system, and thus can not provide the ability to specify subroutine return types; this is only possible in RPerl. Third, we see the variable name C<$hello_world>, which provides the name of the subroutine. The definition of an RPerl subroutine is the only place where you will include a dollar-sign C<$> as part of the subroutine name; everywhere else in your source code you will refer to the subroutine without the dollar-sign C<$> prefix and with an added parentheses C<( )> suffix, so our example becomes C throughout the rest of your code. In normal Perl, a subroutine name is very rarely defined with a dollar-sign C<$> prefix - this is a bit of tricky magic (oh no!) used internally by RPerl in order to enable subroutine return types. Because a special subroutine reference value is stored in the global scalar variable named C<$hello_world>, you may not create a normal variable with the same name C<$hello_world> in the main operations section of your RPerl program. However, you are free to create scalar variables named C<$hello_world> within this or any other subroutine. After the RPerl subroutine name, we will always see an equal-sign C<=> followed by the C keyword and a left-curly-brace C<{> character. As usual, the equal-sign C<=> is the assignment operator, which assigns the special subroutine reference value to the global scalar variable C<$hello_world>. Both RPerl and normal Perl use the C keyword to define a subroutine, as well as the left-curly-brace C<{> to denote the beginning of the subroutine's body. Following the left-curly-brace C<{> character is the subroutine's body, which is a code block consisting of an arbitrary number of operations, and is generally the same in both RPerl and normal Perl. In the example above, the body consists of exactly one operation, the C statement. Finally, we see a right-curly-brace C<}> followed by a semicolon C<;> character, used to denote the end of the subroutine's body. In normal Perl, there is no trailing semicolon C<;> used after the right-curly-brace C<}> character. =head2 Section 4.1: Subroutine Definitions In software development, we have the two related concepts of I<"subroutine declaration"> and I<"subroutine definition">. To declare a subroutine, a software developer must provide (at least) the subroutine's name and return type. To define a subroutine, a developer must provide at least the subroutine's name and body. In RPerl, these two steps of declaration and definition are always combined into one single step, where we provide the subroutine's name and return type and body all together, as seen in the "Hello, World!" example in the previous section. Normal Perl does not provide the ability to specificy a subroutine's return type, so the closest thing to the separation of subroutine declaration and definition in normal Perl is the usage of high-magic features such as the manipulation of subroutine references, etc. In the C and C++ programming languages, subroutine declarations and definitions are traditionally kept separate, often in completely different source code files. Because RPerl subroutine declarations and definitions are always combined, we will simply use the term "subroutine definition" in this textbook. RPerl subroutines with very short bodies may be written on a single line, so we can re-write the "Hello, World!" subroutine as a one-liner by simply deleting the two invisible newline characters: our void $hello_world = sub { print 'Hello, World!', "\n"; }; In normal Perl, the same subroutine would be written like this: sub hello_world { print 'Hello, World!', "\n"; } Let's compare them more closely: sub hello_world { print 'Hello, World!', "\n"; } # Perl our void $hello_world = sub { print 'Hello, World!', "\n"; }; # RPerl In the comparison above, we can quickly see the different placements of the C keyword and RPerl's usage of the C return type. We can also easily point out the four additional bits of RPerl syntax not present in the normal Perl line: C, C<$>, C<=>, and C<;>. In both RPerl and normal Perl, the capitalization of variables (and thus RPerl subroutine names) is significant, which is to say that subroutine names are case-sensitive. The subroutine name C is different than either C or C, all of which are valid Perl (and RPerl) subroutine names. As detailed in L, the all-uppercase subroutine name C is reserved for constant use only, as is any other all-uppercase subroutine or variable name in RPerl. our void $hello_world = sub { print 'Hello, World!', "\n"; }; our void $Hello_World = sub { print 'Hello, World, again!', "\n"; }; our void $HELLO_world = sub { print 'Hello, World, yet again!', "\n"; }; We can call these three similarly-named-yet-distinct subroutines as follows: hello_world(); Hello_World(); HELLO_world(); Doing so will print three different lines of output: =for rperl X Hello, World! Hello, World, again! Hello, World, yet again! =for rperl X If we try to define a subroutine with an all-uppercase name, RPerl will give an error due to all-uppercase symbols being reserved for constants: our void $HELLO_WORLD = sub { print 'Hello, World!', "\n"; }; Before we can even try to call this C subroutine, RPerl tells us we have made a mistake because an all-uppercase symbol is not a valid variable symbol (and thus not a valid RPerl subroutine name): =for rperl X ERROR ECOPARP00, RPERL PARSER, RPERL SYNTAX ERROR Failed RPerl grammar syntax check with the following information: File Name: ... Line Number: ... Unexpected Token: $HELLO_WORLD Expected Token(s): VARIABLE_SYMBOL =for rperl X As long as you are careful to use proper capitalization, then you are free to utilize all-uppercase constant names such as C alongside not-all-uppercase subroutine names: sub sweet_tooth { print 'Yum! I love ', PIE(), ' pie.', "\n"; } # usable in Perl, error in RPerl our void $SWEET_TOOTH = sub { print 'Yum! I love ', PIE(), ' pie.', "\n"; }; # unusable in Perl, error in RPerl our void $Sweet_Tooth = sub { print 'Yum! I love ', PIE(), ' pie.', "\n"; }; # unusable in Perl, usable in RPerl our void $sweet_tooth = sub { print 'Yum! I love ', PIE(), ' pie.', "\n"; }; # unusable in Perl, best in RPerl In the C example above, the first line is usable only in normal Perl, the second line is not usable at all, and both the third and fourth lines are usable only in RPerl. Please see L for best practices which apply equally to subroutine names as well as variable names. The fourth line fulfills best practices by naming the subroutine using all-lowercase letters. =head2 Section 4.2: Subroutine Calls As seen in the previous two sections, in order to run a subroutine we must call (AKA I<"invoke">) the subroutine by name. This is achieved by simply typing the subroutine's name, without the dollar-sign C<$> prefix, and adding empty parentheses C<( )> as a suffix. As with all Perl expressions, we end with a semicolon C<;> character. In this way, we can call the best practices version of the "sweet tooth" example from the previous section: sweet_tooth(); Utilizing the original constant value from L, invoking the subroutine will return the following output: =for rperl X Yum! I love pecan pie. =for rperl X Remember, as mentioned in the previous section, all subroutine names are case-sensitive and must be spelled exactly the same for every subroutine call. In the following five subroutine calls, only the first line is a valid call because the rest are all misspelled: sweet_tooth(); # fine sweeT_tootH(); # error swEEt_tooth(); # error sweet_tOOth(); # error sw33t_t00th(); # error =head3 Section 4.2.1: Parentheses Suffix & Ampersand Sigil Prefix In RPerl, all subroutine calls must include parentheses C<( )> as a suffix immediately following the name of the subroutine, with no space between the last letter of the name and the left-parenthesis C<(> character. In normal Perl, you are allowed to have whitespace between the subroutine name and the parentheses characters, although this is both unnecessary and potentially quite confusing, thus it is against best practices. Likewise, it is not an error to include optional whitespace between the left-parenthesis C<(> and right-parenthesis C<)> characters, but again, best practices admonish us to allow no extraneous whitespace between the parentheses. =for html I =over =item * I character in a subroutine call.> =item * I and right-parenthesis C<)> characters in a subroutine call.> =back =for html The parentheses suffix is optional in normal Perl, and is required in RPerl: sweet_tooth; # fine in Perl, error in RPerl sweet_tooth (); # fine in Perl, fine in RPerl sweet_tooth( ); # fine in Perl, fine in RPerl sweet_tooth(); # fine in Perl, best in RPerl If we try to call an RPerl subroutine without the parentheses C<( )> suffix, we receive a Perl C error: =for rperl X ERROR ECOPAPL02, RPERL PARSER, PERL SYNTAX ERROR Failed normal Perl strictures-and-fatal-warnings syntax check with the following information: File Name: ./lib/RPerl/Test/Subroutine/program_00_bad_01.pl Return Value: 2 Error Message(s): Bareword "hello_world" not allowed while "strict subs" in use =for rperl X In normal Perl, subroutine calls may include an optional ampersand C<&> sigil prefix, but this is unnecessary and thus unsupported by RPerl: sweet_tooth(); # fine in Perl, fine in RPerl &sweet_tooth(); # fine in Perl, error in RPerl If we try to call an RPerl subroutine using an ampersand C<&> sigil, we receive a Perl::Critic policy violation: =for rperl X ERROR ECOPAPC02, RPERL PARSER, PERL CRITIC VIOLATION Failed Perl::Critic brutal review with the following information: File Name: ... Line number: ... Policy: Perl::Critic::Policy::Subroutines::ProhibitAmpersandSigils Description: Subroutine called with "&" sigil Explanation: See Perl Best Practices page(s) 175 =for rperl X =head2 Section 4.3: Subroutine Return Values In the previous sections, both the C and C example subroutines have return values of C, which means no data is returned to the caller when these subroutines finish running. If we try to utilize the return value of a C subroutine, we will experience undefined behavior which will likely lead to other (possibly mysterious) errors in our code. For example, the variable C<$foo> in the following line of source code will have an unknown and unpredictable value, because the return value of a C subroutine is undefined: my integer $foo = hello_world(); # undefined behavior, unpredictable value in $foo Likewise, the outcome of the following addition C<+> operator is unpredictable, and will probably cause other difficult-to-debug errors elsewhere in our source code: 23 + hello_world() # undefined behavior, unpredictable result So, when we want to utilize the return value of a subroutine, we must give the subroutine a non-C return type in the subroutine definition. our integer $jedi = sub { print q{"You love him, don't you?"}, "\n"; return 6; }; We can call the C subroutine defined above, and actually utilize the return value: my integer $episode = jedi(); print 'Return (value) of the Jedi, Episode ', $episode, "\n"; The above subroutine call and C statement produce the following output: =for rperl X "You love him, don't you?" Return (value) of the Jedi, Episode 6 =for rperl X Your RPerl subroutines may have any return type chosen from the full list of supported RPerl data types, such as C, C, C, etc. =head3 Section 4.3.1: C Operator The C subroutine example in the previous section includes a C operator at the end of the subroutine's body, which serves to return the value C<6> to the caller. In other words, the input operand of the C operator is the numeric literal C<6>, which is then passed back to whatever part of the software originally invoked the C subroutine. The C operator serves two purposes, both returning a specific return value to the caller, as well as controlling termination of the subroutine at some point before the end of the subroutine's body. It is common to have multiple C operators inside one subroutine, organized using conditional statements or other logic: if ($foo < $bar) { return 23; } else { return 42; } A subroutine with C return type may also utilize the C operator, in order to control when and where the subroutine terminates: if ($foo < $bar) { print '$foo is too small, returning', "\n"; return; } print '$foo is not too small, continuing', "\n"; $foo = $bar * 17; In normal Perl, the C operator is optional, and Perl automatically returns the vale of the last expression executed before the subroutine ends. However, leaving out the C operator in RPerl will once again lead to either an error, or undefined and unpredictable behavior in C++ compile modes. sub jedi { print q{"You love him, don't you?"}, "\n"; 6; } # usable in Perl, error in RPerl our integer $jedi = sub { print q{"You love him, don't you?"}, "\n"; 6; }; # unusable in Perl, error in RPerl our integer $jedi = sub { print q{"You love him, don't you?"}, "\n"; return 6; }; # unusable in Perl, usable in RPerl If we exclude the C operator as in the second line above, then we will receive an error in RPerl compiled modes, because the semicolon C<;> of C<6;> is found before an actual operator is encountered: =for rperl X $ rperl jedi.pl ... ERROR ECOPARP00, RPERL PARSER, RPERL SYNTAX ERROR Failed RPerl grammar syntax check with the following information: File Name: ... Line Number: ... Unexpected Token: ; ... =for rperl X We can see undefined behavior when we fail to utilize a C operator in a subroutine which should return a value, in this case an C should be returned but instead a string concatenation C<.> operator is performed without an explicit return value: our integer $unpredictable = sub { 'howdy' . 'doody'; }; print 'have unpredictable() = ', unpredictable(), "\n"; When we run the above C subroutine in RPerl test mode C<-t>, we see the result of the string concatenation operator; when we run the same subroutine in RPerl compiled mode, we receive a seemingly-random number instead: =for rperl X $ rperl -t unpredictable.pl have unpredictable() = howdydoody $ rperl unpredictable.pl have unpredictable() = 140725691414304 =for rperl X We can try to add a C operator to the C subroutine: our integer $unpredictable = sub { return 'howdy' . 'doody'; }; print 'have unpredictable() = ', unpredictable(), "\n"; Adding the C operator will lead to a C++ subcompile error, visible in RPerl debug mode C<-D>, because the string concatenation C<.> operator's C return type does not match the C subroutine's C return type: =for rperl X $ rperl -D unpredictable_return.pl [[[ SUBCOMPILE STDERR ]]] unpredictable_return.cpp: In function ‘integer unpredictable()’: unpredictable_return.cpp:18:52: error: cannot convert ‘std::__cxx11::basic_string’ to ‘integer {aka long int}’ in return return (const string) "howdy" + (const string) "doody"; ^ ERROR ECOCOSU04, COMPILER, SUBCOMPILE: C++ compiler returned error code, croaking... =for rperl X For all subroutines with non-C return types, you must always use the C operator, and always provide the C operator with operands of the correct return type. =head3 Section 4.3.2: Multiple Return Values In normal Perl, the C operator may optionally be provided with more than one operand, thereby causing its subroutine to actually return multiple values to the originating caller. In this case, the calling software must know how to properly receive back more than one return value from the invoked subroutine, or else you may receive the incorrect data or experience undefined behavior. The following subroutine C is valid in normal Perl only: sub foo_multi { return 21, 22, 23; } (my $retval0, my $retval1, my $retval2) = foo_multi(); print 'have $retval0 = ', $retval0, "\n"; print 'have $retval1 = ', $retval1, "\n"; print 'have $retval2 = ', $retval2, "\n"; Running the normal Perl C code above will produce the following output: =for rperl X have $retval0 = 21 have $retval1 = 22 have $retval2 = 23 =for rperl X On the other hand, any RPerl subroutine defined with a non-C return type must provide each of its C operators with exactly one operand, thereby causing the subroutine to return exactly one value to the originating caller. Likewise, all non-C subroutine calls in RPerl must be designed to receive back exactly one data value of the subroutine's defined return type. (As with many design aspects of the RPerl compiler, this particular requirement is based on the behavior of the C++ target language.) our integer $foo_single = sub { return 23; }; my integer $retval = foo_single(); print 'have $retval = ', $retval, "\n"; =for rperl X have $retval = 23 =for rperl X When you want to return multiple values from an RPerl subroutine, you may simply return an array reference containing more than one element, then you will receive back a single array reference in the caller and you access each element as needed. In other words, you may wrap up multiple return values inside of a single array reference, and still be in compliance with the exactly-one-return-value requirement. our integer_arrayref $foo_multi = sub { return [21, 22, 23]; }; my integer_arrayref $retvals = foo_multi(); my integer $retval0 = $retvals->[0]; my integer $retval1 = $retvals->[1]; my integer $retval2 = $retvals->[2]; print 'have $retval0 = ', $retval0, "\n"; print 'have $retval1 = ', $retval1, "\n"; print 'have $retval2 = ', $retval2, "\n"; Running the RPerl C code above will produce the exact same variables and output as the normal Perl C code: =for rperl X have $retval0 = 21 have $retval1 = 22 have $retval2 = 23 =for rperl X Currently, all RPerl subroutines utilizing an array reference return value must only return elements which all have the exact same data type as one another, because RPerl arrays are homogeneous with only one data type shared across all elements. As mentioned in L, future versions of RPerl will probably provide a C data structure which can hold elements of non-matching data types. =head2 Section 4.4: Subroutine Arguments When calling a subroutine, often you will want to provide one or more pieces of data as input to the subroutine; for this purpose, we use I<"subroutine arguments">. Perl provides a special array variable named C<@ARG>, which contains all arguments which have been passed into each subroutine by its caller. For any RPerl subroutine which accepts arguments, the first expression of the subroutine must always be the argument definition operation, as seen in the following source code example: our void $foo_arg = sub { (my integer $arg1) = @ARG; print 'inside foo_arg(), have $arg1 = ', integer_to_string($arg1), "\n"; }; foo_arg(1_701); Running the C code example gives us this output: =for rperl X inside foo_arg(), have $arg1 = 1_701 =for rperl X It's easy for a subroutine to accept multiple arguments, simply separate each argument's variable declaration by a comma C<,> character, and keep them all within the parentheses C<( )> characters: our void $foo_args = sub { (my integer $arg1, my number $arg2, my string $arg3) = @ARG; print 'have $arg1 * $arg2 = ', number_to_string($arg1 * $arg2), "\n"; print 'have $arg3 x $arg1 = ', ($arg3 x $arg1), "\n"; }; foo_args(5, 2.575, 'over and '); Running the C code gives us: =for rperl X have $arg1 * $arg2 = 12.875 have $arg3 x $arg1 = over and over and over and over and over and =for rperl X Unsurprisingly, normal Perl provides magic which allows a subroutine to change its own argument names and data types at runtime, which is one of Perl's many dynamic behaviors. In the source code example below, we see the C operator used to receive each argument one-at-a-time, where the name and (implied) data type of the second argument is dependent upon runtime conditional logic using the first argument: sub bar_args_dynamic { my $arg_type = shift @ARG; if ($arg_type eq 'integer') { my $bar_int = shift @ARG; print 'have $bar_int * 3 = ', $bar_int * 3, "\n"; } else { my $bar_str = shift @ARG; print 'have $bar_str x 3 = ', $bar_str x 3, "\n"; } return; } bar_args_dynamic('integer', 4); bar_args_dynamic('string', 'repeat'); Running the C subroutine example produces the following output: =for rperl X have $bar_int * 3 = 12 have $bar_str x 3 = repeatrepeatrepeat =for rperl X In RPerl, the argument names and data types for each subroutine are set at compile time, which is one of RPerl's many static behaviors and which contributes to significant runtime performance optimizations. In other words, one reason why RPerl is faster than normal Perl is because RPerl knows the names and data types for each subroutine when the C compiler is run. By always accepting three arguments, we can upgrade from the C subroutine to the C subroutine, which can then be compiled with RPerl: our void $bar_args_static = sub { (my string $arg_type, my integer $bar_int, my string $bar_str) = @ARG; if ($arg_type eq 'integer') { print 'have $bar_int * 3 = ', $bar_int * 3, "\n"; } else { print 'have $bar_str x 3 = ', $bar_str x 3, "\n"; } return; }; bar_args_static('integer', 4, q{}); bar_args_static('string', 0, 'repeat'); Running C gives us the exact same variables and output as C, now able to be compiled and run at a much faster speed: =for rperl X have $bar_int * 3 = 12 have $bar_str x 3 = repeatrepeatrepeat =for rperl X =head3 Section 4.4.1: Variadic Subroutines The number of arguments accepted by a subroutine is known as its "arity". A subroutine, operator, or other operation which is capable of accepting a varying number of input arguments is known as "variadic". (Please see L for more information.) In the previous section, we saw the C subroutine use the C operator (and associated Perl magic) in order to control its own accepted arguments. The same magic can be used in normal Perl to change, at runtime, the number of arguments accepted by a subroutine. In normal Perl, a variadic subroutine can be created as follows: sub baz_variadic_dynamic { my $num_args = shift @ARG; my $arg2 = q{}; my $arg3 = q{}; my $arg4 = q{}; if ($num_args >= 2) { $arg2 = shift @ARG; } if ($num_args >= 3) { $arg3 = shift @ARG; } if ($num_args >= 4) { $arg4 = shift @ARG; } print 'have $num_args = ', $num_args, "\n"; print 'have $args2 = ', $arg2, "\n"; print 'have $args3 = ', $arg3, "\n"; print 'have $args4 = ', $arg4, "\n\n"; return; } baz_variadic_dynamic(1); baz_variadic_dynamic(2, 'howdy'); baz_variadic_dynamic(3, 'howdy', 'doody'); baz_variadic_dynamic(4, 'howdy', 'doody', 'time'); Running the normal Perl subroutine C, we can see how the first argument C<$num_args> is used to control how many additional arguments are accepted: =for rperl X have $num_args = 1 have $args2 = have $args3 = have $args4 = have $num_args = 2 have $args2 = howdy have $args3 = have $args4 = have $num_args = 3 have $args2 = howdy have $args3 = doody have $args4 = have $num_args = 4 have $args2 = howdy have $args3 = doody have $args4 = time =for rperl X As we did with subroutine return values in L, we can use an array reference to simulate a variadic subroutine while maintaining compatibility with RPerl: our void $baz_variadic_static = sub { (my integer $num_args, my string_arrayref $args) = @ARG; my string $arg2 = q{}; my string $arg3 = q{}; my string $arg4 = q{}; if ($num_args >= 2) { $arg2 = $args->[0]; } if ($num_args >= 3) { $arg3 = $args->[1]; } if ($num_args >= 4) { $arg4 = $args->[2]; } print 'have $num_args = ', $num_args, "\n"; print 'have $args2 = ', $arg2, "\n"; print 'have $args3 = ', $arg3, "\n"; print 'have $args4 = ', $arg4, "\n\n"; return; }; baz_variadic_static(1, []); baz_variadic_static(2, ['howdy']); baz_variadic_static(3, ['howdy', 'doody']); baz_variadic_static(4, ['howdy', 'doody', 'time']); In the C subroutine example above, we accept an array reference argument named C<$args> and retrieve its elements as controlled by the C<$num_args> input argument, achieving the same outcome as in C. You will note the variable C<$arg2> receives its value from C<$args-E[0]> which is a seeming index difference of 2, caused by array indices starting at 0 instead of 1, combined with the fact that we have already accepted C<$num_args> as a separate argument altogether. Also, when we call C, all arguments after the first must be wrapped in the square-brackets C<[ ]>, denoting an array reference. As you may expect, running the C subroutine gives us the same variables and output as C, with the added performance optimizations of the RPerl compiler: =for rperl X have $num_args = 1 have $args2 = have $args3 = have $args4 = have $num_args = 2 have $args2 = howdy have $args3 = have $args4 = have $num_args = 3 have $args2 = howdy have $args3 = doody have $args4 = have $num_args = 4 have $args2 = howdy have $args3 = doody have $args4 = time =for rperl X =head2 Section 4.5: Subroutine Variables, Variable Scope & Persistence In normal Perl, variables inside a subroutine may behave in several complex ways, depending upon if and how the variable was declared, which can happen both inside and outside the subroutine itself. Perl provides a number of different ways to create a variable, including the by-now familiar C keyword, as well as the C and C keywords, and others. Perl variables possess many (often magic) properties which affect their behavior, two of which are I<"scope"> and I<"persistence">. The scope of a variable is the subroutine, code block, or other region of code within which the variable is valid and accessible. Attempting to utilize a variable outside of its scope will lead to errors and undefined behavior. The persistence of a variable is how long the variable will remain valid, before its memory is released and it is no longer accessible from anywhere within your Perl program. As with out-of-scope variables, attepting to access a variable after its persistence has expired will result in errors and undefined behavior. Perl variables declared using the C keyword are classified as possessing I<"local scope">, as well as I<"intermittent persistence"> (AKA I<"non-persistent">). This means C variables declared inside a subroutine will only be valid within their own subroutine (local scope), and must be re-declared each time the subroutine is executed (intermittent). In Perl terminology, "local scope" is generally synonymous with "lexical scope" and "private scope". The C variable is the safest, simplest, and most optimizable classification of Perl variable. use strict; #print 'before defining quux(), have $local_intermittent = ', $local_intermittent, "\n"; # YES ERROR our void $quux = sub { my integer $local_intermittent = 23; print 'inside quux(), have $local_intermittent = ', $local_intermittent, "\n"; # NO ERROR $local_intermittent++; }; #print 'after defining quux(), have $local_intermittent = ', $local_intermittent, "\n"; # YES ERROR quux(); #print 'after calling quux(), have $local_intermittent = ', $local_intermittent, "\n"; # YES ERROR quux(); #print 'after calling quux(), have $local_intermittent = ', $local_intermittent, "\n"; # YES ERROR Running the example code above, which utilizes a C variable, gives us the following output: =for rperl X inside quux(), have $local_intermittent = 23 inside quux(), have $local_intermittent = 23 =for rperl X Perl variables declared using C are of I<"global scope"> and are I<"persistent">, which means C variables may be accessed from anywhere within your Perl program and will never need to be re-declared. This is one of the least safe, simple, and optimizable classifications of variable. use strict; our integer $global_persistent = 23; print 'before defining quux(), have $global_persistent = ', $global_persistent, "\n"; # NO ERROR our void $quux = sub { print 'inside quux(), have $global_persistent = ', $global_persistent, "\n"; # NO ERROR $global_persistent++; }; print 'after defining quux(), have $global_persistent = ', $global_persistent, "\n"; # NO ERROR quux(); print 'after calling quux(), have $global_persistent = ', $global_persistent, "\n"; # NO ERROR quux(); print 'after calling quux(), have $global_persistent = ', $global_persistent, "\n"; # NO ERROR Running this C variable example code produces the output below: =for rperl X before defining quux(), have $global_persistent = 23 after defining quux(), have $global_persistent = 23 inside quux(), have $global_persistent = 23 after calling quux(), have $global_persistent = 24 inside quux(), have $global_persistent = 24 after calling quux(), have $global_persistent = 25 =for rperl X Perl variables declared using C are of local scope and are persistent; this means C variables may be accessed only from within the area of code where they were defined, but they do not ever need to be re-declared, and they will retain their values between each execution of their enclosing code block. A C variable declared inside a subroutine will save its value each time the subroutine is executed, providing yet another convenient use of magic in normal Perl. Like C variables, C variables score low for safety, simplicity, and optimizability. use strict; use feature 'state'; #print 'before defining quux(), have $local_persistent = ', $local_persistent, "\n"; # YES ERROR our void $quux = sub { state integer $local_persistent = 23; print 'inside quux(), have $local_persistent = ', $local_persistent, "\n"; # NO ERROR $local_persistent++; }; #print 'after defining quux(), have $local_persistent = ', $local_persistent, "\n"; # YES ERROR quux(); #print 'after calling quux(), have $local_persistent = ', $local_persistent, "\n"; # YES ERROR quux(); #print 'after calling quux(), have $local_persistent = ', $local_persistent, "\n"; # YES ERROR Executing the C variable example code above will generate the following output: =for rperl X inside quux(), have $local_persistent = 23 inside quux(), have $local_persistent = 24 =for rperl X In normal Perl, a variable which is utilized without first being declared will usually undergo the process of I<"autovivification">, which means the variable is automatically created by Perl, according to Perl's own internal rules. Variables which have been autovivified may cause many difficult-to-debug issues, such as misspelled variables taking data without emitting any warnings, etc. Because of this, the C pragma will cause an error to be triggered by any variables which would normally be autovivified. Like C and C variables, autovivified variables receive a low score for safety, simplicity, and speed. print 'before defining quux(), have $autovivified = ', $autovivified, "\n"; # NO ERROR, YES WARNING our void $quux = sub { $autovivified = 23; print 'inside quux(), have $autovivified = ', $autovivified, "\n"; # NO ERROR $autovivified++; }; print 'after defining quux(), have $autovivified = ', $autovivified, "\n"; # NO ERROR, YES WARNING quux(); print 'after calling quux(), have $autovivified = ', $autovivified, "\n"; # NO ERROR quux(); print 'after calling quux(), have $autovivified = ', $autovivified, "\n"; # NO ERROR Executing the autovivified code requires us to first disable C, after which it will run with warnings: =for rperl X Use of uninitialized value $autovivified in print before defining quux(), have $autovivified = Use of uninitialized value $autovivified in print after defining quux(), have $autovivified = inside quux(), have $autovivified = 23 after calling quux(), have $autovivified = 24 inside quux(), have $autovivified = 23 after calling quux(), have $autovivified = 24 =for rperl X In RPerl, all variables are created using the C keyword, because it is the best choice: C variables are the least prone to cause errors, they are the easiest to convert into C++ output code, and they are the most optimizable. Also, because all RPerl code must utilize the C pragma, there is no autovivification of RPerl variables. RPerl does not support C variables, C variables, autovivified variables, or any kind other than C variables. =head3 Section 4.5.1: C Intermittent Variables You may recall we analyzed part of the C subroutine in L. This particular subroutine makes use of multiple C variables, the significance of which is discussed after the source code example. As promised, we will now review the full subroutine, for Perl operations & Perl data types mode: # stringify an integer_arrayref our string $integer_arrayref_to_string = sub { # require exactly one integer_arrayref as input, store in variable $input_avref ( my integer_arrayref $input_avref ) = @ARG; # declare local variables, av & sv mean "array value" & "scalar value" as used in Perl core my integer $input_av_length; my integer $input_av_element; my string $output_sv; my boolean $i_is_0 = 1; # compute length of (number of elements in) input array $input_av_length = scalar @{$input_avref}; # begin output string with left-square-bracket, as required for all RPerl arrays $output_sv = '['; # loop through all valid values of $i for use as index to input array for my integer $i ( 0 .. ( $input_av_length - 1 ) ) { # retrieve input array's element at index $i $input_av_element = $input_avref->[$i]; # append comma & space to output string for all elements except index 0 if ($i_is_0) { $i_is_0 = 0; } else { $output_sv .= ', '; } # stringify individual integer element, append to output string $output_sv .= integer_to_string($input_av_element); } # end output string with right-square-bracket, as required for all RPerl arrays $output_sv .= ']'; # return output string, containing stringified input array return $output_sv; }; The above subroutine's name is, unsurprisingly, C; it accepts exactly one input operand, an C accessed via the variable C<$input_avref>, and it generates as output a string formed in the variable C<$output_sv>. In addition to the input operand, the C subroutine defines four normal C variables: C<$input_av_length>, C<$input_av_element>, C<$output_sv>, and C<$i_is_0>. Also, the special loop iterator variable C<$i> is declared using the C keyword. The values of the four normal C variables are accessible only within this subroutine; in other words, they are locally-scoped AKA lexically-scoped variables. Any attempt to access or modify the values of the C<$input_av_length>, C<$input_av_element>, C<$output_sv>, or C<$i_is_0> variables outside the C subroutine will result in an error or undefined behavior. The value of the special loop iterator C<$i> has an even smaller scope, because it is only valid within the C loop body. The accepted terminology is to say that C<$i> is a I<"lexical loop iterator"> variable. Any attempt to utilize the C<$i> variable outside the loop body code block will result in an error or undefined behavior. This style of programming, where all variables are created using the C keyword, allows our code to undergo additional optimizations for memory usage, serial runtime performance, and parallel runtime performance. Thus, we always use lexically-scoped variables created using Perl's C keyword, in order to make our RPerl output code run as fast as possible. The string generated as output of the C subroutine is itself valid RPerl source code, and may be copied, pasted, and re-parsed by the RPerl compiler: my integer_arrayref $foo; $foo = [8, 23, 17]; print '$foo = ', integer_arrayref_to_string($foo), ';', "\n"; Running the code example above generates the following output string, which is itself an exact replica of the original line of valid RPerl source code: =for rperl X $foo = [8, 23, 17]; =for rperl X =head3 Section 4.5.2: Persistent State, Pseudo-State Variables RPerl does not support variables created using the magic C keyword. If you want to maintain a persistent state variable for one of your subroutines, then you may simply use the C keyword to declare a variable before calling the subroutine, pass the variable as a differently-named input argument to the subroutine, access and modify the variable while inside the subroutine, return the variable from the subroutine, receive the returned value back into the original variable, and repeat for as many times as you like. Each time your subroutine runs, it will be able to utilize the persistent state contained within your variable, even though you used the C keyword instead of the C keyword to declare the variable. We coin the term C<"pseudo-state variable"> to mean a low-magic C variable used to simulate the behavior of a high-magic C variable. our integer $foo = sub { ( my integer $pseudo_state_in_foo ) = @ARG; print 'inside foo(), received $pseudo_state_in_foo = ', $pseudo_state_in_foo, "\n"; $pseudo_state_in_foo++; print 'inside foo(), have modified $pseudo_state_in_foo = ', $pseudo_state_in_foo, "\n"; return $pseudo_state_in_foo; }; my integer $pseudo_state = 0; $pseudo_state = foo($pseudo_state); $pseudo_state = foo($pseudo_state); $pseudo_state = foo($pseudo_state); $pseudo_state = foo($pseudo_state); $pseudo_state = foo($pseudo_state); Outside the subroutine, we declare our variable with the expressive name C<$pseudo_state> as an indication of its purpose, although you may certainly choose to name your variable(s) differently. Inside the subroutine, we declare our variable with a different name, in this case C<$pseudo_state_in_foo>; by doing so, we remind ourselves these are truly two different variables with different scopes, and we also avoid any possible errors or unexpected behavior. The persistent variable is C<$pseudo_state>, because its value persists after each call to C returns. The non-persistent variable is C<$pseudo_state_in_foo>, because its value is accessible only inside each individual call to C. The trick to creating a pseudo-state variable is to make a connection between a persistent variable outside of a subroutine and a non-persistent variable inside the subroutine, as we have done in the example code above. Running the pseudo-state source code example above produces the following output: =for rperl X inside foo(), received $pseudo_state_in_foo = 0 inside foo(), have modified $pseudo_state_in_foo = 1 inside foo(), received $pseudo_state_in_foo = 1 inside foo(), have modified $pseudo_state_in_foo = 2 inside foo(), received $pseudo_state_in_foo = 2 inside foo(), have modified $pseudo_state_in_foo = 3 inside foo(), received $pseudo_state_in_foo = 3 inside foo(), have modified $pseudo_state_in_foo = 4 inside foo(), received $pseudo_state_in_foo = 4 inside foo(), have modified $pseudo_state_in_foo = 5 =for rperl X =head2 Section 4.6: C Pragmas & Magic We have already been exposed to the C and C source code components; these are both classified as Perl I<"pragmata"> AKA I<"pragma"> statements, which are special configuration controls used to change the way Perl itself functions. Both C and C pragmas appear in the header section of all RPerl programs: #!/usr/bin/env 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 # [[[ OPERATIONS ]]] print 'Howdy, Earth!', "\n"; Each of these pragma statements has multiple effects upon the Perl program for which they are enabled. The most pertinent outcome of the C statement is to disable variable autovivification, which is why there is no C pragmata in the autovivified example of L. The C pragma enables numerous helpful warning messages, which are an invaluable aid to the development of reliable and bug-free Perl software. In the case of warnings generated at compile time, RPerl will automatically cause such warnings to become fatal errors, and will provide as much information as possible to help you fix any issues before you try again. Utilizing these two pragmata statements is the first step toward disabling all of Perl's unnecessary and unwanted magic, which is cleverly hidden throughout every normal Perl program. This direct use of C and C occurs during RPerl's parse phase 0, which is the "Check Perl Syntax" phase. It is impossible to disable C and C in RPerl, as they are required to pass RPerl's parse phase 1 AKA "Criticize Perl Syntax", as well as parse phase 2 AKA "Parse RPerl Syntax". All true Perl Monks harken to the (wise?) words of our own Perl Prophet, The Voice In The Wilderness: =for rperl X Avoid Ye Coders The Programming Of Slack Use strict & warnings, That Ye Catch No Flak =for rperl X =head2 Section 4.7: Exercises =head3 1. Subroutine To Calculate Total Of Numeric Array Elements [ 45 mins ] In the same F directory from the the previous chapters' exercises, create a new sub-directory named (you guessed it!) F. In the new sub-directory, create an RPerl program file named F. Write an RPerl program which includes an array variable named C<$fred> containing the data C<[1, 3, 5, 7, 9]>. Add a subroutine named C which accepts as input a C and returns a C representing the sum total of all array elements. First, call C and display the results. Next, prompt the user to input as many numbers as they like, separated by and ended by , then store the results in an array and display the results of calling C on the array. Remember to use the C or C subroutines. Your program should generate exactly the following output, when provided with the corresponding input: =for rperl X $ rperl LearningRPerl/Chapter4/exercise_1-subroutine_total.pl The total of $fred is 25 Please input zero or more numbers, separated by , ended by : 8 23 17 The total of those numbers is 48 =for rperl X =head3 2. Subroutine To Calculate Total Of Numbers 1 Through 1_000 [ 15 mins ] In the F sub-directory, create an RPerl program file named F. Write an RPerl program which includes the same subroutine C from the previous exercise; you may copy-and-paste your own working source code, or re-write the subroutine from scratch, whichever you prefer. Create an array variable named C<$one_to_one_thousand>, and make use of the range C<..> operator to fill the variable with consecutive integers starting with C<1> and ending with C<1_000>. Call the subroutine and pass your variable as the input argument, then display the result. Your program should generate exactly the following output: =for rperl X $ rperl -t LearningRPerl/Chapter4/exercise_2-subroutine_total_1000.pl The total of 1 to 1000 is 500_500. =for rperl X =head3 3. Subroutine To Find Above-Average Array Elements [ 45 mins ] In the F sub-directory, create an RPerl program file named F. As in the previous exercise, write an RPerl program which includes the same subroutine C once again. Add a subroutine named C, which accepts a C as input argument and returns a C representing the arithmetic mean of the array elements; call the subroutine C from within C as part of calculating the mean value. Next, add another subroutine named C, which also accepts a C argument, and which returns a different C containing only the input array elements which are above the array's arithmetic mean; call the C subroutine from within C as part of your algorithm. Now, create an array variable named C<$fred>, and use the range C<..> operator to populate the array with the integers C<1> through C<10>. Display all the values in C<$fred>, then call C with C<$fred> as the input argument and display the results. Lastly, create another array variable named C<$barney>, and fill it with all the same values as C<$fred>, with the addition of the value C<100> added as the very first element (index 0) of C<$barney>. As before, display the values in the C<$barney> array, then pass it as the argument to C and display the results. Include some helpful hard-coded messages, to let your users know if the correct output is being generated. Your program should generate exactly the following output, when provided with the corresponding input: =for rperl X $ 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]) =for rperl X =head3 4. Subroutine To Greet User & Store Program State [ 30 mins ] In the F sub-directory, create an RPerl program file named F. Write an RPerl program which includes a subroutine named C, which accepts as input two C variables called C<$name> and C<$previous_name>, and which returns a single C variable. The C subroutine should say "Hi" to the person whose name has been passed in as an argument; if C<$previous_name> is an empty string then tell the person they are the first one, otherwise tell them who was the previous person to be greeted. Return the name of the person you have just greeted. Outside the subroutine, create another different (although identically-named) C variable called C<$previous_name>, and set its initial value to equal the empty string C. Call the C subroutine 4 times in a row with the following input names: C<'Fred'>, C<'Barney'>, C<'Wilma'>, and C<'Betty'>. Store the return value of each subroutine call back into the C<$previous_name> variable, and pass it as the second argument to each subsequent subroutine call. Your program should generate exactly the following output, when provided with the specified names: =for rperl X $ 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! =for rperl X =head3 5. Subroutine To Greet User & Store More Program State [ 35 mins ] In the F sub-directory, create an RPerl program file named F. As in the previous exercise, write an RPerl program which includes a new subroutine, also named C. This version of C accepts as input a C argument called C<$name>, as well as a C argument called C<$previous_names>. This C subroutine works similarly to the previous exercise, except it is capable of displaying multiple previous names, and it returns the C<$previous_names> array updated to include the latest person's C<$name>. Your program should generate exactly the following output, when provided with the same names as the previous exercise: =for rperl X $ 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 =for rperl X X
=head1 CHAPTER 5: READING & WRITING FILES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 6: HASH VALUES & VARIABLES A hash may not be a constant. types() introspection subroutine =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 7: THE REGULAR EXPRESSION SUB-LANGUAGE =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 8: MATCHING BY REGULAR EXPRESSIONS =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 9: PROCESSING BY REGULAR EXPRESSIONS =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 10: ADDITIONAL CONTROL STRUCTURES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 11: CLASSES, PACKAGES, MODULES, LIBRARIES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 12: TESTING FILES & DIRECTORIES =for comment [ INSERT CHAPTER ] =head3 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;)/ X
=head1 CHAPTER 13: MANIPULATING FILES & DIRECTORIES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 14: SORTING TEXT VALUES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 15: ADDITIONAL SPECIAL OPERATORS =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 16: MANAGING OPERATING SYSTEM PROCESSES =for comment [ INSERT CHAPTER ] X
=head1 CHAPTER 17: ADDITIONAL ADVANCED TECHNIQUES =for comment [ INSERT CHAPTER ] =head2 Section 17.1: SSE Data Structure & 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' =head3 Section 17.2: Misc & 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; # ADDITIONAL UNSORTED OPERATORS, HIDDEN FROM VIEW BELOW =begin comment %token OP01_NAMED_SCOLON = /(accept;|bind;|binmode;|bless;|break;|chmod;|chown;|closedir;|connect;|continue;|dbmclose; |dbmopen;|default;|dump;|each;|endgrent;|endhostent;|endnetent;|endprotoent;|endpwent;|endservent;|eof;|evalbytes;|exec;|fcntl;|fileno;|flock;|fork; |getc;|getgrent;|getgrgid;|getgrnam;|gethostbyaddr;|gethostent;|getlogin;|getnetbyaddr;|getnetent;|getpeername;|getppid;|getpriority; |getprotobynumber;|getprotoent;|getpwent;|getpwnam;|getpwuid;|getservbyname;|getservbyport;|getservent;|getsockname;|getsockopt;|given;|grep;|ioctl;|join; |keys;|kill;|link;|listen;|local;|map;|mkdir;|msgctl;|msgget;|msgrcv;|msgsnd;|opendir;|pipe;|prototype;|qx;|read;|readdir; |readline;|readpipe;|recv;|rename;|reset;|reverse;|rewinddir;|say;|seek;|seekdir;|select;|semctl;|semget;|semop;|send;|setgrent;|sethostent;|setnetent; |setpgrp;|setpriority;|setprotoent;|setpwent;|setservent;|setsockopt;|shmctl;|shmget;|shmread;|shmwrite;|shutdown;|socket;|socketpair;|sort;|splice;|split; |state;|symlink;|syscall;|sysopen;|sysread;|sysseek;|system;|syswrite;|tell;|telldir;|tie;|tied;|time;|times;|truncate;|unless;|unlink; |untie;|until;|utime;|values;|vec;|wait;|waitpid;|wantarray;|warn;|when;)/ %token OP10_NAMED_UNARY_SCOLON = /(alarm;|caller;|chdir;|chroot;|defined;|delete;|do;|eval;|exists;|gethostbyname;|getnetbyname;|getpgrp;|getprotobyname;|glob; |gmtime;|goto;|localtime;|lock;|lstat;|readlink;|ref;|require;|rmdir;|scalar;|sleep;|stat;|umask;)/ =end comment =head3 Section 17.3: Type Introspection C introspection subroutine X
=head1 APPENDIX A: EXERCISE ANSWERS =head2 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.X
The goal of this exercise is to become familiar with the boilerplate (often-repeated template) RPerl C
and C code sections, as well as the basic C operator.X
The first line, starting with C<#!> and called a "shebang", tells the operating system to run this program using Perl.X
The 4 lines in the C
section tell Perl to run this program using RPerl, and the C<$VERSION> number may be incremented for each update to this file.X
The line in the C section, starting with C<##>, tells RPerl to allow hard-coded numeric values (not used in this program), as well as the C operator.X
The last line, in the C section, calls the C operator on a comma-separated list consisting of 2 string literals, which will simply display the text "Hello, World!" followed by a newline character.X
All other lines beginning with C<#> are comments and, along with blank lines, may be safely ignored or removed.X
#!/usr/bin/env 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: =for rperl X $ rperl -t LearningRPerl/Chapter1/exercise_1-hello_world.pl Hello, World! =for rperl X X
=head2 Chapter 1, Exercise 2 The goal of this exercise is to become familiar with the C<`rperl`> command.X
X
Example execution and output for 2a and 2b: =for DEV NOTE, CORRELATION #rp029: all updates to `rperl` command-line arguments must be documented in script/rperl and 2 places in lib/RPerl/Learning.pm =for rperl X $ 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 magic=LOW ...OR... -m magic=LOW --mode magic=MEDIUM ...OR... -m magic=MEDIUM --mode magic=HIGH ...OR... -m magic=HIGH Specify magic mode, LOW by default. If set to LOW, accept low-magic (static) Perl source code in the source code input file(s). If set to MEDIUM, accept medium-magic (mostly static) Perl source code in the source code input file(s). If set to HIGH, accept high-magic (dynamic) Perl source code in the source code input file(s). Because only low-magic mode is supported at this time, this option does not currently have any effect. --mode code=PERL ...OR... -m code=PERL --mode code=CPP ...OR... -m code=CPP Specify source code mode, CPP by default. If set to PERL, generate Perl source code in the source code output file(s). If set to CPP, generate C++ source code in the source code output file(s). PERL operations mode forces PERL code mode; CPP operations mode forces CPP code mode. Because code mode is dependent upon operations mode, this option does not currently have any effect. --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. [[[ REMAINING ARGUMENTS OMITTED FOR BREVITY ]]] =for rperl X Example execution and output for 2c and 2d: =for rperl X $ 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! =for rperl X 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. X
=head2 Chapter 1, Exercise 3 The goal of this exercise is to become familiar with basic variables and arithmetic.X
The shebang line, C
section, and first line in the C section are the same boilerplate as the previous exercise.X
The second line in the C section tells RPerl to allow the C<$> (dollar) character, among others, to be displayed using the C operator.X
The first 3 lines in the C section each declare a new variable; C<$foo> and C<$bar> each hold an C (non-floating-point) numeric value, while C<$baz> holds a C (floating-point) value.X
The C<$foo> and C<$bar> variables receive their values from hard-coded numeric values being operated upon by the addition C<+> and multiplication C<*> operators, respectively; the C<$baz> and C<$zab> variables receive their values from the the C<$foo> and C<$bar> variables being operated upon by the division C operator. The C type conversion subroutine is necessary for the C++ compiler to use floating-point arithmetic instead of integer arithmetic on the division C operators, without it we would receive the truncated integer value of C<58> in C<$baz>, for example. We will receive the correct floating-point answers if we call C on either C<$bar> (as shown), or C<$foo>, or both; in other words, at least one of the input operands for each operator must be passed through C.X
The last 4 lines call the C 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 C; followed by a newline character.X
#!/usr/bin/env 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 1 The goal of this exercise is to become familiar with constant values.X
The first line in the C section tells RPerl to allow hard-coded numeric values as well as the C operator, both of which are utilized in this program.X
The second line in the C section tells RPerl to allow the C operation.X
The line in the C section declares a number (floating-point) constant value named C, automatically accessible via a subroutine named C.X
The inner type variable C<$TYPED_PI> is only used for RPerl parsing purposes; for example, if your constant is named C then you should declare it using the inner type variable C<$TYPED_FOO> and you should access it by calling the subroutine C, but you should never directly utilize the variable C<$TYPED_FOO> anywhere else in your code.X
The first 2 lines in the C section each create a new number variable, with C<$radius> set to the hard-coded value of C<12.5> and C<$circumference> set to the well-known basic geometry formula "circumference equals 2 pi times radius".X
The last 3 lines call the C operator to display the values of C, C<$radius>, and C<$circumference>, each followed by a newline character.X
#!/usr/bin/env 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 2 The goal of this exercise is to become familiar with accepting user keyboard input.X
The third line in the C section tells RPerl to allow user input via the CSTDINE> standard stream, a software input connection which is attached to the keyboard by default.X
The second line in the C section creates a string variable C<$radius_string>, and assigns to it the text value typed by the user on their keyboard.X
The third line in the C section creates a number variable C<$radius>, and assigns to it the numeric value returned by calling the RPerl type conversion subroutine C on the string variable C<$radius_string>.X
This exercise is otherwise identical to the previous exercise.X
#!/usr/bin/env 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 prompt # [[[ CONSTANTS ]]] use constant PI => my number $TYPED_PI = 3.141_592_654; # [[[ OPERATIONS ]]] print 'Please input radius: '; my string $radius_string = ; 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 3 The goal of this exercise is to become familiar with conditional statements and comparison operators.X
In the C section, the line starting with C= 0)> denotes the beginning of a conditional statement: if the numeric value of the variable C<$radius> is greater-than-or-equal-to 0, then the normal calculation for C<$circumference> is used; if C<$radius> is less-than 0 (physically impossible), then a warning message is printed and C<$circumference> is set to 0.X
This exercise is otherwise identical to the previous exercise.X
#!/usr/bin/env 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 prompt # [[[ CONSTANTS ]]] use constant PI => my number $TYPED_PI = 3.141_592_654; # [[[ OPERATIONS ]]] print 'Please input radius: '; my string $radius_string = ; 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 4 The goal of this exercise is to gain further exposure to the CSTDINE> standard stream and variable multiplication.X
In the C section, CSTDINE> is accessed to collect user input for both the C<$multiplicator_string> and C<$multiplicand_string> variables.X
These 2 string variables are converted from text values to numeric values by calling C, then multiplied via the C<*> multiplication operator, and the results displayed by calling C.X
#!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] print 'Please input multiplicator: '; my string $multiplicator_string = ; my number $multiplicator = string_to_number($multiplicator_string); print 'Please input multiplicand: '; my string $multiplicand_string = ; 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 5 The goal of this exercise is to become familiar with the C string repeat operator.X
In the C section, CSTDINE> is accessed twice to collect user input for a string variable C<$repeat_string> to be repeated, and an integer variable C<$repeat_integer> to specify the number of repetitions.X
The last line contains 2 operators, C and the C string repeat operator.X
Like the C<.> (single dot) string concatenation operator, the C operator has a higher precedence than C 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 C.X
#!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] print 'Please input string to be repeated: '; my string $repeat_string = ; print 'Please input integer (whole number) times to repeat string: '; my string $repeat_integer_string = ; my integer $repeat_integer = string_to_integer($repeat_integer_string); print "\n"; print $repeat_string x $repeat_integer; Example execution, input, and output: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 6 The goal of this exercise is to become familiar with the C loop control structure.X
In the C section, CSTDINE> is accessed to collect user input into the string variable C<$n_string>, then the data type conversion subroutine C is called to create the corresponding integer variable C<$n>.X
The C 0)> conditional control structure calls C to exit with an error message if C<$n> is not a positive value.X
Two additional integer variables are created: C<$sum> is initialized to 0 and will eventually hold the final answer value; and C<$i> is initialized to 0 for use as the iteration counter variable (AKA I<"iterator">) inside the following C loop control structure.X
The C loop iteratively executes as long as the integer value of C<$i> is less-than-or-equal-to C<$n>. Each iteration of the C loop causes the value of C<$sum> to be increased by C<$i>, after which C<$i> itself is incremented by 1, and the loop is repeated.X
The last line calls C, the C conversion subroutine, and the C<.> (single dot) string concatenation operator to display the final answer.X
#!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] print 'Please input a positive integer: '; my string $n_string = ; 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 2, Exercise 7 The goal of this exercise is to utilize an optimization to remove the C loop from the previous exercise.X
In the C section, user input is collected and error-checked, as before.X
By utilizing an algorithm attributed to Gauss, we are able to remove the C loop, so we also remove the C<$i> loop iterator. The C<$sum> variable is kept the same as the previous exercise.X
Two new integer variables are also created: C<$n_original> is initialized to hold a copy of C<$n> which will never change; and C<$n_odd> is initialized to 0.X
The code block beginning with C is used to detect if the user provided a value for C<$n> which is odd (not even), this is detected by utilizing the C<%> modulo operator to test for a remainder of dividing C<$n> by 2. If C<$n> is odd, then a second copy of the original value of C<$n> is stored in C<$n_odd>, after which C<$n> itself is decremented by 1. This C statement allows our algorithm to accept odd as well as even user input values for C<$n>.X
The computational kernel (most important part) is the one line of arithmetic: C<$sum = (($n + 1) * ($n / 2)) + $n_odd;>X
Recall the story of Gauss's algorithm in the exercise description; our arithmetic generalizes the idea of young Gauss by using C<$n> instead of 100, and by adding C<$n_odd> to enable support for odd values of C<$n>. Using Gauss' own example of C<$n> equal to 100, which is even (not odd) so C<$n_odd> will equal 0, we can see the algorithm becomes: C<$sum = ((100 + 1) * (100 / 2)) + 0;>X
One more step of arithmetic simplification shows our algorithm to be the same as Gauss': C<$sum = 101 * 50;>X
The last line calls C using the value of C<$n_original>, because the value of C<$n> will have been decreased by 1 if C<$n> is odd.X
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 C loop algorithm, expecially for very large values of C<$n>. It may be possible to further optimize this exercise by utilizing bitwise operators to replace the modulo and division operators.X
#!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] print 'Please input a positive integer: '; my string $n_string = ; 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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 3, Exercise 1 The goal of this exercise is to become familiar with the C loop control structure, arrays, and array operators; and to become further familiarized with the C loop.X
The first line in the C section declares a new variable C<$input_strings> of type C, which is capable of storing 0 or more individual string values, and C<$input_strings> is then initialized to contain the empty set C<[]>.X
The line starting with CSTDINE)> 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).X
A new copy of the variable C<$input_string> is created and assigned the value of collected user input by calling CSTDINE> at the start of each loop iteration; the C operator is evaluated as a true condition and the loop repeats, until CTRL-D is received and the C operator returns a false condition.X
Inside the body of the C loop is 1 line calling the C operator, which appends the current iteration's value of C<$input_string> onto the list of strings contained in C<$input_strings>.X
The at-sign-curly-braces C<@{ }> 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 C operator.X
The line starting with C declares another array of string values C, and then assigns it the strings contained within the first array C<$input_strings> in reversed order, as returned by calling the C operator.X
As with the C operator, the C operator requires its argument to be dereferenced using at-sign-curly-braces C<@{ }>; another dereferenced array value is returned by C, and an array reference is returned by enclosing C and its argument inside the square-brackets C<[ ]> array reference operator.X
Finally, the line starting with C denotes the beginning of another loop statement, which iterates the value of C<$input_strings_reversed_element> once for each string value contained in the C<$input_strings_reversed> array; C is called inside the loop body to display the original input strings in reverse order.X
#!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] my string_arrayref $input_strings = []; print 'Please input zero or more strings, separated by , ended by :', "\n"; while (my string $input_string = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter3/exercise_1-stdin_strings_reverse.pl Please input zero or more strings, separated by , ended by : howdy doody buffalo bob clarabell clown Strings in reverse order: clown clarabell bob buffalo doody howdy =for rperl X X
=head2 Chapter 3, Exercise 2 The goal of this exercise is to become familiar with utilizing array indices.X
The first line in the C section declares a new variable C<$flintstones_and_rubbles> of type C, which is then initialized to contain a C (quote word) set of names including the string element 'fred' at array index 0, 'betty' at array index 1, and so on.X
The second line in C creates an empty array of integers C<$input_indices>, and the following C loop uses the C operator to fill C<$input_indices> with integers entered by the user.X
The C loop iterates through all the user input integers, placing each in the variable C<$input_index>.X
Inside the C loop, the variable C<$input_index> is used to access the individual names inside the variable C<$flintstones_and_rubbles>.X
In Perl, all array indices start at 0 instead of 1, so we must first subtract 1 from C<$input_index> before accessing the individual string elements of C<$flintstones_and_rubbles>.X
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'.X
#!/usr/bin/env 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 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 , ended by :', "\n"; while ( my string $input_string = ) { 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: =for rperl X $ 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 , ended by : 2 5 3 6 5 1 2 7 4 4 Flintstones & Rubbles: betty wilma barney pebbles wilma fred betty bamm-bamm dino dino =for rperl X X
=head2 Chapter 3, Exercise 3 The goal of this exercise is to become familiar with the C and C operators.X
In the C section, a constant C is created and set to 0, which will cause the program's output to be displayed on multiple lines. If C is instead set to 1, the program's output will be displayed on one line.X
In the C section, a C loop is used to fill the array variable C<$input_strings> with data supplied by the user.X
The C operator is then called to fill the C<$input_strings_sorted> array with the same data in ASCII alphabetical order.X
Last, a C loop is used to print the sorted output by storing and accessing one string at a time in the variable C<$input_strings_sorted_element>.X
An C conditional statement inside the C loop tests the constant C; if the condition is true, then the C 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.X
#!/usr/bin/env 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 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 , ended by :', "\n"; while ( my string $input_string = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter3/exercise_3-stdin_strings_sort.pl Please input zero or more strings, separated by , ended by : howdy doody buffalo bob clarabell clown Strings in ASCIIbetical order: bob buffalo clarabell clown doody howdy =for rperl X X
=head2 Chapter 4, Exercise 1 The goal of this exercise is to become familiar with user-defined subroutines.X
In the C section, one subroutine C is defined, which accepts as input one argument variable C<$input_numbers> of type C, and which also has a C return value stored in the variable C<$retval>.X
Inside the C subroutine, the return value is initialized to 0 in C<$retval>, then a C loop iteratively adds the elements of the array C<$input_numbers> to C<$retval>, after which the value of C<$retval> is returned to original external caller of C.X
By itself, a subroutine such as C does not actually do anything; every subroutine must first be called either by some other subroutine or in the C section.X
In C, a 5-element array is created and stored in the variable C<$fred>, which is then passed as input to the subroutine C, and the return value is displayed using the variable C<$fred_total> and the C operator.X
Next, a C loop and CSTDINE> are used to collect user input strings, which are then converted to numeric data values using the C subroutine, and stored in the array C<$input_numbers> using the C operator.X
Finally, the subroutine C is called a second time, now with the variable C<$input_numbers> passed as the input argument, and the return value is displayed using the variable C<$user_total>.X
#!/usr/bin/env 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 prompt # [[[ SUBROUTINES ]]] our number $total = sub { (my number_arrayref $input_numbers) = @ARG; 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 , ended by :', "\n"; my number_arrayref $input_numbers = []; while (my string $input_string = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter4/exercise_1-subroutine_total.pl The total of $fred is 25 Please input zero or more numbers, separated by , ended by : 21.12 23.42 1701.877 -123.456 The total of those numbers is 1_622.961 =for rperl X X
=head2 Chapter 4, Exercise 2 The goal of this exercise is to become familiar with the C<..> range operator.X
In the C section, the same subroutine C is defined as in the previous exercise.X
In the C section, an array of numbers is created and stored in the variable C<$one_to_one_thousand>.X
Upon execution, there will be 1,000 number elements in the array, which are automatically created by the C<..> range operator.X
The actual elements stored the array variable C<$one_to_one_thousand> start with C<[1, 2, 3, 4> and end with C<997, 998, 999, 1_000]>.X
Finally, the subroutine C is called with C<$one_to_one_thousand> passed as the input argument, and the return value is displayed using the variable C<$one_to_one_thousand_total>.X
#!/usr/bin/env 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 ) = @ARG; 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: =for rperl X $ rperl -t LearningRPerl/Chapter4/exercise_2-subroutine_total_1000.pl The total of 1 to 1000 is 500_500. =for rperl X X
=head2 Chapter 4, Exercise 3 The goal of this exercise is to become familiar with calling user-defined subroutines from one another.X
In the C section, 3 subroutines are defined: C (same as previous exercises), C, and C.X
Inside the subroutine C is a call to the subroutine C; there is also a call to the C operator, which returns the count of elements inside the array C<$input_numbers>. When the return value of C is divided by that of C, the result is computation of the numeric mean (average) of all elements of C<$input_numbers>.X
Inside C is a call to the subroutine C, with the return value stored in the variable C<$average>. An empty array is created in the variable C<$retval>, then a C loop iterates over all elements in C<$input_numbers> and an C conditional statement makes a copy of all elements which are greater-than C<$average>. All above-average elements are returned as an array in C<$retval>.X
In the C section, 2 arrays are created in the C<$fred> and C<$barney> variables, which are then passed as input arguments to 2 calls to the subroutine C, and the results are displayed.X
#!/usr/bin/env 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 # [[[ SUBROUTINES ]]] our number $total = sub { ( my number_arrayref $input_numbers ) = @ARG; 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 ) = @ARG; return (total($input_numbers) / (scalar @{$input_numbers})); }; our number_arrayref $above_average = sub { ( my number_arrayref $input_numbers ) = @ARG; 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 number_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 number_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: =for rperl X $ 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]) =for rperl X X
=head2 Chapter 4, Exercise 4 The goal of this exercise is to become familiar with program state.X
As a program executes, there may be one or more variables in the C section which store information that is important to the overall program; these variables are collectively known as the I<"state"> of the program.X
In the C section, a string variable C<$previous_name> is created and set to the empty string C; this 1 variable is the state of the program.X
Each of the 4 following lines in the C section utilize the program state by both reading from and writing to the variable C<$previous_name>; the calls to the subroutine C read from C<$previous_name> as the 2nd argument, and the return value of C is then written to C<$previous_name> by the C<=> assignment operator.X
In the C section, 1 subroutine C is defined which accepts 2 string arguments, the variables C<$name> and C<$previous_name>.X
Inside C, a personalized greeting is displayed for the virtual person represented by the variable C<$name>, after which an C conditional statement checks if there is any data inside C<$previous_name> and further displays a customized comment about the state of the program. The state variable C<$previous_name> is used to represent the very simple state of virtual people who have already been greeted.X
Finally, the string variable C<$name> is returned from C and passed to the C<=> assignment operators in the C section, thereby updating the program state variable C<$previous_name> to contain the value of C<$name>.X
#!/usr/bin/env 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 ) = @ARG; 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: =for rperl X $ 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! =for rperl X X
=head2 Chapter 4, Exercise 5 The goal of this exercise is to become further familiarized with program state.X
In the C section, the state variable C<$previous_names> is an array of strings representing all previous virtual people who have been greeted.X
In the C section, the subroutine C prints the names of previously-greeted virtual people on one line, separated by spaces, by using the C operator.X
Finally, the current value of C<$name> is appended as the last element of the array C<$previous_names> by the C operator, and C<$previous_names> is then returned by C to update the program state.X
#!/usr/bin/env 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 ) = @ARG; 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: =for rperl X $ 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 =for rperl X X
=head2 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.X
In the C section, the C critic is disabled due to a bug in Perl::Critic and/or PPI which causes a false error.X
In the C section, 1 subroutine C is defined which accepts as input an array of file names received via the operating system's command-line arguments, and which has a C return value, meaning there is no return value for this subroutine.X
Inside C, the C operator is called to reverse the order of the command-line arguments; for example, if the 3 file names C are given as command-line arguments, then C causes the 3 strings C to be stored in the array variable C<$command_line_arguments>.X
The outer C loop iterates through each C<$file_name> in the now-reversed C<$command_line_arguments>.X
Next, 4 file test operators are called, to ensure each input file exists via C<-e>, is readable via C<-r>, is a regular (not special device) file via C<-f>, and is comprised of plain text via C<-T>.X
The operator C is called with the C> file input (read-only) argument, which opens each C<$file_name> for reading via the C<$FILE> filehandle variable.X
The inner C loop reads in all lines from the current C<$FILE> filehandle using the C$FILEE> syntax (similar to CSTDINE>) and stores the input file's lines in the string array variable C<$file_lines>; then, the C operator is called again to reverse the order of the newly-read file lines.X
Finally, the inner C loop displays the now-reversed C<$file_lines>, and the C operator is called to close the C<$FILE> filehandle so no more file access will occur for the current C<$file_name>.X
In the C section, the C subroutine is called with its only argument being a reference to the special C<@ARGV> array, which is Perl's way of accessing the command-line arguments.X
Before executing this program, the non-Perl C<`printf`> program must be called to populate some test data into the 3 input files F, F, and F; and after execution the C<`rm`> program is called to delete the 3 input files.X
To begin execution of this program via the C<`rperl`> command, the program name and input file names must be enclosed in either C<'single-quotes'> or C<"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.X
#!/usr/bin/env 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 ) = @ARG; $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: =for rperl X $ 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 =for rperl X X
=head2 Chapter 5, Exercise 2 The goal of this exercise is to become familiar with the string C operator and basic text formatting.X
In the C section, 1 subroutine C is defined, which accepts no input arguments and returns no values.X
Inside C, an empty array of strings is initialized in the C<$input_strings> variable, which is then populated with strings in a C loop collecting user input from CSTDINE>.X
The C string repeat operator is called to create a 60-character-wide horizontal ruler, which is then displayed by the C operator.X
Finally, a C loop iterates through each C<$input_string> and calls the C operator, thereby determining the correct number of spaces to prepend in order to achieve right justification alignment to the 20th character column. The C<-> subtraction operator is passed a hard-coded column width of 20, and the C operator is called to remove any trailing newline characters which may be appended when the user presses the ENTER key after each input word.X
In the C section, the only operation is a call to the C subroutine.X
X
#!/usr/bin/env 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 prompt # [[[ SUBROUTINES ]]] our void $right_justify_20 = sub { my string_arrayref $input_strings = []; print 'Please input zero or more strings, separated by , ended by :', "\n"; while ( my string $input_string = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter5/exercise_2-right_justify.pl Please input zero or more strings, separated by , ended by : howdy doody buffalo bob clarabell clown 123456789012345678901234567890123456789012345678901234567890 howdy doody buffalo bob clarabell clown =for rperl X X
=head2 Chapter 5, Exercise 3 The goal of this exercise is to become further familiarized with basic text formatting.X
In the C section, 1 subroutine C is defined, which accepts no input arguments and returns no values.X
Inside C, the user is prompted to input a custom right justify width, stored in the integer variable C<$column_width>.X
The integer variable C<$ruler_width_tens> is used to determine the number of characters displayed for the ruler, by tens; the default value for C<$ruler_width_tens> is 6, which means a ruler width of 60 characters. If the user-supplied C<$column_width> is greater-than 60, we scale it by 1/10 and add 1, thereby creating a new value for C<$ruler_width_tens> which will always display a ruler wider than C<$column_width>.X
When the ruler is displayed, C<$ruler_width_tens> is passed to the C string repeat operator instead of a hard-coded value of 6; likewise, when each C<$input_string> is right justified, the C<-> subtraction operator is passed C<$column_width> instead of a hard-coded value of 20.X
In the C section, the only operation is a call to the C subroutine.X
This exercise is otherwise identical to the previous exercise.X
#!/usr/bin/env 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 prompt # [[[ SUBROUTINES ]]] our void $right_justify_variable = sub { my string_arrayref $input_strings = []; print 'Please input integer column width, then press :', "\n"; my string $column_width_string = ; my integer $column_width = string_to_integer($column_width_string); print 'Please input zero or more strings, separated by , ended by :', "\n"; while ( my string $input_string = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter5/exercise_3-right_justify_variable.pl Please input integer column width, then press : 67 Please input zero or more strings, separated by , ended by : howdy doody buffalo bob clarabell clown 1234567890123456789012345678901234567890123456789012345678901234567890 howdy doody buffalo bob clarabell clown =for rperl X X
=head2 Chapter 6, Exercise 1 The goal of this exercise is to become familiar with hash data structures and hash operators.X
In the C section, 1 subroutine C is defined, which accepts no input arguments and returns no values.X
Inside C, a hash data structure is created in the variable C<$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 C<$names> are fred, barney, and wilma; the value of the key fred is 'flintstone'.X
A first name is collected from the user by CSTDINE> and stored in C<$given_name>, then the C operator is called to remove the trailing newline recorded when the user presses the ENTER key.X
An C conditional statement calls the C and C operators to ensure the user has entered a valid hash key, and an error is returned if there is no such key in the C<$names> hash.X
Finally, the thin-arrow syntax C<$names-E{$given_name}> is used to retrieve the hash value, and C is called to display the family name outputs.X
In the C section, the only operation is a call to the C subroutine.X
#!/usr/bin/env 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 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 :', "\n"; my string $given_name = ; 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: =for rperl X $ rperl -t LearningRPerl/Chapter6/exercise_1-hash_family_names.pl Please input a given (first) name in all lowercase, then press : 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 : howdy ERROR: No family (last) name found for given (first) name howdy, croaking =for rperl X X
=head2 Chapter 6, Exercise 2 The goal of this exercise is to become further familiarized with hash data structures and hash operators.X
In the C section, 1 subroutine C is defined, which accepts no input arguments and returns no values.X
In C, an empty hash of integer values is created in the variable C<$word_counts>; a C loop then collects user input strings, inside of which an C conditional statement updates the C<$word_counts> hash. If a word is seen for the first time, then the corresponding C<$word_counts> hash value will be set to 1, otherwise the count value will be incremented by 1.X
Finally, a C loop iterates through the alphabetically-sorted keys of the C<$word_counts> hash by calling the C and C operators, then the thin-arrow hash value retrieval syntax C<$word_counts-E{$unique_word}> is called, and the C operator displays the word count outputs.X
In the C section, the only operation is a call to the C subroutine.X
#!/usr/bin/env 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 prompt # [[[ SUBROUTINES ]]] our void $unique_word_count = sub { my integer_hashref $word_counts = {}; print 'Please input zero or more words, separated by , ended by :', "\n"; while (my string $input_word = ) { 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: =for rperl X $ rperl -t LearningRPerl/Chapter6/exercise_2-hash_unique_word_count.pl Please input zero or more words, separated by , ended by : 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) =for rperl X X
=head2 Chapter 6, Exercise 3 The goal of this exercise is to become further familiarized with hash data structures and basic text formatting.X
In the C section, 1 subroutine C is defined, which accepts no input arguments and returns no values.X
Inside C, a hash of strings is created in the variable C<$env_vars>, and it is initialized to contain the values of the special C<%ENV> system hash, which stores the current user's environmental variables.X
Next, 2 integer variables C<$env_var_length> and C<$left_column_width> are created, and C<$left_column_width> is initialized to the value 0. A C loop iterates through all environmental variables, measuring the string length of each C<$env_var> by the C operator, and using an C conditional statement to test if the current C<$env_var_length> is greater-than the existing C<$left_column_width>. If C<$env_var_length> is large enough, then C<$left_column_width> is updated, thereby resulting in the value of C<$left_column_width> being equal to the longest C<$env_var_length>.X
After the C loop, C<$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.X
Finally, there is another C loop below the first, again iterating through all C<$env_vars>, and printing the keys at the beginning of each output line. The C<-> subtraction operator is called to find the difference between the current key length and the pre-calculated C<$left_column_width>, then the C 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 C<$env_vars-E{$env_var}> is called, and the C operator displays the hash value outputs.X
In the C section, the only operation is a call to the C subroutine.X
#!/usr/bin/env 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: =for rperl X $ 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 =for rperl X X
=for DEV NOTE, CORRELATION #rp029: all updates to `rperl` command-line arguments must be documented in script/rperl and 2 places in lib/RPerl/Learning.pm =head1 APPENDIX B: RPERL COMMAND-LINE ARGUMENTS The C<`rperl`> I<"command-line interface"> (CLI) is a software program which serves as the primary front-end user interface for RPerl. When called for execution, the C<`rperl`> command must be provided with at least one input file name, which tells RPerl which file(s) to compile. In addition, C<`rperl`> may also be provided with one or more optional I<"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 I<"options">, or in this specific context just I<"arguments">. Command-line arguments which are listed as one of the I<"modes"> will modify the way RPerl compiles the input source code file(s). All RPerl modes are written using the longhand format: C<--mode foo=BAR> Arguments which are listed as one of the I<"flags"> are written using the shorthand C<--foo> or even shorter C<-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 S> command. Additional explanations for each argument are provided I =head2 B.1: Help =over =item B<--help ...OR... -h ...OR... -?> =for rperl X Print this (relatively) brief help message for command-line usage. For additional explanations, run the command `perldoc RPerl::Learning` and see Appendix B. =for rperl X I I =back =head2 B.2: Version =over =item B<--version ...OR... -v> =item B<--vversion ...OR... -vv> =for rperl X 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. =for rperl X I command.> I 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.> =back =head2 B.3: Input Files =over =item B<--infile=MyFile.pm ...OR... -i=MyFile.pm> =for rperl X 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. =for rperl X I command is fully executed (not just C<`rperl -?`>, C<`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.> I =back =head2 B.4: Output Files =over =item B<--outfile=MyCompiledModule ...OR... -o=MyCompiledModule> =item B<--outfile=my_compiled_program ...OR... -o=my_compiled_program> =for rperl X 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). =for rperl X I I provided, the same 'foo.pl' input file will instead generate the 'bar.cpp' and 'bar' (or 'bar.exe') output files.> =back =head2 B.5: C++ Compiler =over =item B<--CXX=/path/to/compiler> =for rperl X 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. =for rperl X I I> I =back =head2 B.6: Modes, Magic =over =item B<--mode magic=LOW ...OR... -m magic=LOW> =item B<--mode magic=MEDIUM ...OR... -m magic=MEDIUM> =item B<--mode magic=HIGH ...OR... -m magic=HIGH> =for rperl X Specify magic mode, LOW by default. If set to LOW, accept low-magic (static) Perl source code in the source code input file(s). If set to MEDIUM, accept medium-magic (mostly static) Perl source code in the source code input file(s). If set to HIGH, accept high-magic (dynamic) Perl source code in the source code input file(s). Because only low-magic mode is supported at this time, this option does not currently have any effect. =for rperl X I I =back =head2 B.7: Modes, Code =over =item B<--mode code=PERL ...OR... -m code=PERL> =item B<--mode code=CPP ...OR... -m code=CPP> =for rperl X Specify source code mode, CPP by default. If set to PERL, generate Perl source code in the source code output file(s). If set to CPP, generate C++ source code in the source code output file(s). PERL operations mode forces PERL code mode; CPP operations mode forces CPP code mode. Because code mode is dependent upon operations mode, this option does not currently have any effect. =for rperl X I I I =back =head2 B.8: Modes, Operations =over =item B<--mode ops=PERL ...OR... -m ops=PERL> =item B<--mode ops=CPP ...OR... -m ops=CPP> =for rperl X 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. =for rperl X I I I =back =head2 B.9: Modes, Types =over =item B<--mode types=PERL ...OR... -m types=PERL> =item B<--mode types=CPP ...OR... -m types=CPP> =item B<--mode types=DUAL ...OR... -m types=DUAL> =for rperl X 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. =for rperl X I I I =back =head2 B.10: Modes, Integer Type =over =item B<--mode type_integer=LONG ...OR... -m type_integer=LONG> =item B<--mode type_integer=LONG__LONG ...OR... -m type_integer=LONG__LONG> =for rperl X 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. =for rperl X I I I =back =head2 B.11: Modes, Number Type =over =item B<--mode type_number=DOUBLE ...OR... -m type_number=DOUBLE> =item B<--mode type_number=LONG__DOUBLE ...OR... -m type_number=LONG__DOUBLE> =for rperl X 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. =for rperl X I I I I =back =head2 B.12: Modes, Type Checking =over =item B<--mode check=OFF ...OR... -m check=OFF> =item B<--mode check=ON ...OR... -m check=ON> =item B<--mode check=TRACE ...OR... -m check=TRACE> =for rperl X 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. =for rperl X I I I =back =head2 B.13: Modes, Dependencies =over =item B<--mode dependencies=OFF ...OR... -m dependencies=OFF> =item B<--mode dependencies=ON ...OR... -m dependencies=ON> =for rperl X 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. =for rperl X I 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.> I I =back =head2 B.14: Modes, Uncompile =over =item B<--mode uncompile=OFF ...OR... -m uncompile=OFF> =item B<--mode uncompile=SOURCE ...OR... -m uncompile=SOURCE> =item B<--mode uncompile=BINARY ...OR... -m uncompile=BINARY> =item B<--mode uncompile=INLINE ...OR... -m uncompile=INLINE> =item B<--mode uncompile=SOURCE_BINARY ...OR... -m uncompile=SOURCE_BINARY> =item B<--mode uncompile=SOURCE_BINARY_INLINE ...OR... -m uncompile=SOURCE_BINARY_INLINE> =for rperl X 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. =for rperl X I I I =back =head2 B.15: Modes, Compile =over =item B<--mode compile=OFF ...OR... -m compile=OFF> =item B<--mode compile=PARSE ...OR... -m compile=PARSE> =item B<--mode compile=GENERATE ...OR... -m compile=GENERATE> =item B<--mode compile=SAVE ...OR... -m compile=SAVE> =item B<--mode compile=SUBCOMPILE ...OR... -m compile=SUBCOMPILE> =for rperl X 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). =for rperl X I I I =back =head2 B.16: Modes, Subcompile =over =item B<--mode subcompile=OFF ...OR... -m subcompile=OFF> =item B<--mode subcompile=ASSEMBLE ...OR... -m subcompile=ASSEMBLE> =item B<--mode subcompile=ARCHIVE ...OR... -m subcompile=ARCHIVE> =item B<--mode subcompile=SHARED ...OR... -m subcompile=SHARED> =item B<--mode subcompile=STATIC ...OR... -m subcompile=STATIC> =item B<--mode subcompile=DYNAMIC ...OR... -m subcompile=DYNAMIC> =for rperl X 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). =for rperl X I I I I I I> =back =head2 B.17: Modes, C++ Compiler =over =item B<--mode CXX=/path/to/compiler ...OR... -m CXX=/path/to/compiler> =for rperl X Specify path to C++ compiler for use in subcompile modes, equivalent to '--CXX=/path/to/compiler' or 'CXX' manual Makefile argument, 'g++' by default. =for rperl X I I is strongly recommended, although in theory you should be able to use any C++ compiler which supports the C++11 standard.> L =back =head2 B.18: Modes, Parallelize =over =item B<--mode parallel=OFF ...OR... -m parallel=OFF> =item B<--mode parallel=OPENMP ...OR... -m parallel=OPENMP> =item B<--mode parallel=MPI ...OR... -m parallel=MPI> ((( COMING SOON!!! ))) =item B<--mode parallel=OPENCL ...OR... -m parallel=OPENCL> ((( COMING SOON!!! ))) =for rperl X Specify automatic parallelization mode, OFF 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. =for rperl X I I I I =back =head2 B.19: Modes, Parallelize, Number Of Cores =over =item B<--mode num_cores=2 ...OR... -m num_cores=2 ...OR... --num_cores=2 ...OR... -num=2> =item B<--mode num_cores=4 ...OR... -m num_cores=4 ...OR... --num_cores=4 ...OR... -num=4> =item B<--mode num_cores=8 ...OR... -m num_cores=8 ...OR... --num_cores=8 ...OR... -num=8> =item B<...ETC...> =for rperl X Specify number of CPU cores to utilize for OPENMP automatic parallelization mode, 4 by default. =for rperl X I I I =back =head2 B.20: Modes, Execute =over =item B<--mode execute=OFF ...OR... -m execute=OFF> =item B<--mode execute=ON ...OR... -m execute=ON> =for rperl X 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. =for rperl X I I I =back =head2 B.21: Modes, Source Code Labels =over =item B<--mode label=OFF ...OR... -m label=OFF> =item B<--mode label=ON ...OR... -m label=ON> =for rperl X 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. =for rperl X I =back =head2 B.22: Flags, Verbose =over =item B<--Verbose ...OR... -V> =item B<--noVerbose ...OR... -noV> =for rperl X 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. =for rperl X I I RPerl system subroutine.> I L =back =head2 B.23: Flags, Debug =over =item B<--Debug ...OR... -D> =item B<--noDebug ...OR... -noD> =for rperl X 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. =for rperl X I I & C RPerl system subroutines.> I is recommended for RPerl system developers.> =back =head2 B.24: Flags, Warnings =over =item B<--Warnings ...OR... -W> =item B<--noWarnings ...OR... -noW> =for rperl X Include system warnings in output, or not. If disabled, equivalent to `export RPERL_WARNINGS=0` shell command. Enabled by default. =for rperl X I I =back =head2 B.25: Flags, Test =over =item B<--test ...OR... -t> =for rperl X 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. =for rperl X I =back =head2 B.26: Flags, Low Magic =over =item B<--low ...OR... -l> =for rperl X Accept low-magic (static) Perl source code in the source code input file(s). Enabled by default, equivalent to '--mode magic=LOW' argument. Because only low-magic mode is supported at this time, this option does not currently have any effect. =for rperl X I I> =back =head2 B.27: Flags, Medium Magic =over =item B<--medium> =for rperl X Accept medium-magic (mostly static) Perl source code in the source code input file(s). Disabled by default, equivalent to '--mode magic=MEDIUM' argument. Because only low-magic mode is supported at this time, this option does not currently have any effect. Shorthand '-m' used for '--mode' argument, not '--medium' argument. =for rperl X I I> =back =head2 B.28: Flags, High Magic =over =item B<--high> =for rperl X Accept high-magic (dynamic) Perl source code in the source code input file(s). Disabled by default, equivalent to '--mode magic=HIGH' argument. Because only low-magic mode is supported at this time, this option does not currently have any effect. Shorthand '-h' used for '--help' argument, not '--high' argument. =for rperl X I I> =back =head2 B.29: Flags, Dependencies =over =item B<--dependencies ...OR... -d> =item B<--nodependencies ...OR... -nod> =for rperl X 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. =for rperl X I I> =back =head2 B.30: Flags, Uncompile =over =item B<--uncompile ...OR... -u> =item B<--nouncompile ...OR... -nou> =item B<--uuncompile ...OR... -uu> =item B<--nouuncompile ...OR... -nouu> =item B<--uuuncompile ...OR... -uuu> =item B<--nouuncompile ...OR... -nouuu> =for rperl X 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. =for rperl X I I> =back =head2 B.31: Flags, Compile =over =item B<--compile ...OR... -c> =item B<--nocompile ...OR... -noc> =for rperl X Generate & subcompile C++ source code, or not. Enabled by default, equivalent to '--mode compile=SUBCOMPILE' argument. =for rperl X I I or C<-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.> I> =back =head2 B.32: Flags, Subcompile, Assemble =over =item B<--assemble> =for rperl X 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. =for rperl X I I> =back =head2 B.33: Flags, Subcompile, Archive =over =item B<--archive> =for rperl X 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. =for rperl X I I> =back =head2 B.34: Flags, Subcompile, Shared Object =over =item B<--shared> =for rperl X 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. =for rperl X I I> =back =head2 B.35: Flags, Subcompile, Static =over =item B<--static> =item B<--nostatic> =for rperl X 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. =for rperl X I I flag, because dynamic subcompile mode is already the default behavior.> I> =back =head2 B.36: Flags, Parallelize =over =item B<--parallel ...OR... -p> =item B<--noparallel ...OR... -nop> =for rperl X Automatically parallelize input code, or not. Disabled by default. Equivalent to '--mode parallel=OPENMP' argument. =for rperl X I I> =back =head2 B.37: Flags, Execute =over =item B<--execute ...OR... -e> =item B<--noexecute ...OR... -noe> =for rperl X 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. =for rperl X I I> =back =head1 APPENDIX C: RPERL CRITICS =for comment [ START HERE: need add content and descriptions to all critics below ] =for comment [ START HERE: need add content and descriptions to all critics below ] =for comment [ START HERE: need add content and descriptions to all critics below ] =for rperl X # 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 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 @ARG ## 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 =for rperl X =head1 APPENDIX D: RPERL GRAMMAR =head2 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 F contains the uncompiled RPerl grammar, which is passed through the C<`eyapp`> compiler command once to generate the output file F, which is then used by the C<`rperl`> compiler command to parse RPerl input source code files. Inside the F file, there are several labeled file sections, which can be grouped into 4 major categories: =over 16 =item * Eyapp Setup & Config At the top of the F file, the C<[[[ EYAPP SETUP & CONFIG ]]]> section contains Perl 5 code to initialize RPerl within the special percent-signs-and-curly-braces C<%{ }%> delimiters, as well as the C<%strict> and C<%tree> Eyapp configuration directives for automatically building an abstract syntax tree (AST) from an RPerl input file. =item * Lexicon Near the top of the F file, multiple C<[[[ LEXICON TOKENS ... ]]]> sections contain all valid RPerl tokens in the form of Perl 5 regular expressions. The lexicon of a language is synonymous with the language's alphabet and vocabulary; lexical analysis is synonymous with spell checking. =item * Syntax In the middle of the F file, one C<[[[ SYNTAX, OPERATOR PRECEDENCE & ASSOCIATIVITY ]]]> section and multiple C<[[[ SYNTAX PRODUCTION RULES ... ]]]> sections define all relationships between all RPerl tokens, as well as all valid combinations of RPerl tokens. The syntax of a language is synonymous with the rules of constructing valid sentences, and syntactic analysis is synonymous with grammar checking. =item * Semantics Near the top of the F file, the C<[[[ SEMANTIC ACTION, ABSTRACT SYNTAX TREE NODE CONSTRUCTOR ]]]> section creates new Perl 5 objects (blessed hash references) to be used as nodes when constructing an AST; at the bottom of the file, the C<[[[ SEMANTIC MAP, ABSTRACT SYNTAX TREE NODES TO CLASSES ]]]> section contains a 1-to-1 mapping from AST nodes to RPerl objects. The Perl module file for each of the RPerl objects contains subroutines implementing the semantic actions which actually generate and/or execute output code. The semantics of a language are synonymous with the meaning of words and sentences; in computer programming languages, semantic actions are the tasks which the computer source code performs when executed. =back For more information, please view the following links: =over 16 =item * L =item * L =item * L =back =head2 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 I<"lexical matching">, and is distinct from operator precedence and associativity as covered in the next section. =head3 D.2.1: Whitespace C<[[[ LEXICON TOKENS, WHITESPACE ]]]> =over 16 =item * actual whitespace, or one or more normal comments; neither shebang C<#!>, nor double-hash critics C<##> =back =head3 D.2.2: Types & Reserved Words C<[[[ LEXICON TOKENS, TYPES & RESERVED WORDS ]]]> =over 16 =item * SHEBANG begin line, hash (octothorpe), bang, *NIX path to Perl; ex. C<#!/usr/bin/env perl> =item * USE_RPERL C =item * USE_RPERL_AFTER C =item * USE C =item * VERSION_NUMBER_ASSIGN $VERSION assign v-number, only capture v-number, not a normal number; ex. C<$VERSION = 12.345_678;> returns C<12.345_678> =item * MY C =item * LITERAL_NUMBER number with underscores, optional scientific notation; ex. C<12_345_678.910_1> =item * LITERAL_STRING single-quotes non-empty; double-quotes non-empty without sigils or extra backslashes & with newline or tab; or single q-braces; ex. C<'howdy $foo!'> or C<"howdy foo!\n"> or C =item * SELF C<$self> =item * VARIABLE_SYMBOL dollar sigil, scoped word with at least one lowercase in the first scope segment; ex. C<$foo> or C<$Foo::Bar::baz> =item * FHREF_SYMBOL_IN less-than, dollar sigil, uppercase letter, uppercase letters & numbers & underscores, greater-than; ex. C$MY_FILEHANDLE_23E> =item * FHREF_SYMBOL_BRACES left brace, dollar sigil, uppercase letter, uppercase letters & numbers & underscores, right brace; ex. C<{$MY_FILEHANDLE_23}> =item * FHREF_SYMBOL dollar sigil, uppercase letter, uppercase letters & numbers & underscores; ex. C<$MY_FILEHANDLE_23> =item * TYPE_INTEGER C or C followed by whitespace =item * TYPE_FHREF C followed by whitespace =item * TYPE_METHOD optionally-scoped word, followed by '::method'; ex. C or C =item * CONSTANT_CALL_SCOPED optionally-scoped constant call; ex. C or C =item * WORD_SCOPED optionally-scoped word; ex. C or C or C =item * STDOUT_STDERR C<{*STDOUT}> or C<{*STDERR}> =item * STDIN CSTDINE> =item * ARGV C<@ARGV> =item * ENV C<%ENV> =back =head3 D.2.3: Operators C<[[[ LEXICON TOKENS, OPERATORS ]]]> =over 16 =item * OP24_LOGICAL_OR_XOR precedence 24 infix: logical C and C, equivalent to C<||> except for precedence =item * OP23_LOGICAL_AND precedence 23 infix: logical C, equivalent to C<&&> except for precedence =item * OP22_LOGICAL_NEG precedence 22 prefix: logical negation C, equivalent to C except for precedence =item * OP21_LIST_COMMA precedence 21 infix: "list operators (rightward)" [1] AKA comma C<,> =item * OP20_HASH_FATARROW precedence 20 infix: hash entry fat-arrow AKA fat-comma C<=E> =item * OP19_LOOP_CONTROL_SCOLON precedence 19 prefix void: loop control C, C =item * OP19_LOOP_CONTROL precedence 19 prefix void: same as above, except allows C and requires loop label =item * OP18_TERNARY precedence 18 infix: ternary conditional C =item * OP17_LIST_RANGE precedence 17 infix: range C<..> =item * OP16_LOGICAL_OR precedence 16 infix: logical or C<||> =item * OP15_LOGICAL_AND precedence 15 infix: logical and C<&&> =item * OP14_BITWISE_OR_XOR precedence 14 infix: bitwise or C<|>, bitwise xor C<^> =item * OP13_BITWISE_AND precedence 13 infix: bitwise and C<&> =item * OP12_COMPARE_EQ_NE precedence 12 infix: comparison numeric equal C<==>, numeric not equal C, string equal C, string not equal C =item * OP09_BITWISE_SHIFT precedence 09 infix: bitwise shift left CE>, shift right CE> =item * OP10_NAMED_UNARY_SCOLON precedence 10 prefix: "named unary operators" [1] and Programming Perl, Chapter 3, List of All Named Unary Operators; C<-A;>, C<-B;>, C<-C;>, C<-M;>, C<-O;>, C<-R;>, C<-S;>, C<-T;>, C<-W;>, C<-X;>, C<-b;>, C<-c;>, C<-d;>, C<-e;>, C<-f;>, C<-g;>, C<-k;>, C<-l;>, C<-o;>, C<-p;>, C<-r;>, C<-s;>, C<-t;>, C<-u;>, C<-w;>, C<-x;>, C<-z;>, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C =item * OP10_NAMED_UNARY same as above, except without semicolon; C not C =item * OP19_VARIABLE_ASSIGN_BY precedence 19 infix: add assign C<+=>, subtract assign C<-=>, multiply assign C<*=>, divide assign C, string concatenation assign C<.=> =item * OP08_STRING_CAT precedence 08 infix: string concatenate C<.> =item * OP03_MATH_INC_DEC precedence 03 prefix and postfix: increment C<++>, decrement C<--> =item * OP04_MATH_POW precedence 04 infix: arithmetic exponent AKA power C<**> =item * OP07_MATH_MULT_DIV_MOD precedence 07 infix: arithmetic multiply C<*>, divide C, modulo C<%>, SSE multiply C, SSE divide C =item * OP07_STRING_REPEAT precedence 07 infix: string repetition C =item * OP06_REGEX_PATTERN precedence 06 infix: regular expression pattern; ex. C or C =item * OP06_REGEX_BIND precedence 06 infix: regular expression match C<=~>, not match C =item * OP05_LOGICAL_NEG precedence 05 prefix: logical negation C =item * OP02_HASH_THINARROW precedence 02 infix: thin-arrow, hash dereference and retrieval C<-E{> =item * OP02_ARRAY_THINARROW precedence 02 infix: thin-arrow, array dereference and retrieval C<-E[> =item * OP02_METHOD_THINARROW_NEW precedence 02 infix: thin-arrow, class constructor C<-Enew(> =item * OP02_METHOD_THINARROW precedence 02 infix: thin-arrow, method dereference and call; ex. C<-Efoo> or C<-EBar23> =item * OP05_MATH_NEG_LPAREN precedence 05 prefix: arithmetic negative C<-(> =item * OP08_MATH_ADD_SUB precedence 08 infix: arithmetic add C<+>, subtract C<->, SSE add C, SSE subtract C =item * OP11_COMPARE_LT_GT precedence 11 infix: numeric comparison less-or-equal C=>, greater-or-equal C=>, less-than C>, greater-than C>; string comparison less-or-equal C, greater-or-equal C, less-than C, greater-than C =item * OP19_VARIABLE_ASSIGN precedence 19 infix: assign C<=> =item * OP01_PRINT precedence 01 prefix void: C or C to STDOUT, STDERR, or filehandle =item * OP01_NAMED_VOID_SCOLON precedence 01 prefix void: "terms and list operators (leftward)" [1] AKA built-ins, no return value; C, C, C, C =item * OP01_NAMED_VOID_LPAREN precedence 01 prefix void: same as above, except with parentheses & without semicolon & without die; C, C, C =item * OP01_NAMED_VOID precedence 01 prefix void: same as above, except accepts argument(s); C, C, C, C =item * OP01_QW precedence 01 prefix: quote word; ex. C or C or C =item * OP01_OPEN precedence 01 prefix: C filehandle =item * OP01_CLOSE precedence 01 prefix: C filehandle =item * OP01_NAMED_SCOLON precedence 01 prefix: "terms and list operators (leftward)" [1] AKA built-ins; L [2]; without all-uppercase Perl system built-in keywords (C<__DATA__>, C, C, etc); named unary operators above (C, C, etc); and RPerl keywords (C, C, C, C, C, etc); C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C =item * OP01_NAMED same as above, except without semicolon =back =head3 D.2.4: Punctuation & User-Defined Words C<[[[ LEXICON TOKENS, PUNCTUATION & USER-DEFINED WORDS ]]]> =over 16 =item * COLON C<:> =item * LPAREN_MY C<(my> =item * LPAREN C<(> =item * LBRACKET C<[> =item * LBRACE C<{> =item * WORD lowercase letter followed by optional word characters; or uppercase letter followed by at least one lowercase letter and optional word characters; ex. C or C or C =item * WORD_UPPERCASE single uppercase letter, or uppercase letter followed by uppercase letters, numbers, and underscores; ex. C or C =back =head2 D.3: Syntax Arity, Fixity, Precedence, Associativity Operator I<"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 subroutine. An operator or function which accepts 0 input arguments is known as I<"nullary">, 1 argument as I<"unary">, 2 arguments as I<"binary">, 3 arguments as I<"ternary">, and so forth. The C operator may be called as nullary; the C<++> increment operator is unary; the C<+> addition operator is binary; and the C 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 I<"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 I<"variadic">. Some RPerl operators are variadic, such as C which may accept 2, 3, or 4 arguments. RPerl does not currently support variadic user-defined subroutine. L Operator I<"fixity"> is the notation form indicating the location of an operator when placed relative to its own input operands. I<"Prefix"> operators are located before their operands, I<"infix"> between operands, and I<"postfix"> after operands. Additionally, operators which must be placed both before and after their operands are said to be of I<"closed"> fixity (AKA I<"closefix">), while operators capable of more than one placement location are called I<"mixfix">. Prefix notation is also known as I<"Polish notation">, and postfix is called I<"Reverse Polish"> notation. The C absolute value is a prefix operator; the C<+> addition operator is infix; and the C<++> increment operator can be called as postfix. The C<-( )> 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 C<-> negative (without parentheses) is a prefix operator, but in RPerl we only allow the closed fixity C<-( )> negative-with-parentheses operator in order to avoid grammar ambiguity, because the same C<-> dash (AKA hyphen) character is utilized for both the C<-> negative and C<-> subtraction operators. The C<++> increment operator may also be called as prefix, so it may be classified as mixfix. L L L Operator I<"precedence">, also known as I<"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 C<*> arithmetic multiplication operator has a precedence number of 7, and C<+> addition has a precedence of 8, so C is equivalent to C, not C<(a + b) * c>. L Operator I<"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 C is equivalent to C<(a - b) - c>, not C. Some operators such as mathematic power (AKA exponentiation) are right-associative, meaning C is equivalent to C. Operators which are not meant to be chained together are non-associative, such as the C<..> list range operator which takes scalar values as input but generates an array as output, so C is incorrect usage and will cause an error. L In the following list of operators copied directly from F, 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 F.) All operator arity, fixity, precedence, and associativity are taken directly from Perl 5. L [1] C<[[[ SYNTAX, OPERATOR PRECEDENCE & ASSOCIATIVITY ]]]> =for rperl X %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_BIND %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 =for rperl X =head2 D.4: Syntax Production Rules The EBNF metasyntax implemented by Eyapp is of the form: C In this example, C is a non-terminal left-hand-side (LHS) symbol, is followed by the C<:> 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 C<|> 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 C<'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, C in this example. =head3 D.4.1: File Formats C<[[[ SYNTAX PRODUCTION RULES, FILE FORMATS ]]]> =for rperl X 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 '@ARG;' ; 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 '@ARG;' ; MethodOrSubroutine: Method | Subroutine; =for rperl X B I =over 16 =item * L L #!/usr/bin/env perl # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OPERATIONS ]]] my integer $i = 2 + 2; =item * L L #!/usr/bin/env 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 # [[[ INCLUDES ]]] use RPerl::Test::Module::Class_00_Good; # [[[ OPERATIONS ]]] my RPerl::Test::Module::Class_00_Good $foo = RPerl::Test::Module::Class_00_Good->new(); my RPerl::Test::Module::Class_00_Good $bar = RPerl::Test::Module::Class_00_Good->new(); print 'have $foo->{empty_property} = ', $foo->{empty_property}, "\n"; print 'have $bar->{empty_property} = ', $bar->{empty_property}, "\n"; print '...', "\n"; $foo->{empty_property} = 23; print 'have $foo->{empty_property} = ', $foo->{empty_property}, "\n"; print 'have $bar->{empty_property} = ', $bar->{empty_property}, "\n"; L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Module::Package_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ SUBROUTINES ]]] our void $empty_sub = sub { return 2; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Module::Class_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ OO PROPERTIES ]]] our hashref $properties = { empty_property => my integer $TYPED_empty_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our void::method $empty_method = sub { return 2; }; 1; # end of class =item * L =item * L =item * L L #!/usr/bin/env perl ## 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 # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ CRITICS ]]] ## no critic qw(ProhibitUselessNoCritic) # [[[ OPERATIONS ]]] my integer $i = 2 + 2; L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Critic::Package_00_Good; 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 $empty_sub = sub { return 2; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Critic::Class_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ CRITICS ]]] ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls) # USER DEFAULT 1: allow numeric values & print operator # [[[ OO PROPERTIES ]]] our hashref $properties = { empty_property => my integer $TYPED_empty_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our void::method $empty_method = sub { return 2; }; 1; # end of class =item * L L #!/usr/bin/env perl # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ INCLUDES ]]] use RPerl::Test::Foo; use RPerl::Test::Bar; # [[[ OPERATIONS ]]] my integer $i = 2 + 2; L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Include::Package_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ INCLUDES ]]] use RPerl::Test::Foo; use RPerl::Test::Bar; # [[[ SUBROUTINES ]]] our integer $empty_sub = sub { return 2; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Include::Class_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ INCLUDES ]]] use RPerl::Test::Foo; use RPerl::Test::Bar; # [[[ OO PROPERTIES ]]] our hashref $properties = { empty_property => my integer $TYPED_empty_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our integer::method $empty_method = sub { return 2; }; 1; # end of class =item * L L #!/usr/bin/env perl # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ CONSTANTS ]]] ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers) # USER DEFAULT 3: allow constants use constant PI => my number $TYPED_PI = 3.141_59; use constant PIE => my string $TYPED_PIE = 'pecan'; # [[[ OPERATIONS ]]] my integer $i = 2 + 2; L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Constant::Package_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ CONSTANTS ]]] ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers) # USER DEFAULT 3: allow constants use constant PI => my number $TYPED_PI = 3.141_59; use constant PIE => my string $TYPED_PIE = 'pecan'; # [[[ SUBROUTINES ]]] our void $empty_sub = sub { return 2; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Constant::Class_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ CONSTANTS ]]] ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers) # USER DEFAULT 3: allow constants use constant PI => my number $TYPED_PI = 3.141_59; use constant PIE => my string $TYPED_PIE = 'pecan'; # [[[ OO PROPERTIES ]]] our hashref $properties = { empty_property => my integer $TYPED_empty_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our void::method $empty_method = sub { return 2; }; 1; # end of class =item * L =item * L L # [[[ HEADER ]]] use RPerl; package RPerl::Test::SubroutineArguments::Package_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ SUBROUTINES ]]] our void $empty_sub = sub { ( my number $foo ) = @ARG; return 1; }; 1; # end of package =back I =over 16 =item * L L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: '92' >>> # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.000_010; # [[[ CRITICS ]]] ## no critic qw(ProhibitUselessNoCritic ProhibitMagicNumbers RequireCheckedSyscalls) # USER DEFAULT 1: allow numeric values & print operator # [[[ INCLUDES ]]] use RPerl::Test::Properties::Class_00_Good; # [[[ OPERATIONS ]]] # set and get object property ourself # using direct access to blessed $property hashref, breaking object encapsulation my RPerl::Test::Properties::Class_00_Good $test_object = RPerl::Test::Properties::Class_00_Good->new(); $test_object->{test_property} = 4; $test_object->test_method(23); print $test_object->{test_property}, "\n"; L # [[[ HEADER ]]] use RPerl; package RPerl::Test::Properties::Class_00_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ OO PROPERTIES ]]] our hashref $properties = { test_property => my integer $TYPED_test_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our void::method $test_method = sub { ( my object $self, my integer $input_integer ) = @ARG; $self->{test_property} *= $input_integer; return $self->{test_property}; }; 1; # end of class =item * L =item * L L # [[[ HEADER ]]] use RPerl; package RPerl::Test::MethodArguments::Class_01_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OO INHERITANCE ]]] use parent qw(RPerl::Test); use RPerl::Test; # [[[ OO PROPERTIES ]]] our hashref $properties = { empty_property => my integer $TYPED_empty_property = 2 }; # [[[ SUBROUTINES & OO METHODS ]]] our void::method $empty_method = sub { ( my object $self, my integer $foo ) = @ARG; return 2; }; 1; # end of class =back =head3 D.4.2: Operations C<[[[ SYNTAX PRODUCTION RULES, OPERATIONS ]]]> =for rperl X 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_BIND 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+ '}' ; =for rperl X B I =over 16 =item * L L #!/usr/bin/env 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 $i = 0; $i++; L #!/usr/bin/env 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 ]]] our integer $foo = sub { return 23; }; foo(); L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: '1.570795' >>> # [[[ 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 # [[[ INCLUDES ]]] use RPerl::Test::Foo; # [[[ OPERATIONS ]]] my number $pi_over_2 = RPerl::Test::Foo::PI() / 2; print 'pi / 2 = ', $pi_over_2, "\n"; L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: "'a' => 'twenty-threetwenty-threetwenty-threetwenty-threetwenty-threetwenty-threetwenty-three'" >>> # <<< EXECUTE_SUCCESS: "'b' => 'howdy'" >>> # <<< EXECUTE_SUCCESS: "'c' => '-23.42'" >>> # <<< EXECUTE_SUCCESS: "'a' => 'guffawguffawguffawguffawguffawguffawguffawguffawguffawguffawguffaw'" >>> # <<< EXECUTE_SUCCESS: "'b' => 'howdy'" >>> # <<< EXECUTE_SUCCESS: "'c' => '-23.42'" >>> # [[[ 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 # [[[ INCLUDES ]]] use RPerl::Test::Foo; # [[[ OPERATIONS ]]] my RPerl::Test::Foo $my_foo = RPerl::Test::Foo->new(); print Dumper($my_foo->qorge(7)), "\n"; $my_foo->{xyzzy} = 'guffaw'; print Dumper($my_foo->qorge(11)), "\n"; L #!/usr/bin/env 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 $foo = 9_123.456_789; my number_arrayref $bar = [ 21, 12, 43.23, 987.654_321 ]; my string $bat = number_to_string($foo); my string $baz = ::number_arrayref_to_string($bar); my string $bax = ::string_arrayref_to_string( [ 'abc', '123', 'lalala' ] ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = ::integer_hashref_to_string( { foo => 23, bar => 56, quux => 123_456 } ); $baz = ::number_hashref_to_string( { foo => 23.4, bar => 56.789, quux => 123_456.789_012 } ); $bax = ::string_hashref_to_string( { foo => 'howdy', bar => 'dowdy', quux => 'doo' } ); print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $op_sin = sin 2; my number $op_cos = cos 2; my integer_arrayref $frob = []; my integer $frob_length = ( push @{$frob}, 21, 12, 23 ); # Operator, yes parentheses required for built-in w/ multiple arguments in non-void context print 'have $frob_length = ', $frob_length, "\n"; print 'have $frob = ', "\n", Dumper($frob), "\n"; my integer $frob_pop = pop @{$frob}; print 'have $frob_pop = ', "\n", $frob_pop, "\n"; print 'have $frob = ', "\n", Dumper($frob), "\n"; L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] wait; L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] my unknown $op_wait = wait; =item * L L #!/usr/bin/env 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 $foo = chdir; my integer $bar = chdir 'INVALID__DIRECTORY__NAME'; my number $bat = rand; my number $baz = rand 10; my number $bax = rand 30; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; my integer_arrayref $quux = [ 5, 6, 7, 8 ]; $foo = scalar @{$quux}; $bar = scalar @{ [] }; $bat = scalar @{ [0] }; $baz = scalar @{ [ 0, 1, 2, 3, 4, 5, 6, 7 ] }; $bax = scalar @{ [ 0 .. 22 ] }; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] chdir; =item * L L #!/usr/bin/env 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 ]]] if (1) { print 'Production rule Statement matched by Conditional', "\n"; } L #!/usr/bin/env 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 ]]] for my integer $i ( -1 .. 1 ) { print 'Production rule Statement matched by Loop, iteration number ', $i, "\n"; } L #!/usr/bin/env 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 ]]] foreach my number $my_number ( 11.1, 22.2, 33.3, 44.4 ) { print 'Production rule Statement matched by Loop, iteration item ', $my_number, "\n"; } L #!/usr/bin/env 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 $i = 10; FOOBARLOOP: while ( $i < 23 ) { print 'Production rule Statement matched by Loop, iteration number ', $i, "\n"; $i += 2; if ( $i > 18 ) { last FOOBARLOOP; } } L #!/usr/bin/env 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 ]]] print 'Production rule Statement matched by OperatorVoid', "\n"; L #!/usr/bin/env 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 = 'Production rule Statement matched by VariableDeclaration'; L #!/usr/bin/env 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 = 'Production rule Statement matched by'; $foo .= ' VariableModification'; =back I =over 16 =item * L L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] # USER NOTE: the Operator (not OperatorVoid) production rule matched by 'print' requires parentheses and filehandle my integer $open_success = open my filehandleref $HOWDY, '>', '/tmp/howdy'; if ( not $open_success ) { croak 'ERROR: Failed to open file /tmp/howdy for writing, croaking'; } # USER NOTE: return values of Operator print are purposefully ignored here, possibly ignoring write errors ( print {$HOWDY} 2 ); ( print {$HOWDY} 2, 3, 4, "\n" ); ( print {$HOWDY} 2.31 ); ( print {$HOWDY} 2.31, 3.21, 4.23, "\n" ); ( print {$HOWDY} 'howdy' ); ( print {$HOWDY} 'howdy', 'doody', 'foobar', "\n" ); ( print {$HOWDY} 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n" ); # USER NOTE: return values of Operator print are utilized here, catching write errors # long format, 2 RPerl Operations my integer $print_success = ( print {$HOWDY} 2 ); if ( not $print_success ) { croak 'ERROR: Failed to write to file /tmp/howdy, croaking'; } # short format, 1 RPerl Operation if (not( print {$HOWDY} 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n" ) ) { croak 'ERROR: Failed to write to file /tmp/howdy, croaking'; } if ( not close $HOWDY ) { croak 'ERROR: Failed to close file /tmp/howdy after writing, croaking'; } =item * L L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] my integer $open_success = open my filehandleref $HOWDY, '>', '/tmp/howdy'; if ( not $open_success ) { croak 'ERROR: Failed to open file /tmp/howdy for writing, croaking'; } my integer $print_success = ( print {$HOWDY} 23, 32, 42 ); if ( not $print_success ) { croak 'ERROR: Failed to write to file /tmp/howdy, croaking'; } if ( not close $HOWDY ) { croak 'ERROR: Failed to close file /tmp/howdy after writing, croaking'; } =item * L L #!/usr/bin/env 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 $foo = 2; my integer $bar = 3; $foo++; my integer $bat = $foo++; $bar--; my integer $baz = $bar--; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; ++$foo; $bat = ++$foo; --$bar; $baz = --$bar; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; =item * L L #!/usr/bin/env 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 $foo = 2**3; my integer $bar = 3**2; my integer $bat = $foo**$bar; my integer $baz = $bar**$foo; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; $foo = 2; $bar = 3; $bat = ( $foo**2 )**$bar; $baz = $foo**( 2**$bar ); my integer $bax = $foo**2**$bar; # right associative print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 0; my integer $bar = 1; my integer $bat = !$foo; my integer $baz = !($bar); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; $foo = 2; $bar = 3; $bat = !2; # returns empty string '' $baz = !( $foo - $bar ); # returns empty string '' my integer $bax = !!$foo; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 3; my integer $bar = -3; # Literal Number, not Operator my integer $bat = -(3); # Operator(Literal Number) my integer $baz = 5 - -($bar); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; $foo = -(-3); # Operator(Literal Number) $bar = -( -(3) ); # Operator(Operator(Literal Number)) $bat = $foo + -($bar); $baz = $foo - -($bar); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; =item * L L #!/usr/bin/env 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 hello ahoy'; my integer $bar = $foo =~ m/owdy/msx; my integer $bat = ( $foo =~ m/Hello/msx ); my integer $baz = ( $foo =~ m/\s[Aa]hoy$/msx ); my integer $bax = ( $foo =~ s/ho/HO/gms ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $foo = 'Alpha Bravo Charlie 123'; $bar = ( $foo !~ m/owdy/msx ); $bat = ( $foo !~ m/ravo/msx ); $baz = ( $foo !~ m/\s[Cc]harlie\s\d*$/msx ); $bax = ( $foo !~ s/ha/HAHA/gms ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: "have $foo = ''" >>> # <<< EXECUTE_SUCCESS: "have $bar = 'bar'" >>> # <<< EXECUTE_SUCCESS: "have $bat = 'batbat'" >>> # <<< EXECUTE_SUCCESS: "have $baz = 'bazbazbazbaz'" >>> # <<< EXECUTE_SUCCESS: "have $bax = 'baxbaxbaxbaxbaxbaxbaxbax'" >>> # [[[ 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 = 'foo' x 0; my string $bar = 'bar' x 1; my string $bat = 'bat' x 2; my string $baz = 'baz' x 4; my string $bax = 'bax' x 8; print q{have $foo = '}, $foo, q{'}, "\n"; print q{have $bar = '}, $bar, q{'}, "\n"; print q{have $bat = '}, $bat, q{'}, "\n"; print q{have $baz = '}, $baz, q{'}, "\n"; print q{have $bax = '}, $bax, q{'}, "\n"; =item * L L #!/usr/bin/env 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 $foo = 222 * -33; my number $bar = 222 / 33; my number $bat = 222 % 33; my number $baz = $foo % $bar * $bat / 4; my number $bax = $foo % ( $bar * ( $bat / 4 ) ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 222 + 33; my number $bar = 222 - 33; my number $bat = 222 + -33; my number $baz = $foo - $bar + $bat - 4; my number $bax = $foo - ( $bar + ( $bat - 4 ) ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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' . 'doody'; my string $bar = 'hello' . ('and' . 'goodbye'); my string $bat = ('ahoy' . 'matey') . 'yarr'; my string $baz = $foo . $bar . $bat; my string $bax = $foo . $foo . $foo; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 1_024; my integer $bar = 256; my integer $bat = 4_096 << 3; my integer $baz = $foo << 3; my integer $bax = $bar >> 4; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo < 22; my integer $baz = 22 < $foo; my integer $bax = 33 <= 44; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $foo > 333_333_333_333; $baz = 444 >= 222; $bax = 9_123.456_789 >= $foo; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar lt 'ahoy'; $baz = 'ZZZZZZZZZZZZZZ' lt $bar; $bax = '33' le '44'; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar gt 'abc'; $baz = '144' ge '222'; $bax = 'howdy' ge $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo == 22; my integer $baz = 9_123.456_789 == $foo; my integer $bax = 33 != 44; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $foo == 333_333_333_333; $baz = 444 != 222; $bax = 33 != $foo; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar eq 'howdy'; $baz = 'ZZZZZZZZZZZZZZ' eq $bar; $bax = '33' ne '44'; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar eq 'abc'; $baz = '444' ne '222'; $bax = '33' ne $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo & 22; my integer $baz = 9_123.456_789 & $foo; my integer $bax = 33 & 44; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar & 'abc'; $baz = '444' & '222'; $bax = '33' & $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo | 22; my integer $baz = 9_123.456_789 | $foo; my integer $bax = 33 ^ 44; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar | 'abc'; $baz = '444' ^ '222'; $bax = '33' ^ $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo && 22; my integer $baz = 9_123.456_789 && $foo; my integer $bax = 33 && 0; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar && q{}; $baz = '444' && '222'; $bax = '33' && $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = $foo || 22; my integer $baz = 9_123.456_789 || $foo; my integer $bax = 33 || 0; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = $bar || q{}; $baz = '444' || '222'; $bax = '33' || $bar; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 123; my string $bar = 'ab'; my integer_arrayref $bat; $bat = [ $foo .. 22 ]; my integer_arrayref $baz; $baz = [ 22 .. $foo ]; my integer_arrayref $bax; $bax = [ 0 .. 23 ]; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', ::integer_arrayref_to_string($bat), "\n"; print 'have $baz = ', ::integer_arrayref_to_string($baz), "\n"; print 'have $bax = ', ::integer_arrayref_to_string($bax), "\n"; my string_arrayref $bat2; $bat2 = [ $bar .. 'ac' ]; my string_arrayref $baz2; $baz2 = [ 'a2' .. 'a4' ]; my string_arrayref $bax2; $bax2 = [ 'a' .. $bar ]; print 'have $bat2 = ', ::string_arrayref_to_string($bat2), "\n"; print 'have $baz2 = ', ::string_arrayref_to_string($baz2), "\n"; print 'have $bax2 = ', ::string_arrayref_to_string($bax2), "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my number $bar = 2_112; my number $bat = ( 22 > 21 ) ? $foo : $bar; my number $baz = 0 ? $foo : $bar; my number $bax = 1 ? 99.9 : 100.1; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = ( 'howdy' ne 'dowdy' ) ? $foo : 22_222.33; $baz = ( 4 <= 4 ) ? 88 : $bar; $bax = ( 88 > 99 ) ? 21 : 12; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 0; my integer $bar = 1; my integer $bat = not $foo; my integer $baz = not ($bar); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; $foo = 2; $bar = 3; $bat = not 2; # returns empty string '' $baz = not ( $foo - $bar ); # returns empty string '' my integer $bax = not not $foo; print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = ($foo and 22); my integer $baz = (9_123.456_789 and $foo); my integer $bax = (33 and 0); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = ($bar and q{}); $baz = ('444' and '222'); $bax = ('33' and $bar); print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =item * L L #!/usr/bin/env 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 $foo = 9_123.456_789; my string $bar = 'howdy'; my integer $bat = ( $foo or 22 ); my integer $baz = ( 9_123.456_789 or $foo ); my integer $bax = ( 33 xor 0 ); print 'have $foo = ', $foo, "\n"; print 'have $bar = ', $bar, "\n"; print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; $bat = ( $bar or q{} ); $baz = ( '444' xor '222' ); $bax = ( '33' xor $bar ); print 'have $bat = ', $bat, "\n"; print 'have $baz = ', $baz, "\n"; print 'have $bax = ', $bax, "\n"; =back I =over 16 =item * L L #!/usr/bin/env 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 # [[[ OPERATIONS ]]] # USER NOTE: the OperatorVoid (not Operator) production rule matched by 'print' has optional STDOUT, STDERR, or filehandle print 2; print 2, 3, 4, "\n"; print 2.31; print 2.31, 3.21, 4.23, "\n"; print 'howdy'; print 'howdy', 'doody', 'foobar', "\n"; print 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n"; print {*STDOUT} 2; print {*STDOUT} 2, 3, 4, "\n"; print {*STDOUT} 2.31; print {*STDOUT} 2.31, 3.21, 4.23, "\n"; print {*STDOUT} 'howdy'; print {*STDOUT} 'howdy', 'doody', 'foobar', "\n"; print {*STDOUT} 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n"; print {*STDERR} 2; print {*STDERR} 2, 3, 4, "\n"; print {*STDERR} 2.31; print {*STDERR} 2.31, 3.21, 4.23, "\n"; print {*STDERR} 'howdy'; print {*STDERR} 'howdy', 'doody', 'foobar', "\n"; print {*STDERR} 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n"; my integer $open_success = open my filehandleref $HOWDY, '>', '/tmp/howdy'; if ( not $open_success ) { croak 'ERROR: Failed to open file /tmp/howdy for writing, croaking'; } # USER NOTE: return values of OperatorVoid print-to-filehandle are always ignored, possibly ignoring write errors print {$HOWDY} 2; print {$HOWDY} 2, 3, 4, "\n"; print {$HOWDY} 2.31; print {$HOWDY} 2.31, 3.21, 4.23, "\n"; print {$HOWDY} 'howdy'; print {$HOWDY} 'howdy', 'doody', 'foobar', "\n"; print {$HOWDY} 'howdy', 2.31, 'doody', 3.21, 'foobar', 4.23, "\n"; if ( not close $HOWDY ) { croak 'ERROR: Failed to close file /tmp/howdy after writing, croaking'; } =item * L L #!/usr/bin/env 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_arrayref $frob = []; push @{$frob}, 21, 12, 23; # OperatorVoid, no parentheses required for built-in w/ multiple arguments in void context print 'have $frob = ', "\n", Dumper($frob), "\n"; =item * L L #!/usr/bin/env 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 ]]] croak; =item * L L #!/usr/bin/env 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 ]]] die "\n"; =item * L L #!/usr/bin/env 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 ]]] exit; =item * L L #!/usr/bin/env 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 # [[[ SUBROUTINES ]]] # DEV NOTE: DO NOT RUN PERLTIDY ON THIS FILE! the line below should read 'return();' not 'return ();' our void $foo = sub { return(); }; # [[[ OPERATIONS ]]] foo(); =item * L L #!/usr/bin/env 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 ]]] HOWDYLOOP: while (1) { next HOWDYLOOP; } =back I =over 16 =item * L L #!/usr/bin/env perl # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ CONSTANTS ]]] ## no critic qw(ProhibitConstantPragma ProhibitMagicNumbers) # USER DEFAULT 3: allow constants use constant PI => my number $TYPED_PI = 3.141_59; use constant PIE => my string $TYPED_PIE = 'pecan'; # [[[ OPERATIONS ]]] my integer $i = 2 + 2; =back I =over 16 =item * L L #!/usr/bin/env 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 $foo = undef; L #!/usr/bin/env 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_hashref $foo = { puppet => 'howdy doody', host => 'buffalo bob', sidekick => 'clarabell clown' }; keys %{$foo}; =item * L L # [[[ HEADER ]]] use RPerl; package RPerl::Test::LiteralNumber::Package_30_Good; 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 $empty_sub = sub { return 0.234_567_89; }; 1; # end of package =item * L L # [[[ HEADER ]]] use RPerl; package RPerl::Test::LiteralString::Package_DoubleQuotes_10_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ SUBROUTINES ]]] our string $empty_sub = sub { return "{foo}\n"; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::LiteralString::Package_QQuotes_07_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ SUBROUTINES ]]] our string $empty_sub = sub { return q{@ $}; }; 1; # end of package L # [[[ HEADER ]]] use RPerl; package RPerl::Test::LiteralString::Package_SingleQuotes_07_Good; use strict; use warnings; our $VERSION = 0.001_000; # [[[ SUBROUTINES ]]] our string $empty_sub = sub { return '@ $'; }; 1; # end of package =item * L L #!/usr/bin/env 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 ]]] # homogeneous 2-dimensional array of arrays, using inner types my arrayref_arrayref $array_array = [ my integer_arrayref $TYPED_array_array_0 = [ 17, -23, 1_701 ], my integer_arrayref $TYPED_array_array_1 = [ -1, 444, 2_987 ], my integer_arrayref $TYPED_array_array_2 = [ -321, 7, 24_851 ] ]; foreach my arrayref $array ( @{$array_array} ) { print '$array = ', Dumper($array), "\n"; } L #!/usr/bin/env 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_arrayref $s_array = ['buffalo', qw(alpha beta gamma), 'howdy']; foreach my string $s ( @{$s_array} ) { print '$s = ', $s, "\n"; } =item * L L #!/usr/bin/env 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 ]]] foreach my integer $i ( @{ [ 10, 20, 30, 40, 50 ] } ) { print '$i = ', $i, "\n"; } L #!/usr/bin/env 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 ]]] foreach my integer $i ( @{ my integer_arrayref $TYPED_i_array = [ 10, 20, 30, 40, 50 ] } ) { print '$i = ', $i, "\n"; } L #!/usr/bin/env 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 ]]] foreach my integer $i ( @{ [ my integer $TYPED_i0 = 10, 20, 30, 40, 50 ] } ) { print '$i = ', $i, "\n"; } =item * L L #!/usr/bin/env 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 ]]] # homogeneous 2-dimensional hash of hashes, using inner types my hashref_hashref $hash_hash = { key_0 => my integer_hashref $TYPED_key_0 = { a => 17, b => -23, c => 1_701 }, key_1 => my integer_hashref $TYPED_key_1 = { d => -1, e => 444, f => 2_987 }, key_2 => my integer_hashref $TYPED_key_2 = { g => -321, h => 7, i => 24_851 } }; print Dumper($hash_hash); L #!/usr/bin/env 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 $key_number = 0.1; my string $key_string = '0.1'; my hashref $unknown_hash = { key0 => my integer $TYPED_key0 = -23, 0 => my number_arrayref $TYPED_zero = [ 42 / 1_701, 21.12, 2_112.23 ], 0.1 => my string_hashref $TYPED_zerodotone = { 'alpha' => 'strings are scalars, too', 12.345_678 => 'hello world', gamma => 'last one' }, '0.1' => 'replacement', "0.1\n" => 'close but not quite', $key_number => 'another replacement', $key_string => 'final replacement' }; print Dumper($unknown_hash); =item * L L #!/usr/bin/env 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 ]]] foreach my string $key ( sort keys %{ { a => 10, b => 20, c => 30, d => 40, e => 50 } } ) { print '$key = ', $key, "\n"; } L #!/usr/bin/env 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 ]]] foreach my string $key ( sort keys %{ my integer_hashref $TYPED_i_hash = { a => 10, b => 20, c => 30, d => 40, e => 50 } } ) { print '$key = ', $key, "\n"; } L #!/usr/bin/env 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 ]]] foreach my string $key ( sort keys %{ { a => my integer $TYPED_a = 10, b => 20, c => 30, d => 40, e => 50 } } ) { print '$key = ', $key, "\n"; } L #!/usr/bin/env 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 ]]] foreach my string $key ( sort keys %{ my integer_hashref $TYPED_i_hash = { a => my integer $TYPED_a = 10, b => 20, c => 30, d => 40, e => 50 } }) { print '$key = ', $key, "\n"; } =back I =over 16 =item * L L #!/usr/bin/env 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 prompt # [[[ OPERATIONS ]]] my string $foo; $foo = ; =back I =over 16 =item * L L #!/usr/bin/env 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 ]]] if (0) { print 'yes if', "\n"; } elsif (0) { print 'yes elsif 0', "\n"; } elsif (0) { print 'yes elsif 1', "\n"; } else { print 'yes else', "\n"; } =item * L L #!/usr/bin/env 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 ]]] TESTFORLOOP: for my unsigned_integer $i ( 0 .. 4 ) { print 'Production rule Loop matched by LoopFor, iteration number ', $i, "\n"; if ( $i > 1 ) { last TESTFORLOOP; } } L #!/usr/bin/env 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 ]]] TESTFOREACHLOOP: foreach my number $my_number ( 1.1, 2.2, 3.3, 4.4 ) { if ( $my_number == 3.3 ) { next TESTFOREACHLOOP; } print 'Production rule Loop matched by LoopForEach, iteration item ', $my_number, "\n"; } L #!/usr/bin/env 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 $i = 0; TESTWHILELOOP: while ( $i < 7 ) { $i++; if ( $i == 3 ) { next TESTWHILELOOP; } print 'Production rule Loop matched by LoopWhile, iteration item ', $i, "\n"; } =item * L L #!/usr/bin/env 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 unknown $foo; L #!/usr/bin/env 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_hashref $s_hash = { a => 'howdy', b => 'doody', c => 'clarabell' }; L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: 'size of $foo is 10' >>> # [[[ 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 $size_max_half = 5; my number_arrayref $foo->[($size_max_half * 2) - 1] = undef; print 'size of $foo is ', ( scalar @{$foo} ), "\n"; L #!/usr/bin/env perl # [[[ HEADER ]]] use RPerl; use strict; use warnings; our $VERSION = 0.001_000; # [[[ OPERATIONS ]]] my filehandleref $FOO_FH; L #!/usr/bin/env 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 # [[[ INCLUDES ]]] use RPerl::Test; # [[[ OPERATIONS ]]] my RPerl::Test $foo = RPerl::Test->new(); =item * L L #!/usr/bin/env 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_arrayref $i_array; $i_array = [ -20, -15, -10, -5, 0, 5, 10, 15, 20 ]; L #!/usr/bin/env 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 unknown $foo; $foo = [ 'strange', { weird => 'goofy', beard => [ 'goatee', -17.01 ] }, 23.42, 'heterogeneous' ]; =back =head3 D.4.3: Variable Data C<[[[ SYNTAX PRODUCTION RULES, VARIABLE DATA ]]]> =for rperl X 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 '}' ; =for rperl X B I =over 16 =item * L L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: 'foo' >>> # <<< EXECUTE_SUCCESS: 'quux' >>> # <<< EXECUTE_SUCCESS: 'zorg' >>> # <<< EXECUTE_SUCCESS: 'munge' >>> # <<< EXECUTE_SUCCESS: 'frob' >>> # [[[ 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_arrayref $s_array = [qw(foo quux zorg munge frob)]; foreach my string $s ( @{$s_array} ) { print '$s = ', $s, "\n"; } L #!/usr/bin/env perl # [[[ PREPROCESSOR ]]] # <<< EXECUTE_SUCCESS: '-1bar-5bat' >>> # <<< EXECUTE_SUCCESS: 'qu23ux' >>> # <<< EXECUTE_SUCCESS: 'zorg0+blop+0frun' >>> # <<< EXECUTE_SUCCESS: 'munge4/4sqap6/6cruft' >>> # <<< EXECUTE_SUCCESS: '88frob*99grul99*jick88' >>> # <<< EXECUTE_SUCCESS: '`~!@$%^&*-_=+[]{}|;:'".<>/?' >>> # [[[ 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_arrayref $s_array = [qw(-1bar-5bat qu23ux zorg0+blop+0frun munge4/4sqap6/6cruft 88frob*99grul99*jick88 `~!@$%^&*-_=+[]{}|;:'".<>/?)]; foreach my string $s ( @{$s_array} ) { print '$s = ', $s, "\n"; } =back =head3 D.4.4: User-Defined Words C<[[[ SYNTAX PRODUCTION RULES, USER-DEFINED WORDS ]]]> =for rperl X 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 ; =for rperl X B X
=head1 APPENDIX E: BEYOND THE ROADRUNNER =for html B =for html The Scallion Book X
=for html B =for html The Sword Book X
=head1 GLOSSARY =head2 A =head3 Angle-Brackets Used to wrap input streams such as CSTDINE> or C$MY_FILEHANDLEE>. Also known as I<"chevrons">; created using I<"less-than"> C> and I<"greater-than"> C> characters. =head2 B =head3 Braces I<"curly-brackets"> AKA I<"curly-braces"> AKA I<"braces"> C<{ }> See L =head3 Brackets A group of opening and closing character pairs, including: I<"square-brackets"> AKA I<"brackets"> C<[ ]> I<"round-brackets"> AKA I<"parentheses"> C<( )> I<"curly-brackets"> AKA I<"curly-braces"> AKA I<"braces"> C<{ }> I<"angle-brackets"> AKA I<"chevrons"> AKA I<"less-than"> and I<"greater-than"> C E> See L See L See L See L =head2 P =head3 Parentheses NEED DEFINITION =head2 S =head3 Square-Brackets NEED DEFINITION X
=head1 SEE ALSO L L X
=head1 AUTHOR B L =for comment DEV NOTE: END INLINE CSS DIV =for html
=cut