diff options
Diffstat (limited to 'upstream/archlinux/man1/perlform.1perl')
| -rw-r--r-- | upstream/archlinux/man1/perlform.1perl | 514 |
1 files changed, 514 insertions, 0 deletions
diff --git a/upstream/archlinux/man1/perlform.1perl b/upstream/archlinux/man1/perlform.1perl new file mode 100644 index 00000000..4f2bcaad --- /dev/null +++ b/upstream/archlinux/man1/perlform.1perl @@ -0,0 +1,514 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLFORM 1perl" +.TH PERLFORM 1perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlform \- Perl formats +.IX Xref "format report chart" +.SH DESCRIPTION +.IX Header "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: \fBformat()\fR to declare and \fBwrite()\fR +to execute; see their entries in perlfunc. Fortunately, the layout is +much more legible, more like BASIC's PRINT USING statement. Think of it +as a poor man's \fBnroff\fR\|(1). +.IX Xref "nroff" +.PP +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. +.PP +Output record formats are declared as follows: +.PP +.Vb 3 +\& format NAME = +\& FORMLIST +\& . +.Ve +.PP +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: +.IP 1. 4 +A comment, indicated by putting a '#' in the first column. +.IP 2. 4 +A "picture" line giving the format for one output line. +.IP 3. 4 +An argument line supplying values to plug into the previous picture line. +.PP +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: +.IX Xref "format, picture line @ ^ < | > # 0 . ... @* ^* ~ ~~" +.PP +.Vb 10 +\& @ 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 +.Ve +.PP +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. +.SS "Text Fields" +.IX Xref "format, text field" +.IX Subsection "Text Fields" +The length of the field is supplied by padding out the field with multiple +"<", ">", 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 "Using Fill Mode" for details. +.PP +.Vb 7 +\& Example: +\& format STDOUT = +\& @<<<<<< @|||||| @>>>>>> +\& "left", "middle", "right" +\& . +\& Output: +\& left middle right +.Ve +.SS "Numeric Fields" +.IX Xref "# format, numeric field" +.IX Subsection "Numeric Fields" +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. +.PP +.Vb 7 +\& Example: +\& format STDOUT = +\& @### @.### @##.### @### @### ^#### +\& 42, 3.1415, undef, 0, 10000, undef +\& . +\& Output: +\& 42 3.142 0.000 0 #### +.Ve +.SS "The Field @* for Variable-Width Multi-Line Text" +.IX Xref "@*" +.IX Subsection "The Field @* for Variable-Width Multi-Line Text" +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. +.SS "The Field ^* for Variable-Width One-line-at-a-time Text" +.IX Xref "^*" +.IX Subsection "The Field ^* for Variable-Width One-line-at-a-time Text" +Like "@*", this is a variable-width field. The value supplied must be a +scalar variable. Perl puts the first line (up to the first "\en") 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 \fInot\fR be restored. +.PP +.Vb 12 +\& Example: +\& $text = "line 1\enline 2\enline 3"; +\& format STDOUT = +\& Text: ^* +\& $text +\& ~~ ^* +\& $text +\& . +\& Output: +\& Text: line 1 +\& line 2 +\& line 3 +.Ve +.SS "Specifying Values" +.IX Xref "format, specifying values" +.IX Subsection "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 \fBwithout\fR an embedded "."), the character used for the decimal +point is determined by the current LC_NUMERIC locale if \f(CW\*(C`use locale\*(C'\fR 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 +perllocale and "WARNINGS" for more information. +.SS "Using Fill Mode" +.IX Xref "format, fill mode" +.IX Subsection "Using 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 \fBwrite()\fR +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 +(\f(CW\*(C`\er\*(C'\fR) to force a line break. You can change which characters are legal +to break on by changing the variable \f(CW$:\fR (that's +\&\f(CW$FORMAT_LINE_BREAK_CHARACTERS\fR if you're using the English module) to a +list of the desired characters. +.PP +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. +.SS "Suppressing Lines Where All Fields Are Void" +.IX Xref "format, suppressing lines" +.IX Subsection "Suppressing Lines Where All Fields Are Void" +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. +.SS "Repeating Format Lines" +.IX Xref "format, repeating lines" +.IX Subsection "Repeating Format 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! (\f(CWshift(@f)\fR +is a simple example that would work.) Don't use a regular (at) numeric +field in such lines, because it will never go blank. +.SS "Top of Form Processing" +.IX Xref "format, top of form top header" +.IX Subsection "Top of Form Processing" +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 "write" in perlfunc. +.PP +Examples: +.PP +.Vb 10 +\& # 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 +\& . +.Ve +.PP +It is possible to intermix \fBprint()\fRs with \fBwrite()\fRs on the same output +channel, but you'll have to handle \f(CW\*(C`$\-\*(C'\fR (\f(CW$FORMAT_LINES_LEFT\fR) +yourself. +.SS "Format Variables" +.IX Xref "format variables format, variables" +.IX Subsection "Format Variables" +The current format name is stored in the variable \f(CW$~\fR (\f(CW$FORMAT_NAME\fR), +and the current top of form format name is in \f(CW$^\fR (\f(CW$FORMAT_TOP_NAME\fR). +The current output page number is stored in \f(CW$%\fR (\f(CW$FORMAT_PAGE_NUMBER\fR), +and the number of lines on the page is in \f(CW$=\fR (\f(CW$FORMAT_LINES_PER_PAGE\fR). +Whether to autoflush output on this handle is stored in \f(CW$|\fR +(\f(CW$OUTPUT_AUTOFLUSH\fR). The string output before each top of page (except +the first) is stored in \f(CW$^L\fR (\f(CW$FORMAT_FORMFEED\fR). These variables are +set on a per-filehandle basis, so you'll need to \fBselect()\fR into a different +one to affect them: +.PP +.Vb 4 +\& select((select(OUTF), +\& $~ = "My_Other_Format", +\& $^ = "My_Top_Format" +\& )[0]); +.Ve +.PP +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): +.PP +.Vb 4 +\& $ofh = select(OUTF); +\& $~ = "My_Other_Format"; +\& $^ = "My_Top_Format"; +\& select($ofh); +.Ve +.PP +If you use the English module, you can even read the variable names: +.PP +.Vb 5 +\& use English; +\& $ofh = select(OUTF); +\& $FORMAT_NAME = "My_Other_Format"; +\& $FORMAT_TOP_NAME = "My_Top_Format"; +\& select($ofh); +.Ve +.PP +But you still have those funny \fBselect()\fRs. So just use the FileHandle +module. Now, you can access these special variables using lowercase +method names instead: +.PP +.Vb 3 +\& use FileHandle; +\& format_name OUTF "My_Other_Format"; +\& format_top_name OUTF "My_Top_Format"; +.Ve +.PP +Much better! +.SH NOTES +.IX Header "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 \fBsprintf()\fR or one of your own. For example: +.PP +.Vb 4 +\& format Ident = +\& @<<<<<<<<<<<<<<< +\& &commify($n) +\& . +.Ve +.PP +To get a real at or caret into the field, do this: +.PP +.Vb 4 +\& format Ident = +\& I have an @ here. +\& "@" +\& . +.Ve +.PP +To center a whole line of text, do something like this: +.PP +.Vb 4 +\& format Ident = +\& @||||||||||||||||||||||||||||||||||||||||||||||| +\& "Some text line" +\& . +.Ve +.PP +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 \fBeval()\fR it: +.PP +.Vb 9 +\& $format = "format STDOUT = \en" +\& . \*(Aq^\*(Aq . \*(Aq<\*(Aq x $cols . "\en" +\& . \*(Aq$entry\*(Aq . "\en" +\& . "\et^" . "<" x ($cols\-8) . "~~\en" +\& . \*(Aq$entry\*(Aq . "\en" +\& . ".\en"; +\& print $format if $Debugging; +\& eval $format; +\& die $@ if $@; +.Ve +.PP +Which would generate a format looking something like this: +.PP +.Vb 6 +\& format STDOUT = +\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< +\& $entry +\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~ +\& $entry +\& . +.Ve +.PP +Here's a little program that's somewhat like \fBfmt\fR\|(1): +.PP +.Vb 3 +\& format = +\& ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~ +\& $_ +\& +\& . +\& +\& $/ = \*(Aq\*(Aq; +\& while (<>) { +\& s/\es*\en\es*/ /g; +\& write; +\& } +.Ve +.SS Footers +.IX Xref "format, footer footer" +.IX Subsection "Footers" +While \f(CW$FORMAT_TOP_NAME\fR 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. +.PP +Here's one strategy: If you have a fixed-size footer, you can get footers +by checking \f(CW$FORMAT_LINES_LEFT\fR before each \fBwrite()\fR and print the footer +yourself if necessary. +.PP +Here's another strategy: Open a pipe to yourself, using \f(CW\*(C`open(MYSELF, "|\-")\*(C'\fR +(see "open" in perlfunc) and always \fBwrite()\fR 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. +.SS "Accessing Formatting Internals" +.IX Xref "format, internals" +.IX Subsection "Accessing Formatting Internals" +For low-level access to the formatting mechanism, you may use \fBformline()\fR +and access \f(CW$^A\fR (the \f(CW$ACCUMULATOR\fR variable) directly. +.PP +For example: +.PP +.Vb 3 +\& $str = formline <<\*(AqEND\*(Aq, 1,2,3; +\& @<<< @||| @>>> +\& END +\& +\& print "Wow, I just stored \*(Aq$^A\*(Aq in the accumulator!\en"; +.Ve +.PP +Or to make an \fBswrite()\fR subroutine, which is to \fBwrite()\fR what \fBsprintf()\fR +is to \fBprintf()\fR, do this: +.PP +.Vb 8 +\& use Carp; +\& sub swrite { +\& croak "usage: swrite PICTURE ARGS" unless @_; +\& my $format = shift; +\& $^A = ""; +\& formline($format,@_); +\& return $^A; +\& } +\& +\& $string = swrite(<<\*(AqEND\*(Aq, 1, 2, 3); +\& Check me out +\& @<<< @||| @>>> +\& END +\& print $string; +.Ve +.SH WARNINGS +.IX Header "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. +.PP +Lexical variables (declared with "my") are not visible within a +format unless the format is declared within the scope of the lexical +variable. +.PP +If a program's environment specifies an LC_NUMERIC locale and \f(CW\*(C`use +locale\*(C'\fR 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 \f(CW\*(C`use locale\*(C'\fR at the time when \fBwrite()\fR +is called. See perllocale for further discussion of locale handling. +.PP +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 \f(CW\*(C`\er\*(C'\fR when using fill mode.) This is done to avoid +misalignment when control characters "disappear" on some output media. |