{
    "mode": "man",
    "parameter": "fmttest",
    "section": "1",
    "url": "https://www.chedong.com/phpMan.php/man/fmttest/1/json",
    "generated": "2026-05-30T11:55:13Z",
    "synopsis": "fmttest [-help] [-version] [-form formatfile] [-format formatstring] [-address | -raw | -date\n| -message] [-file | -nofile] [--component component-text] [-dupaddrs | -nodupaddrs]\n[-ccme | -noccme] [-outsize size-in-characters] [-width column-width] [-msgnum number]\n[-msgcur flag] [-msgsize size] [-unseen flag] [-dump | -nodump] [-trace | -notrace]\n[+folder] [msgs | strings]",
    "sections": {
        "NAME": {
            "content": "fmttest - test programs in nmh's mh-format(5) language\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "fmttest [-help] [-version] [-form formatfile] [-format formatstring] [-address | -raw | -date\n| -message] [-file | -nofile] [--component component-text] [-dupaddrs | -nodupaddrs]\n[-ccme | -noccme] [-outsize size-in-characters] [-width column-width] [-msgnum number]\n[-msgcur flag] [-msgsize size] [-unseen flag] [-dump | -nodump] [-trace | -notrace]\n[+folder] [msgs | strings]\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "fmttest  is used to test programs written for the nmh format language as specified by mh-for‐\nmat(5).  It is also intended to replace the ap, dp, and fmtdump programs.\n",
            "subsections": [
                {
                    "name": "Format Program Selection",
                    "content": "The -format string and -form formatfile specify a format string or file to  read.   A  format\nstring,  if given, must be a single argument to the -format switch.  If a format file name is\npassed to the -form, switch, the file is searched for using the normal  nmh  rules:  absolute\npathnames are accessed directly, tilde expansion is done on usernames, and files are searched\nfor in the user's Mail directory as specified in their profile.  If not found there, the  di‐\nrectory “/etc/nmh” is checked.\n"
                },
                {
                    "name": "Mode Selection and Component Specification",
                    "content": "fmttest  has  four  operating modes - address, raw, date, and message - which are selected by\nthe -address, -raw, -date, and -message switches, respectively.\n\nAddress mode treats every argument as an email address to be processed by nmh's email  parser\nusing  the  specified  format  program.   The  parsed  address is made available as a special\n%{text} component escape, and the output from the program is printed on standard output.   If\nthere was an error parsing the email address the error message is stored in the %{error} com‐\nponent escape.  If no format program is given on the command line, the following default pro‐\ngram is used:\n\n%<{error}%{error}: %{text}%|%(putstr(proper{text}))%>\n\nAddress mode is equivalent to ap(8).\n\nIn  raw mode, no processing of the specified arguments is done.  Each argument is run against\nthe specified format program with the argument text available in the %{text} component.   You\nmust specify a format with -form or -format when using raw mode.\n\nDate  mode  is identical to raw mode, with one exception: if no format is specified, the fol‐\nlowing format string is used:\n\n%<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>\n\nDate mode is equivalent to dp(8).\n\nIn message mode the arguments to fmttest are interpreted as an optional folder and  messages.\nfmttest will read each specified message and make all of the components in the message avail‐\nable to the format program.  Also, the appropriate information for the %(msg), %(cur),  %(un‐\nseen),  and  %(size)  function escapes will be made available for each message.  If the -file\nswitch is given, the arguments are interpreted as filenames instead of message  numbers,  but\notherwise  the  behavior  is the same (except that the %(msg), %(cur), and %(unseen) function\nescapes will not provide any useful information).\n\nThe default format used in address mode is the default format used by  scan.   The  following\ncommand can replicate the functionality of the repl command.\n\nfmttest -nodupaddrs -form replcomps -outsize max [+folder] message\n\nRegardless  of the mode, other components can be provided to the format program by the use of\nthe --component switch.  For example, the following program will test the  use  of  the  “en‐‐\ncrypted” component:\n\nfmttest --encrypted yes -message cur\n\nIn  message  mode, components supplied on the command line will override components from mes‐\nsages.\n"
                },
                {
                    "name": "Additional Switches",
                    "content": "The -dupaddrs and -nodupaddrs switches control whether duplicate  addresses  are  allowed  or\nsuppressed  by  the FORMATADDR instruction, which is used by the `%(formataddr)' function es‐\ncape.  In normal operation duplicate addresses are only suppressed by repl.\n\nThe -ccme and -noccme switches control whether or not to count the user's local mailbox as  a\nduplicate  address.   This replicates the behavior of the -cc me switch to repl, and only ap‐\nplies if -nodupaddrs is in effect.\n\nThe -outsize switch controls the maximum number of printable characters that the  format  en‐\ngine will produce.  Characters marked as non-printing by the format engine with `%(zputlit)',\ncharacters with zero width, and extra bytes that are part of a multibyte  character  are  not\ncounted  against  this  total.   Two special values are supported: “max”, which means as many\ncharacters as the format engine can produce (limited by internal buffers), and “width”, which\nwill  set  the  value  to the width of the terminal.  In message mode it defaults to “width”,\notherwise the default is “max”.\n\nThe -width switch controls the column width which is used by the `%(width)' function  escape.\nIt defaults to the terminal width.\n\nThe -msgnum, -msgcur, -msgsize, and the -unseen switches all control the values used, respec‐\ntively, by the following function escapes: `%(num)', `%(cur)',  `%(size)',  and  `%(unseen)'.\nIf  none  are supplied, these values are taken from the message in message mode; in all other\nmodes the default values are 0.\n"
                },
                {
                    "name": "Compiling and Tracing Format Programs",
                    "content": "The -dump switch outputs the complete set of format instructions  for  the  specified  format\nprogram.   The -trace switch will output each format instruction as it is being executed, and\nshow the values of the num and str registers if they have changed from the previous  instruc‐\ntion.  The output buffer is also printed if it has changed from the previous instruction.\n"
                },
                {
                    "name": "Format Instructions",
                    "content": "It  should  be noted that there is not a one-to-one correspondence between format escapes and\nformat instructions; many instructions have side effects.  Instructions  prefixed  with  “LV”\ngenerally  return  a integer into the num (value) register; instructions prefixed with a “LS”\nreturn a string into the str register.\n\nInstruction   Description\nCOMP          Output component\nCOMPF         Formatted output component\nLIT           Output literal text\nLITF          Formatted literal text output\nCHAR          Output single character\nNUM           Output the num register\nNUMF          Formatted output of the num register\nSTR           Output the str register\nSTRF          Formatted output of the str register\nSTRFW         Not used\nPUTADDR       Output address list in str register\nSTRLIT        Output str, no space compression\nSTRLITZ       Like STRLIT, but not counted against width\nLSCOMP       Write component to str register\nLSLIT        Write literal to str register\nLSGETENV     Write environment var to str register\nLSDECODECOMP Decode RFC 2047 encoded component to str register\nLSDECODE     Decode RFC 2047 encoded string to str register\nLSTRIM       Trim trailing whitespace from str register\nLVCOMP       Convert component to integer, store in num register\nLVCOMPFLAG   Set num to 1 if TRUE set in component\nLVLIT        Load literal value into num register\nLVDAT        Load value from dat array into num register (see note)\nLVSTRLEN     Set num to the length of str\nLVPLUSL     Add value to num register\nLVMINUSL    Subtract value from num register\nLVDIVIDEL   Divide num register by value\nLVMODULOL   num modulo value\nLVCHARLEFT  Store remaining number of printable chars in num\nLSMONTH      Write short name of month to str from date component\nLSLMONTH     Write long name of month to str from date component\nLSZONE       Write time zone offset to str from date component\nLSDAY        Write short name of day of week to str from date component\nLSWEEKDAY    Write long name of day of week to str from date component\nLS822DATE    Write RFC 822 compatible date to str from date component\nLSPRETTY     Write date with “pretty” timezone to str\nLVSEC        Write date component seconds to num\nLVMIN        Write date component minutes to num\nLVHOUR       Write date component hour to num\nLVMON        Write date component numeric month to num (start at 1)\nLVYEAR       Write date component year to num\nLVYDAY       Write date component Julian day to num\nLVWDAY       Write date component day of week to num (0 == Sunday)\nLVZONE       Write date component time zone offset to num\nLVCLOCK      Write date component in Unix epoch time to num\nLVRCLOCK     Write offset of date component from current time to num\nLVDAYF       Write 1 to num if day of week is explicit\nLVDST        Write 1 to num if DST is in effect for date component\nLVZONEF      Write 1 to num if timezone is explicit\nLSADDR       Write email address of addr component to str\nLSPERS       Write personal name of addr component to str\nLSMBOX       Write mailbox (username) of addr component to str\nLSHOST       Write host of addr component to str\nLSPATH       Write host route of addr component to str\nLSGNAME      Write group name of addr component to str\nLSNOTE       Write note portion of addr component to str\nLS822ADDR    Write “proper” RFC 822 version of addr component to str\nLSFRIENDLY   Write friendly (name or note) of address component to str\nLSUNQUOTE    Remove RFC 2822 quotes from string\nLVHOSTTYPE   Set num to type of host (0=local, 1=network)\nLVINGRPF     Set num to 1 if address was inside of group\nLVNOHOSTF    Set num to 1 of no host was present in address component\nLOCALDATE     Convert date component to local timezone\nGMTDATE       Convert date component to GMT\nPARSEDATE     Parse date component\nPARSEADDR     Parse address component\nFORMATADDR    Add address component to list in str\nCONCATADDR    Like FORMATADDR, but will not suppress duplicates\nMYMBOX        Set num if address component is a local address\nSAVESTR       Save str register temporarily\nDONE          End program\nNOP           No operation\nGOTO          Jump to new instruction\nIFSNULL     Branch if str is NULL\nIFS          Branch if str is not NULL\nIFVEQ       Branch if num is equal to value\nIFVNE       Branch if num is not equal to value\nIFVGT       Branch if num is greater than value\nIFMATCH      Branch if str contains string\nIFAMATCH     Branch if str starts with string\nSNULL        Set num to 1 if str is NULL\nSNONNULL     Set num to 1 if str is not NULL\nVEQ          Set num to 1 if num equals value\nVNE          Set num to 1 if num does not equal value\nVGT          Set num to 1 if num is greater than value\nVMATCH       Set num to 1 if str contains string\nVAMATCH      Set num to 1 if str starts with string\n\nThe LVDAT instruction is a bit special.  Callers of the format library pass in an  array  of\nintegers that are used by certain format escapes.  The current list of format escapes and the\nindexes they use are:\n\ndat[0]  %(num)\ndat[1]  %(cur)\ndat[2]  %(size)\ndat[3]  %(width)\ndat[4]  %(unseen)\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "mh-format(5), repl(1), ap(8), dp(8), fmtdump(8)\n",
            "subsections": []
        },
        "DEFAULTS": {
            "content": "`-message'\n`-nofile'\n`-dupaddrs'\n",
            "subsections": []
        },
        "BUGS": {
            "content": "It shouldn't require as much code from other programs as it does.\n\n\n\nnmh-1.7.1                                    2014-08-31                                 FMTTEST(1mh)",
            "subsections": []
        }
    },
    "summary": "fmttest - test programs in nmh's mh-format(5) language",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "mh-format",
            "section": "5",
            "url": "https://www.chedong.com/phpMan.php/man/mh-format/5/json"
        },
        {
            "name": "repl",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/repl/1/json"
        },
        {
            "name": "ap",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/ap/8/json"
        },
        {
            "name": "dp",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/dp/8/json"
        },
        {
            "name": "fmtdump",
            "section": "8",
            "url": "https://www.chedong.com/phpMan.php/man/fmtdump/8/json"
        }
    ]
}