WITH OUTPUT
This book includes two types of displays that depict output: one form that shows what appears on the user’s screen when a command is typed to the Shell (command with out-put) and another that shows the output that a statement from a Perl program generates (code with output).
We’ll discuss Shell displays first and then Perl displays.
Shell command-with-output displays
Shell terminal sessions are shown as follows, where the $ at the beginning of the com-mand line is the Shell prompt:
$ perl -wnl -e 'print;' one_line_file Line 1
$ who | sort
shroomy pts/9 Oct 24 13:42 shroomy pts/0 Oct 24 14:22
As mentioned in the section on “Constant width bold” type, the bold typeface identi-fies what the user types.
Every effort is made to represent terminal sessions with complete accuracy, which includes backslashing long lines for continuation and showing the Shell’s secondary prompt (>) on continuation lines:
$ who |
> perl -wnl -e 'print; exit;' # like head -1 contix pts/0 Oct 24 14:22
$
The critical thing to understand about examples like this one is that the Shell itself pro-vides the > symbol at the beginning of the second line—which means a reader trying the command shown will never type it. In this case, the trailing pipe symbol (|) auto-matically triggers a continuation line, leading to the appearance of the secondary prompt, which is the Shell’s way of saying “I can’t run the command yet, because you haven’t finished typing it.”
In commands like the following, which do not naturally end with a command con-nector like the | symbol, continuation must be explicitly requested by dangling a backslash at the end of each incomplete line:
$ meeting_page -title='Kwiki' -speaker='Brian "Ingy" Ingerson' \
> -date='September Meeting; Tuesday, 9/16/03:' \
> -summary='Ingy talks about "Kwiki"' meeting.tmpl > 0903.html
$
There’s one exception to the policy of always showing sessions exactly as they would appear on the user’s screen: to save space, the final prompt after the last command is generally omitted, unless its presence adds to your understanding (e.g., by revealing the presence of a blank line at the end of a command’s output).
Perl code-with-output displays
This book uses a special method of depicting Perl statements and their output, which is analogous to the way Shell commands are depicted with their output. For instance, the following examples show comparable Shell and Perl ways of printing an array’s values:
Final prompt
$ echo "${stooges[@]}" # Shell syntax arry Moe Curly
print "@stooges"; # Perl syntax; required program omitted Larry Moe Curly
You could type that echo command directly to the Shell as shown to produce the indicated output, as indicated by that command being typed after a Shell prompt.
In contrast, the Perl print statement must be included within a program to be processed. But to avoid bogging down examples like this one with extra program mate-rial, the book uses this Shell-like code-with-output format to show what a Perl state-ment would produce as output, if run from a suitable program.
The key to differentiating the Shell examples from the Perl examples is to remem-ber that only the former are preceded by the Shell prompt ($).
Ellipsis marks
Ellipsis marks (…) are used to indicate that unnecessary information has been omit-ted. In addition to being used in the text (e.g., with quotations), they’re also used in displays of data files, shell commands, and program output to indicate that something has been omitted:
$ chastise file1 file2 ... # can supply many filenames Chastising on Tuesday, September ...
...
Thank you for running chastise!
The three dots of the ellipsis are displayed in the font of the surrounding text, except when they appear in listings of Perl source code, where they’re shown in a propor-tional font (…) rather than the monospaced code font (...). This approach is needed because Perl’s range operator looks identical to the ellipsis, as do some regular expressions, and these conflicts could otherwise cause uncertainty about how to inter-pret ... in Perl source code. So, just remember that “...” in Perl source code is Perl code, whereas any occurrence of “...” there signifies omitted material.
C
ODING CONVENTIONSThe coding conventions used for the Shell and Perl programs are discussed next.
Shell programs
In cases where there’s considered to be a relatively conventional way of writing the code for a particular type of command, the examples use that style. On the other hand, in cases where two different styles are in popular use, both are shown, as in these equiv-alent commands:
[ -f "$file" -a -r "$file" -a -s "$file" ] || exit 42;
[[ -f $file && -r $file && -s $file ]] || exit 42;
Perl programs
Perl allows the programmer to select from a variety of language features when coding program statements,1 and to exercise wide liberties in how those features are laid out on the pages of the resulting programs.
The features used in this book were included in Minimal Perl for their compati-bility with the expectations of UNIX/Linux people, and they’re laid out in a manner that is compatible with those expectations. As an additional influence, guidelines from the book Perl Best Practices2 are followed, but only where they don’t conflict with our
“prime directive” of catering to UNIX and Shell sensibilities.