FMTTEST(1)

💖 FMTTEST(1) — or, the General Commands Manual page where you test your nmh mh-format(5) language programs ✨

okay bestie, welcome to fmttest, straight out of the nmh universe 💅

---

🌸 NAME 🌸

fmttest — test programs in nmh's mh-format(5) language 🧚

like, that's it, that's the whole job description. it tests programs. in nmh's mh-format(5) language. no cap.

---

✨ SYNOPSIS ✨

fmttest [-help] [-version] [-form formatfile] [-format formatstring]
     [-address | -raw | -date | -message] [-file | -nofile] [--component
     component-text] [-dupaddrs | -nodupaddrs] [-ccme | -noccme]
     [-outsize size-in-characters] [-width column-width] [-msgnum
     number] [-msgcur flag] [-msgsize size] [-unseen flag] [-dump |
     -nodump] [-trace | -notrace] [+folder] [msgs | strings]

look at her. so many flags. so much range. she's giving main character energy fr fr 🎀

like, the way that there are choices in there (all those | pipes) means you pick one side of each pair, not both — the vibes are mutually exclusive and the manpage knows it 👑

and at the very end? you either hand her a +folder and some msgs, or you hand her strings — and honestly both are valid 💖

---

okay so that's the whole intro, the details are still loading, and we are SO not done yet — more coming right up, don't you dare close the terminal 💜

🌸 DESCRIPTION 🌸

okay bestie, fmttest is literally the tool you use to test programs written for the nmh format language, exactly as specified by mh-format(5). It's also intended to replace the ap, dp, and fmtdump programs. 💅

---

✨ Format Program Selection ✨

The -format string and -form formatfile specify a format string or file to read. A format string, if given, must be a single argument to the -format switch. If a format file name is passed to the -form switch, the file is searched for using the normal nmh rules: absolute pathnames are accessed directly, tilde expansion is done on usernames, and files are searched for in the user's Mail directory as specified in their profile. If it's not found there, the directory “/etc/nmh” is checked. 🦋

---

🦋 Mode Selection and Component Specification 🦋

fmttest has four operating modes — address, raw, date, and message — which are selected by the -address, -raw, -date, and -message switches, respectively.

Address mode treats every argument as an email address to be processed by nmh's email parser using the specified format program. The parsed address is made available as a special %{text} component escape, and the output from the program is printed on standard output. If there was an error parsing the email address, the error message is stored in the %{error} component escape. If no format program is given on the command line, the following default program is used:

%<{error}%{error}: %{text}%|%(putstr(proper{text}))%>

Address mode is equivalent to ap(8). 👑

In raw mode, no processing of the specified arguments is done. Each argument is run against the specified format program with the argument text available in the %{text} component. You must specify a format with -form or -format when using raw mode. 🚨

Date mode is identical to raw mode, with one exception: if no format is specified, the following format string is used:

%<(nodate{text})error: %{text}%|%(putstr(pretty{text}))%>

Date mode is equivalent to dp(8). 🎀

In message mode the arguments to fmttest are interpreted as an optional folder and messages. fmttest will read each specified message and make all of the components in the message available to the format program. Also, the appropriate information for the %(msg), %(cur), %(unseen), and %(size) function escapes will be made available for each message. If the -file switch is given, the arguments are interpreted as filenames instead of message numbers, but otherwise the behavior is the same (except that the %(msg), %(cur), and %(unseen) function escapes will not provide any useful information). 💖

The default format used in address mode is the default format used by scan. The following command can replicate the functionality of the repl command.

fmttest -nodupaddrs -form replcomps -outsize max [+folder] message

Regardless of the mode, other components can be provided to the format program by the use of the --component switch. For example, the following program will test the use of the “encrypted” component:

fmttest --encrypted yes -message cur

In message mode, components supplied on the command line will override components from messages. ✨

---

💅 Additional Switches 💅

• -dupaddrs and -nodupaddrs — control whether duplicate addresses are allowed or suppressed by the FORMATADDR instruction, which is used by the %(formataddr) function escape. In normal operation duplicate addresses are only suppressed by repl.
• -ccme and -noccme — control whether or not to count the user's local mailbox as a duplicate address. This replicates the behavior of the -cc me switch to repl, and only applies if -nodupaddrs is in effect.
• -outsize — controls the maximum number of printable characters that the format engine will produce. Characters marked as non-printing by the format engine with %(zputlit), characters with zero width, and extra bytes that are part of a multibyte character are not counted against this total. Two special values are supported: “max”, which means as many characters as the format engine can produce (limited by internal buffers), and “width”, which will set the value to the width of the terminal. In message mode it defaults to “width”, otherwise the default is “max”. 🌈
• -width — controls the column width which is used by the %(width) function escape. It defaults to the terminal width.
• -msgnum, -msgcur, -msgsize, and -unseen — all control the values used, respectively, by the following function escapes: %(num), %(cur), %(size), and %(unseen). If none are supplied, these values are taken from the message in message mode; in all other modes the default values are 0.

---

🔥 Compiling and Tracing Format Programs 🔥

• -dump — outputs the complete set of format instructions for the specified format program.
• -trace — will output each format instruction as it is being executed, and show the values of the num and str registers if they have changed from the previous instruction. The output buffer is also printed if it has changed from the previous instruction. 👀

---

👑 Format Instructions 👑

It should be noted that there is not a one-to-one correspondence between format escapes and format instructions; many instructions have side effects. Instructions prefixed with “LV” generally return a integer into the num (value) register; instructions prefixed with a “LS” return a string into the str register. 🧚

