{
    "content": [
        {
            "type": "text",
            "text": "# perlform (info)\n\n## NAME\n\nperlform - Perl formats\n\n## DESCRIPTION\n\nPerl has a mechanism to help you generate simple reports and charts.\nTo facilitate this, Perl helps you code up your output page close to\nhow it will look when it's printed.  It can keep track of things like\nhow many lines are on a page, what page you're on, when to print page\nheaders, etc.  Keywords are borrowed from FORTRAN: format() to declare\nand write() to execute; see their entries in perlfunc.  Fortunately,\nthe layout is much more legible, more like BASIC's PRINT USING\nstatement.  Think of it as a poor man's nroff(1).\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **NOTES**\n- **WARNINGS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "perlform",
        "section": "",
        "mode": "info",
        "summary": "perlform - Perl formats",
        "synopsis": null,
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 269,
                "subsections": []
            },
            {
                "name": "NOTES",
                "lines": 107,
                "subsections": []
            },
            {
                "name": "WARNINGS",
                "lines": 22,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "perlform - Perl formats\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "Perl has a mechanism to help you generate simple reports and charts.\nTo facilitate this, Perl helps you code up your output page close to\nhow it will look when it's printed.  It can keep track of things like\nhow many lines are on a page, what page you're on, when to print page\nheaders, etc.  Keywords are borrowed from FORTRAN: format() to declare\nand write() to execute; see their entries in perlfunc.  Fortunately,\nthe layout is much more legible, more like BASIC's PRINT USING\nstatement.  Think of it as a poor man's nroff(1).\n\nFormats, like packages and subroutines, are declared rather than\nexecuted, so they may occur at any point in your program.  (Usually\nit's best to keep them all together though.) They have their own\nnamespace apart from all the other \"types\" in Perl.  This means that if\nyou have a function named \"Foo\", it is not the same thing as having a\nformat named \"Foo\".  However, the default name for the format\nassociated with a given filehandle is the same as the name of the\nfilehandle.  Thus, the default format for STDOUT is named \"STDOUT\", and\nthe default format for filehandle TEMP is named \"TEMP\".  They just look\nthe same.  They aren't.\n\nOutput record formats are declared as follows:\n\nformat NAME =\nFORMLIST\n.\n\nIf the name is omitted, format \"STDOUT\" is defined. A single \".\" in\ncolumn 1 is used to terminate a format.  FORMLIST consists of a\nsequence of lines, each of which may be one of three types:\n\n1.  A comment, indicated by putting a '#' in the first column.\n\n2.  A \"picture\" line giving the format for one output line.\n\n3.  An argument line supplying values to plug into the previous picture\nline.\n\nPicture lines contain output field definitions, intermingled with\nliteral text. These lines do not undergo any kind of variable\ninterpolation.  Field definitions are made up from a set of characters,\nfor starting and extending a field to its desired width. This is the\ncomplete set of characters for field definitions:\n\n@    start of regular field\n^    start of special field\n<    pad character for left justification\n|    pad character for centering\n>    pad character for right justification\n#    pad character for a right-justified numeric field\n0    instead of first #: pad number with leading zeroes\n.    decimal point within a numeric field\n...  terminate a text field, show \"...\" as truncation evidence\n@*   variable width field for a multi-line value\n^*   variable width field for next line of a multi-line value\n~    suppress line with all fields empty\n~~   repeat line until all fields are exhausted\n\nEach field in a picture line starts with either \"@\" (at) or \"^\"\n(caret), indicating what we'll call, respectively, a \"regular\" or\n\"special\" field.  The choice of pad characters determines whether a\nfield is textual or numeric. The tilde operators are not part of a\nfield.  Let's look at the various possibilities in detail.\n\nText Fields\nThe length of the field is supplied by padding out the field with\nmultiple \"<\", \">\", or \"|\" characters to specify a non-numeric field\nwith, respectively, left justification, right justification, or\ncentering.  For a regular field, the value (up to the first newline) is\ntaken and printed according to the selected justification, truncating\nexcess characters.  If you terminate a text field with \"...\", three\ndots will be shown if the value is truncated. A special text field may\nbe used to do rudimentary multi-line text block filling; see \"Using\nFill Mode\" for details.\n\nExample:\nformat STDOUT =\n@<<<<<<   @||||||   @>>>>>>\n\"left\",   \"middle\", \"right\"\n.\nOutput:\nleft      middle    right\n\nNumeric Fields\nUsing \"#\" as a padding character specifies a numeric field, with right\njustification. An optional \".\" defines the position of the decimal\npoint. With a \"0\" (zero) instead of the first \"#\", the formatted number\nwill be padded with leading zeroes if necessary.  A special numeric\nfield is blanked out if the value is undefined.  If the resulting value\nwould exceed the width specified the field is filled with \"#\" as\noverflow evidence.\n\nExample:\nformat STDOUT =\n@###   @.###   @##.###  @###   @###   ^####\n42,   3.1415,  undef,    0, 10000,   undef\n.\nOutput:\n42   3.142     0.000     0   ####\n\nThe Field @* for Variable-Width Multi-Line Text\nThe field \"@*\" can be used for printing multi-line, nontruncated\nvalues; it should (but need not) appear by itself on a line. A final\nline feed is chomped off, but all other characters are emitted\nverbatim.\n\nThe Field ^* for Variable-Width One-line-at-a-time Text\nLike \"@*\", this is a variable-width field. The value supplied must be a\nscalar variable. Perl puts the first line (up to the first \"\\n\") of the\ntext into the field, and then chops off the front of the string so that\nthe next time the variable is referenced, more of the text can be\nprinted.  The variable will not be restored.\n\nExample:\n$text = \"line 1\\nline 2\\nline 3\";\nformat STDOUT =\nText: ^*\n$text\n~~    ^*\n$text\n.\nOutput:\nText: line 1\nline 2\nline 3\n\nSpecifying Values\nThe values are specified on the following format line in the same order\nas the picture fields.  The expressions providing the values must be\nseparated by commas.  They are all evaluated in a list context before\nthe line is processed, so a single list expression could produce\nmultiple list elements.  The expressions may be spread out to more than\none line if enclosed in braces.  If so, the opening brace must be the\nfirst token on the first line.  If an expression evaluates to a number\nwith a decimal part, and if the corresponding picture specifies that\nthe decimal part should appear in the output (that is, any picture\nexcept multiple \"#\" characters without an embedded \".\"), the character\nused for the decimal point is determined by the current LCNUMERIC\nlocale if \"use locale\" is in effect.  This means that, if, for example,\nthe run-time environment happens to specify a German locale, \",\" will\nbe used instead of the default \".\".  See perllocale and \"WARNINGS\" for\nmore information.\n\nUsing Fill Mode\nOn text fields the caret enables a kind of fill mode.  Instead of an\narbitrary expression, the value supplied must be a scalar variable that\ncontains a text string.  Perl puts the next portion of the text into\nthe field, and then chops off the front of the string so that the next\ntime the variable is referenced, more of the text can be printed.\n(Yes, this means that the variable itself is altered during execution\nof the write() call, and is not restored.)  The next portion of text is\ndetermined by a crude line-breaking algorithm. You may use the carriage\nreturn character (\"\\r\") to force a line break. You can change which\ncharacters are legal to break on by changing the variable $: (that's\n$FORMATLINEBREAKCHARACTERS if you're using the English module) to a\nlist of the desired characters.\n\nNormally you would use a sequence of fields in a vertical stack\nassociated with the same scalar variable to print out a block of text.\nYou might wish to end the final field with the text \"...\", which will\nappear in the output if the text was too long to appear in its\nentirety.\n\nSuppressing Lines Where All Fields Are Void\nUsing caret fields can produce lines where all fields are blank. You\ncan suppress such lines by putting a \"~\" (tilde) character anywhere in\nthe line.  The tilde will be translated to a space upon output.\n\nRepeating Format Lines\nIf you put two contiguous tilde characters \"~~\" anywhere into a line,\nthe line will be repeated until all the fields on the line are\nexhausted, i.e. undefined. For special (caret) text fields this will\noccur sooner or later, but if you use a text field of the at variety,\nthe  expression you supply had better not give the same value every\ntime forever! (\"shift(@f)\" is a simple example that would work.)  Don't\nuse a regular (at) numeric field in such lines, because it will never\ngo blank.\n\nTop of Form Processing\nTop-of-form processing is by default handled by a format with the same\nname as the current filehandle with \"TOP\" concatenated to it.  It's\ntriggered at the top of each page.  See \"write\" in perlfunc.\n\nExamples:\n\n# a report on the /etc/passwd file\nformat STDOUTTOP =\nPasswd File\n.\nformat STDOUT =\n@<<<<<<<<<<<<<<<<<< @||||||| @<<<<<<@>>>> @>>>> @<<<<<<<<<<<<<<<<<\n$name,              $login,  $office,$uid,$gid, $home\n.\n\n# a report from a bug report form\nformat STDOUTTOP =\nBug Reports\n@<<<<<<<<<<<<<<<<<<<<<<<     @|||         @>>>>>>>>>>>>>>>>>>>>>>>\n.\nformat STDOUT =\nSubject: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$subject\nIndex: @<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$index,                       $description\nPriority: @<<<<<<<<<< Date: @<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$priority,        $date,   $description\nFrom: @<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$from,                         $description\nAssigned to: @<<<<<<<<<<<<<<<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$programmer,            $description\n~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$description\n~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$description\n~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$description\n~                                    ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$description\n~                                    ^<<<<<<<<<<<<<<<<<<<<<<<...\n$description\n.\n\nIt is possible to intermix print()s with write()s on the same output\nchannel, but you'll have to handle \"$-\" ($FORMATLINESLEFT) yourself.\n\nFormat Variables\nThe current format name is stored in the variable $~ ($FORMATNAME),\nand the current top of form format name is in $^ ($FORMATTOPNAME).\nThe current output page number is stored in $% ($FORMATPAGENUMBER),\nand the number of lines on the page is in $= ($FORMATLINESPERPAGE).\nWhether to autoflush output on this handle is stored in $|\n($OUTPUTAUTOFLUSH).  The string output before each top of page (except\nthe first) is stored in $^L ($FORMATFORMFEED).  These variables are\nset on a per-filehandle basis, so you'll need to select() into a\ndifferent one to affect them:\n\nselect((select(OUTF),\n$~ = \"MyOtherFormat\",\n$^ = \"MyTopFormat\"\n)[0]);\n\nPretty ugly, eh?  It's a common idiom though, so don't be too surprised\nwhen you see it.  You can at least use a temporary variable to hold the\nprevious filehandle: (this is a much better approach in general,\nbecause not only does legibility improve, you now have an intermediary\nstage in the expression to single-step the debugger through):\n\n$ofh = select(OUTF);\n$~ = \"MyOtherFormat\";\n$^ = \"MyTopFormat\";\nselect($ofh);\n\nIf you use the English module, you can even read the variable names:\n\nuse English;\n$ofh = select(OUTF);\n$FORMATNAME     = \"MyOtherFormat\";\n$FORMATTOPNAME = \"MyTopFormat\";\nselect($ofh);\n\nBut you still have those funny select()s.  So just use the FileHandle\nmodule.  Now, you can access these special variables using lowercase\nmethod names instead:\n\nuse FileHandle;\nformatname     OUTF \"MyOtherFormat\";\nformattopname OUTF \"MyTopFormat\";\n\nMuch better!\n",
                "subsections": []
            },
            "NOTES": {
                "content": "Because the values line may contain arbitrary expressions (for at\nfields, not caret fields), you can farm out more sophisticated\nprocessing to other functions, like sprintf() or one of your own.  For\nexample:\n\nformat Ident =\n@<<<<<<<<<<<<<<<\n&commify($n)\n.\n\nTo get a real at or caret into the field, do this:\n\nformat Ident =\nI have an @ here.\n\"@\"\n.\n\nTo center a whole line of text, do something like this:\n\nformat Ident =\n@|||||||||||||||||||||||||||||||||||||||||||||||\n\"Some text line\"\n.\n\nThere is no builtin way to say \"float this to the right hand side of\nthe page, however wide it is.\"  You have to specify where it goes.  The\ntruly desperate can generate their own format on the fly, based on the\ncurrent number of columns, and then eval() it:\n\n$format  = \"format STDOUT = \\n\"\n. '^' . '<' x $cols . \"\\n\"\n. '$entry' . \"\\n\"\n. \"\\t^\" . \"<\" x ($cols-8) . \"~~\\n\"\n. '$entry' . \"\\n\"\n. \".\\n\";\nprint $format if $Debugging;\neval $format;\ndie $@ if $@;\n\nWhich would generate a format looking something like this:\n\nformat STDOUT =\n^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<\n$entry\n^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~\n$entry\n.\n\nHere's a little program that's somewhat like fmt(1):\n\nformat =\n^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< ~~\n$\n\n.\n\n$/ = '';\nwhile (<>) {\ns/\\s*\\n\\s*/ /g;\nwrite;\n}\n\nFooters\nWhile $FORMATTOPNAME contains the name of the current header format,\nthere is no corresponding mechanism to automatically do the same thing\nfor a footer.  Not knowing how big a format is going to be until you\nevaluate it is one of the major problems.  It's on the TODO list.\n\nHere's one strategy:  If you have a fixed-size footer, you can get\nfooters by checking $FORMATLINESLEFT before each write() and print\nthe footer yourself if necessary.\n\nHere's another strategy: Open a pipe to yourself, using \"open(MYSELF,\n\"|-\")\" (see \"open\" in perlfunc) and always write() to MYSELF instead of\nSTDOUT.  Have your child process massage its STDIN to rearrange headers\nand footers however you like.  Not very convenient, but doable.\n\nAccessing Formatting Internals\nFor low-level access to the formatting mechanism, you may use\nformline() and access $^A (the $ACCUMULATOR variable) directly.\n\nFor example:\n\n$str = formline <<'END', 1,2,3;\n@<<<  @|||  @>>>\nEND\n\nprint \"Wow, I just stored '$^A' in the accumulator!\\n\";\n\nOr to make an swrite() subroutine, which is to write() what sprintf()\nis to printf(), do this:\n\nuse Carp;\nsub swrite {\ncroak \"usage: swrite PICTURE ARGS\" unless @;\nmy $format = shift;\n$^A = \"\";\nformline($format,@);\nreturn $^A;\n}\n\n$string = swrite(<<'END', 1, 2, 3);\nCheck me out\n@<<<  @|||  @>>>\nEND\nprint $string;\n",
                "subsections": []
            },
            "WARNINGS": {
                "content": "The lone dot that ends a format can also prematurely end a mail message\npassing through a misconfigured Internet mailer (and based on\nexperience, such misconfiguration is the rule, not the exception).  So\nwhen sending format code through mail, you should indent it so that the\nformat-ending dot is not on the left margin; this will prevent SMTP\ncutoff.\n\nLexical variables (declared with \"my\") are not visible within a format\nunless the format is declared within the scope of the lexical variable.\n\nIf a program's environment specifies an LCNUMERIC locale and \"use\nlocale\" is in effect when the format is declared, the locale is used to\nspecify the decimal point character in formatted output.  Formatted\noutput cannot be controlled by \"use locale\" at the time when write() is\ncalled. See perllocale for further discussion of locale handling.\n\nWithin strings that are to be displayed in a fixed-length text field,\neach control character is substituted by a space. (But remember the\nspecial meaning of \"\\r\" when using fill mode.) This is done to avoid\nmisalignment when control characters \"disappear\" on some output media.\n\nperl v5.34.0                      2026-06-23                       PERLFORM(1)",
                "subsections": []
            }
        }
    }
}