summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/pods/perlform.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/pods/perlform.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/pods/perlform.pod455
1 files changed, 0 insertions, 455 deletions
diff --git a/Master/tlpkg/tlperl/lib/pods/perlform.pod b/Master/tlpkg/tlperl/lib/pods/perlform.pod
deleted file mode 100644
index b00d394296e..00000000000
--- a/Master/tlpkg/tlperl/lib/pods/perlform.pod
+++ /dev/null
@@ -1,455 +0,0 @@
-=head1 NAME
-X<format> X<report> X<chart>
-
-perlform - Perl formats
-
-=head1 DESCRIPTION
-
-Perl has a mechanism to help you generate simple reports and charts. To
-facilitate this, Perl helps you code up your output page close to how it
-will look when it's printed. It can keep track of things like how many
-lines are on a page, what page you're on, when to print page headers,
-etc. Keywords are borrowed from FORTRAN: format() to declare and write()
-to execute; see their entries in L<perlfunc>. Fortunately, the layout is
-much more legible, more like BASIC's PRINT USING statement. Think of it
-as a poor man's nroff(1).
-X<nroff>
-
-Formats, like packages and subroutines, are declared rather than
-executed, so they may occur at any point in your program. (Usually it's
-best to keep them all together though.) They have their own namespace
-apart from all the other "types" in Perl. This means that if you have a
-function named "Foo", it is not the same thing as having a format named
-"Foo". However, the default name for the format associated with a given
-filehandle is the same as the name of the filehandle. Thus, the default
-format for STDOUT is named "STDOUT", and the default format for filehandle
-TEMP is named "TEMP". They just look the same. They aren't.
-
-Output record formats are declared as follows:
-
- format NAME =
- FORMLIST
- .
-
-If the name is omitted, format "STDOUT" is defined. A single "." in
-column 1 is used to terminate a format. FORMLIST consists of a sequence
-of lines, each of which may be one of three types:
-
-=over 4
-
-=item 1.
-
-A comment, indicated by putting a '#' in the first column.
-
-=item 2.
-
-A "picture" line giving the format for one output line.
-
-=item 3.
-
-An argument line supplying values to plug into the previous picture line.
-
-=back
-
-Picture lines contain output field definitions, intermingled with
-literal text. These lines do not undergo any kind of variable interpolation.
-Field definitions are made up from a set of characters, for starting and
-extending a field to its desired width. This is the complete set of
-characters for field definitions:
-X<format, picture line>
-X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...>
-X<@*> X<^*> X<~> X<~~>
-
- @ start of regular field
- ^ start of special field
- < pad character for left justification
- | pad character for centering
- > pad character for right justification
- # pad character for a right-justified numeric field
- 0 instead of first #: pad number with leading zeroes
- . decimal point within a numeric field
- ... terminate a text field, show "..." as truncation evidence
- @* variable width field for a multi-line value
- ^* variable width field for next line of a multi-line value
- ~ suppress line with all fields empty
- ~~ repeat line until all fields are exhausted
-
-Each field in a picture line starts with either "@" (at) or "^" (caret),
-indicating what we'll call, respectively, a "regular" or "special" field.
-The choice of pad characters determines whether a field is textual or
-numeric. The tilde operators are not part of a field. Let's look at
-the various possibilities in detail.
-
-
-=head2 Text Fields
-X<format, text field>
-
-The length of the field is supplied by padding out the field with multiple
-"E<lt>", "E<gt>", or "|" characters to specify a non-numeric field with,
-respectively, left justification, right justification, or centering.
-For a regular field, the value (up to the first newline) is taken and
-printed according to the selected justification, truncating excess characters.
-If you terminate a text field with "...", three dots will be shown if
-the value is truncated. A special text field may be used to do rudimentary
-multi-line text block filling; see L</Using Fill Mode> for details.
-
- Example:
- format STDOUT =
- @<<<<<< @|||||| @>>>>>>
- "left", "middle", "right"
- .
- Output:
- left middle right
-
-
-=head2 Numeric Fields
-X<#> X<format, numeric field>
-
-Using "#" as a padding character specifies a numeric field, with
-right justification. An optional "." defines the position of the
-decimal point. With a "0" (zero) instead of the first "#", the
-formatted number will be padded with leading zeroes if necessary.
-A special numeric field is blanked out if the value is undefined.
-If the resulting value would exceed the width specified the field is
-filled with "#" as overflow evidence.
-
- Example:
- format STDOUT =
- @### @.### @##.### @### @### ^####
- 42, 3.1415, undef, 0, 10000, undef
- .
- Output:
- 42 3.142 0.000 0 ####
-
-
-=head2 The Field @* for Variable-Width Multi-Line Text
-X<@*>
-
-The field "@*" can be used for printing multi-line, nontruncated
-values; it should (but need not) appear by itself on a line. A final
-line feed is chomped off, but all other characters are emitted verbatim.
-
-
-=head2 The Field ^* for Variable-Width One-line-at-a-time Text
-X<^*>
-
-Like "@*", this is a variable-width field. The value supplied must be a
-scalar variable. Perl puts the first line (up to the first "\n") of the
-text into the field, and then chops off the front of the string so that
-the next time the variable is referenced, more of the text can be printed.
-The variable will I<not> be restored.
-
- Example:
- $text = "line 1\nline 2\nline 3";
- format STDOUT =
- Text: ^*
- $text
- ~~ ^*
- $text
- .
- Output:
- Text: line 1
- line 2
- line 3
-
-
-=head2 Specifying Values
-X<format, specifying values>
-
-The values are specified on the following format line in the same order as
-the picture fields. The expressions providing the values must be
-separated by commas. They are all evaluated in a list context
-before the line is processed, so a single list expression could produce
-multiple list elements. The expressions may be spread out to more than
-one line if enclosed in braces. If so, the opening brace must be the first
-token on the first line. If an expression evaluates to a number with a
-decimal part, and if the corresponding picture specifies that the decimal
-part should appear in the output (that is, any picture except multiple "#"
-characters B<without> an embedded "."), the character used for the decimal
-point is determined by the current LC_NUMERIC locale if C<use locale> is in
-effect. This means that, if, for example, the run-time environment happens
-to specify a German locale, "," will be used instead of the default ".". See
-L<perllocale> and L<"WARNINGS"> for more information.
-
-
-=head2 Using Fill Mode
-X<format, fill mode>
-
-On text fields the caret enables a kind of fill mode. Instead of an
-arbitrary expression, the value supplied must be a scalar variable
-that contains a text string. Perl puts the next portion of the text into
-the field, and then chops off the front of the string so that the next time
-the variable is referenced, more of the text can be printed. (Yes, this
-means that the variable itself is altered during execution of the write()
-call, and is not restored.) The next portion of text is determined by
-a crude line-breaking algorithm. You may use the carriage return character
-(C<\r>) to force a line break. You can change which characters are legal
-to break on by changing the variable C<$:> (that's
-$FORMAT_LINE_BREAK_CHARACTERS if you're using the English module) to a
-list of the desired characters.
-
-Normally you would use a sequence of fields in a vertical stack associated
-with the same scalar variable to print out a block of text. You might wish
-to end the final field with the text "...", which will appear in the output
-if the text was too long to appear in its entirety.
-
-
-=head2 Suppressing Lines Where All Fields Are Void
-X<format, suppressing lines>
-
-Using caret fields can produce lines where all fields are blank. You can
-suppress such lines by putting a "~" (tilde) character anywhere in the
-line. The tilde will be translated to a space upon output.
-
-
-=head2 Repeating Format Lines
-X<format, repeating lines>
-
-If you put two contiguous tilde characters "~~" anywhere into a line,
-the line will be repeated until all the fields on the line are exhausted,
-i.e. undefined. For special (caret) text fields this will occur sooner or
-later, but if you use a text field of the at variety, the expression you
-supply had better not give the same value every time forever! (C<shift(@f)>
-is a simple example that would work.) Don't use a regular (at) numeric
-field in such lines, because it will never go blank.
-
-
-=head2 Top of Form Processing
-X<format, top of form> X<top> X<header>
-
-Top-of-form processing is by default handled by a format with the
-same name as the current filehandle with "_TOP" concatenated to it.
-It's triggered at the top of each page. See L<perlfunc/write>.
-
-Examples:
-
- # a report on the /etc/passwd file
- format STDOUT_TOP =
- Passwd File
- Name Login Office Uid Gid Home
- ------------------------------------------------------------------
- .
- format STDOUT =
- @<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<
- $name, $login, $office,$uid,$gid, $home
- .
-
-
- # a report from a bug report form
- format STDOUT_TOP =
- Bug Reports
- @<<<<<<<<<<<<<<<<<<<<<<< @||| @>>>>>>>>>>>>>>>>>>>>>>>
- $system, $%, $date
- ------------------------------------------------------------------
- .
- format STDOUT =
- Subject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $subject
- Index: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $index, $description
- Priority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $priority, $date, $description
- From: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $from, $description
- Assigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $programmer, $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $description
- ~ ^<<<<<<<<<<<<<<<<<<<<<<<...
- $description
- .
-
-It is possible to intermix print()s with write()s on the same output
-channel, but you'll have to handle C<$-> (C<$FORMAT_LINES_LEFT>)
-yourself.
-
-=head2 Format Variables
-X<format variables>
-X<format, variables>
-
-The current format name is stored in the variable C<$~> (C<$FORMAT_NAME>),
-and the current top of form format name is in C<$^> (C<$FORMAT_TOP_NAME>).
-The current output page number is stored in C<$%> (C<$FORMAT_PAGE_NUMBER>),
-and the number of lines on the page is in C<$=> (C<$FORMAT_LINES_PER_PAGE>).
-Whether to autoflush output on this handle is stored in C<$|>
-(C<$OUTPUT_AUTOFLUSH>). The string output before each top of page (except
-the first) is stored in C<$^L> (C<$FORMAT_FORMFEED>). These variables are
-set on a per-filehandle basis, so you'll need to select() into a different
-one to affect them:
-
- select((select(OUTF),
- $~ = "My_Other_Format",
- $^ = "My_Top_Format"
- )[0]);
-
-Pretty ugly, eh? It's a common idiom though, so don't be too surprised
-when you see it. You can at least use a temporary variable to hold
-the previous filehandle: (this is a much better approach in general,
-because not only does legibility improve, you now have an intermediary
-stage in the expression to single-step the debugger through):
-
- $ofh = select(OUTF);
- $~ = "My_Other_Format";
- $^ = "My_Top_Format";
- select($ofh);
-
-If you use the English module, you can even read the variable names:
-
- use English '-no_match_vars';
- $ofh = select(OUTF);
- $FORMAT_NAME = "My_Other_Format";
- $FORMAT_TOP_NAME = "My_Top_Format";
- select($ofh);
-
-But you still have those funny select()s. So just use the FileHandle
-module. Now, you can access these special variables using lowercase
-method names instead:
-
- use FileHandle;
- format_name OUTF "My_Other_Format";
- format_top_name OUTF "My_Top_Format";
-
-Much better!
-
-=head1 NOTES
-
-Because the values line may contain arbitrary expressions (for at fields,
-not caret fields), you can farm out more sophisticated processing
-to other functions, like sprintf() or one of your own. For example:
-
- format Ident =
- @<<<<<<<<<<<<<<<
- &commify($n)
- .
-
-To get a real at or caret into the field, do this:
-
- format Ident =
- I have an @ here.
- "@"
- .
-
-To center a whole line of text, do something like this:
-
- format Ident =
- @|||||||||||||||||||||||||||||||||||||||||||||||
- "Some text line"
- .
-
-There is no builtin way to say "float this to the right hand side
-of the page, however wide it is." You have to specify where it goes.
-The truly desperate can generate their own format on the fly, based
-on the current number of columns, and then eval() it:
-
- $format = "format STDOUT = \n"
- . '^' . '<' x $cols . "\n"
- . '$entry' . "\n"
- . "\t^" . "<" x ($cols-8) . "~~\n"
- . '$entry' . "\n"
- . ".\n";
- print $format if $Debugging;
- eval $format;
- die $@ if $@;
-
-Which would generate a format looking something like this:
-
- format STDOUT =
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
- $entry
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
- $entry
- .
-
-Here's a little program that's somewhat like fmt(1):
-
- format =
- ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~
- $_
-
- .
-
- $/ = '';
- while (<>) {
- s/\s*\n\s*/ /g;
- write;
- }
-
-=head2 Footers
-X<format, footer> X<footer>
-
-While $FORMAT_TOP_NAME contains the name of the current header format,
-there is no corresponding mechanism to automatically do the same thing
-for a footer. Not knowing how big a format is going to be until you
-evaluate it is one of the major problems. It's on the TODO list.
-
-Here's one strategy: If you have a fixed-size footer, you can get footers
-by checking $FORMAT_LINES_LEFT before each write() and print the footer
-yourself if necessary.
-
-Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")>
-(see L<perlfunc/open>) and always write() to MYSELF instead of STDOUT.
-Have your child process massage its STDIN to rearrange headers and footers
-however you like. Not very convenient, but doable.
-
-=head2 Accessing Formatting Internals
-X<format, internals>
-
-For low-level access to the formatting mechanism. you may use formline()
-and access C<$^A> (the $ACCUMULATOR variable) directly.
-
-For example:
-
- $str = formline <<'END', 1,2,3;
- @<<< @||| @>>>
- END
-
- print "Wow, I just stored '$^A' in the accumulator!\n";
-
-Or to make an swrite() subroutine, which is to write() what sprintf()
-is to printf(), do this:
-
- use Carp;
- sub swrite {
- croak "usage: swrite PICTURE ARGS" unless @_;
- my $format = shift;
- $^A = "";
- formline($format,@_);
- return $^A;
- }
-
- $string = swrite(<<'END', 1, 2, 3);
- Check me out
- @<<< @||| @>>>
- END
- print $string;
-
-=head1 WARNINGS
-
-The lone dot that ends a format can also prematurely end a mail
-message passing through a misconfigured Internet mailer (and based on
-experience, such misconfiguration is the rule, not the exception). So
-when sending format code through mail, you should indent it so that
-the format-ending dot is not on the left margin; this will prevent
-SMTP cutoff.
-
-Lexical variables (declared with "my") are not visible within a
-format unless the format is declared within the scope of the lexical
-variable. (They weren't visible at all before version 5.001.)
-
-If a program's environment specifies an LC_NUMERIC locale and C<use
-locale> is in effect when the format is declared, the locale is used
-to specify the decimal point character in formatted output. Formatted
-output cannot be controlled by C<use locale> at the time when write()
-is called. See L<perllocale> for further discussion of locale handling.
-
-Within strings that are to be displayed in a fixed-length text field,
-each control character is substituted by a space. (But remember the
-special meaning of C<\r> when using fill mode.) This is done to avoid
-misalignment when control characters "disappear" on some output media.
-