• COMP — Output component
• COMPF — Formatted output component
• LIT — Output literal text
• CHAR — Output single character
• NUM — Output the num register
• NUMF — Formatted output of the num register
• STR — Output the str register
• STRF — Formatted output of the str register
• STRFW — Not used
• PUTADDR — Output address list in str register
• STRLIT — Output str, no space compression
• STRLITZ — Like STRLIT, but not counted against width
• LS_COMP — Write component to str register
• LS_LIT — Write literal to str register
• LS_GETENV — Write environment var to str register
• LS_DECODECOMP — Decode RFC 2047 encoded component to str register
• LS_DECODE — Decode RFC 2047 encoded string to str register
• LS_TRIM — Trim trailing whitespace from str register
• LV_COMP — Convert component to integer, store in num register
• LV_COMPFLAG — Set num to 1 if TRUE set in component
• LV_LIT — Load literal value into num register
• LV_DAT — Load value from dat array into num register (see note)
• LV_STRLEN — Set num to the length of str
• LV_PLUS_L — Add value to num register
• LV_MINUS_L — Subtract value from num register
• LV_DIVIDE_L — Divide num register by value
• LV_MODULO_L — num modulo value
• LV_CHAR_LEFT — Store remaining number of printable chars in num
• LS_MONTH — Write short name of month to str from date component
• LS_LMONTH — Write long name of month to str from date component
• LS_ZONE — Write time zone offset to str from date component
• LS_DAY — Write short name of day of week to str from date component
• LS_WEEKDAY — Write long name of day of week to str from date component
• LS_822DATE — Write RFC 822 compatible date to str from date component
• LS_PRETTY — Write date with “pretty” timezone to str
• LV_SEC — Write date component seconds to num
• LV_MIN — Write date component minutes to num
• LV_HOUR — Write date component hour to num
• LV_MON — Write date component numeric month to num (start at 1)
• LV_YEAR — Write date component year to num
• LV_YDAY — Write date component Julian day to num
• LV_WDAY — Write date component day of week to num (0 == Sunday)
• LV_ZONE — Write date component time zone offset to num
• LV_CLOCK — Write date component in Unix epoch time to num
• LV_RCLOCK — Write offset of date component from current time to num
• LV_DAYF — Write 1 to num if day of week is explicit
• LV_DST — Write 1 to num if DST is in effect for date component
• LV_ZONEF — Write 1 to num if timezone is explicit
• LS_ADDR — Write email address of addr component to str
• LS_PERS — Write personal name of addr component to str
• LS_MBOX — Write mailbox (username) of addr component to str
• LS_HOST — Write host of addr component to str
• LS_PATH — Write host route of addr component to str
• LS_GNAME — Write group name of addr component to str
• LS_NOTE — Write note portion of addr component to str
• LS_822ADDR — Write “proper” RFC 822 version of addr component to str
• LS_FRIENDLY — Write friendly (name or note) of address component to str
• LS_UNQUOTE — Remove RFC 2822 quotes from string
• LV_HOSTTYPE — Set num to type of host (0=local, 1=network)
• LV_INGRPF — Set num to 1 if address was inside of group
• LV_NOHOSTF — Set num to 1 of no host was present in address component
• LOCALDATE — Convert date component to local timezone
• GMTDATE — Convert date component to GMT
• PARSEDATE — Parse date component
• PARSEADDR — Parse address component
• FORMATADDR — Add address component to list in str
• CONCATADDR — Like FORMATADDR, but will not suppress duplicates
• MYMBOX — Set num if address component is a local address
• SAVESTR — Save str register temporarily
• DONE — End program
• NOP — No operation
• GOTO — Jump to new instruction
• IF_S_NULL — Branch if str is NULL
• IF_S — Branch if str is not NULL
• IF_V_EQ — Branch if num is equal to value
• IF_V_NE — Branch if num is not equal to value
• IF_V_GT — Branch if num is greater than value
• IF_MATCH — Branch if str contains string
• IF_AMATCH — Branch if str starts with string
• S_NULL — Set num to 1 if str is NULL
• S_NONNULL — Set num to 1 if str is not NULL
• V_EQ — Set num to 1 if num equals value
• V_NE — Set num to 1 if num does not equal value
• V_GT — Set num to 1 if num is greater than value
• V_MATCH — Set num to 1 if str contains string
• V_AMATCH — Set num to 1 if str starts with string

The LV_DAT instruction is a bit special. Callers of the format library pass in an array of integers that are used by certain format escapes. The current list of format escapes and the indexes they use are:

dat[0]  %(num)
dat[1]  %(cur)
dat[2]  %(size)
dat[3]  %(width)
dat[4]  %(unseen)

---

🌈 SEE ALSO 🌈

mh-format(5), repl(1), ap(8), dp(8), fmtdump(8)

---

💜 DEFAULTS 💜

• -message
• -nofile
• -dupaddrs

---

🫶 CONTEXT 🫶

If a folder is given, it will become the current folder.

💀 BUGS 💀

okay so bestie, there's literally only one thing on the bug list and it's giving self-aware:

• it shouldn't require as much code from other programs as it does 🙈

that's it. that's the whole complaint. our girl is highkey dragging herself for being too needy with other programs' code, and honestly? relatable. we've all been there. ✨

ngl it's not a broken bug, it's more of a "she's doing the most and she knows it" bug. still counts, still documented, no cap. 💅

---

and that's the whole page, bestie, we ate 🍓✨ go forth and fmttest responsibly, you absolute icon 👑

with so much love from the nmh-1.8 era, dated 2014-08-31 🎀 (yes she's vintage, yes she still slays) 🦋💖