.\" This file is in the public domain. .\" .\" Grr, why do .Bl/.El produce a blank line before but not after?! .\" It seems damn near impossible to get a blank line. .\" .D1 and .Dl with no argument produce a whine. .\" Neither of .\" .D1 \& .\" .D1 \&\ \& .\" work. .de bL .nf \&\ \& .br .fi .. .Dd December 31, 1996 .Dt HALIGN 1 .Os NetBSD 1.2BETA .Sh NAME .Nm halign .Nd line columns up .Sh SYNOPSIS .Nm .Op Fl flags .Op Ar column-spec ... .\" How the hell do I get what I want here? .\" I want... .\" [ [c[lr]lrx]flags[n] | -m | -ostr | -Ostr ] ... .\" .Op Fl b .\" .Op Fl B Ns Ar str .\" .Op Fl C .\" .Op Fl \&. .\" .Op Fl r .\" .Op Fl s .\" .Op Fl t .\" .Op Fl F Ns Ar c .\" .Bk -words .\" .Oo .\" .Oo .\" c .\" .Op lr .\" lrx .\" .Oc Ns flags Op n .\" \&| .\" .Fl m .\" \&| .\" .Fl o Ns Ar str .\" \&| .\" .Fl O Ns Ar str .\" .Oc ... .\" .Ek .\" The above produces .\" halign [-b] [-Bstr] [-C] [-.] [-r] [-s] [-t] [-Fc] [c lrx .\" [ [lr]]flags [n] | -m | -ostr | -Ostr] ... .Sh DESCRIPTION .Nm reads input, breaking each line into fields; it produces output with those fields lined up according to the specifications on the command line. By default, input fields are delimited by whitespace. .Pp The command line consists of zero or more flags followed by one or more column specifiers. The available flags are: .Bl -tag -width indent .It Fl b Consider leading whitespace on each line to be part of the first field. When the input field delimiter is whitespace (see .Fl F ) , leading whitespace on each line is normally stripped. .It Fl B Ns Ar str Consider the first field to be everything up to and including the first occurrence of .Ar str . .It Fl C Apply the .Ar C option to each field. .It Fl \&. Apply the .Ar \&. option to each field. .It Fl r Normally, fields after the last field specified on the command line are discarded. With this option, no field delimiters are recognized once the last field starts; the .Sq last field is the rest of the line. (This is useful for aligning things like lists of manifest contents in C code, where each line maybe tagged with a comment.) .It Fl s Don't strip trailing spaces from each output line. Normally, .Nm removes all trailing spaces from each line before printing it. With this option, this is not done. .It Fl F Ns Ar char Change the input field separator from whitespace to .Ar char . Multiple consecutive .Ar char Ns s will produce empty fields. If .Ar char is omitted, set the input field separator to the default, which is that fields are separated by (possibly multiple) whitespace characters. .It Fl t A convenient abbreviation for the common case of .Fl F with a tab as the separator character. (Actually using .Fl F with a tab works, but requires quoting for most shells.) .It Fl x Ns Ar regex .It Fl j Ns Ar regex Process only lines that match .Pf ( Fl j , .Sq just ) or don't match .Pf ( Fl x , .Sq exclude ) .Ar regex . Lines not processed are copied to the output unchanged, in their original position relative to other lines. Multiple .Fl j or .Fl x options may be given; when both options are used, the behavior is as if the list of .Ar regex Ns es is scanned in the order they appear on the command line, with the first match terminating the scan. If none match, the action is the complement of the action specified by the last such option. As a special case, specifying a zero-length .Ar regex will never match and serves only to change the default action if it turns out to be the last such option. (If no .Fl j or .Fl x options at all are given, all lines are processed.) .El .Pp A column specifier consists of an alignment spec, followed by zero or more option indicators, followed by an optional minimum width. The entire alignment spec must be a single argument to .Nm halign ; if it contains characters such as whitespace, it may be necessary to quote it to protect it from the shell. The alignment spec can be .Bl -tag -width indent .It Ar l This column is to be aligned left; field contents are to appear at the far left edge of the field. .It Ar r This column is to be aligned right; field contents are to appear at the far right edge of the field. .It Ar c This column is to be centered; padding on the left and right of the contents are to be equal. Since .Nm works on the assumption of fixed-width characters, it will not always be able to do this exactly; to control where the extra space goes in cases where an odd number of padding characters are called for, this spec can appear as .Ar cl or .Ar cr . .It Ar x This column is to be omitted entirely from the output. .El .bL The option indicators are zero or more of .Bl -tag -width indent .It Ar C C-style quoting is allowed in this field. Single and double quote characters \&' and \&" quote everything up to the matching quote character, preventing recognition of what would otherwise be field delimiters. This option also understands backslash escapes; in accordance with C, even a newline can appear if it is backslashed, though .Nm will treat such a newline as a character occupying a single column like any other, thus throwing off the appearance of the output. .It Ar \&. This field is to be treated as numbers and aligned accordingly. The field contents are examined looking for a .Sq \&. ; the first one found is used as the alignment point (the dots will appear above one another). If no dot is found, one is implicitly provided at the far right edge of the field. The alignment spec is ignored unless an explicit width is given that is wider than the otherwise-resulting column, in which case the alignment spec controls where the lined-up numbers appear in the output field. There is currently no way to line up on anything but the first dot in the field. .It Ar pX When padding this field for output, pad with .Ar X instead of spaces. .It Ar PXY When padding this field for output, pad with .Ar X on the left and .Ar Y on the right, instead of using spaces. (If the alignment spec specifies left or right alignment, one of the characters will never be used.) .It min= Ns Ar width Ns Op \&, This field will consume at least .Ar width characters of input, regardless of what they are (delimiters occurring within the first .Ar width characters of the field will not be recognized). The only way the field can be shorter than .Ar width is if the line ends before that. The trailing comma is optional and necessary only when the next character after .Ar width is a digit. .It max= Ns Ar width Ns Op \&, This field will consume no more than .Ar width characters of input; if no delimiter is encountered earlier, one will be effectively inserted after that many characters. The trailing comma is optional and necessary only when the next character after .Ar width is a digit. .It trunc= Ns Ar width Ns Op \&, This field is read from the input normally (possibly affected by other options), but is truncated to no more than .Ar width characters after reading. This differs from the max= option in that trunc= discards characters after reading; max= refuses to read them. The trailing comma is optional and necessary only when the next character after .Ar width is a digit. .El .bL The optional minimum width, if specified, takes the form of a string of digits following the options (if any, or following the alignment spec if there are no options). By default, a column is as narrow as possible while still containing all entries; if the specified width is greater than the width computed this way, the column is expanded to the width specified. (There is no way to specify a maximum width; .Nm does not truncate fields.) .Pp Intermixed with the column specifiers can be any of three options: .Bl -tag -width indent .It Fl m This option can be used to specify a repeating pattern of column specifiers without having to list them all or having to know exactly how many there are. The position of the .Fl m is remembered, and if more columns appear in the input than are specified on the command line, specifiers are reused starting just after the .Fl m and continuing until the end of the command line, repeating this as often as necessary to account for all columns found in the input. (If .Fl m is used in conjunction with the global .Fl r option, the latter takes precedence, because once the .Sq last field is started, no more field delimiters are recognized, so extra fields will never be seen in the input.) .It Fl o Ns Ar str Normally, .Nm puts one space between columns on output. The .Fl o option specifies some other output separator string. The specified .Ar str will be placed between the column before this option and the column after it, when those columns are output. (Using this option before the first column specifier is accepted but useless; using it after the last is, except as described below, equally useless.) .It Fl O Ns Ar str This is just like .Fl o Ns Ar str , but not only changes the separator at the position it appears at but also changes the default separator for later columns that have no explicit separator specified. .El .bL When .Fl m is used in conjunction with .Fl o or .Fl O , output separators are generated based on attaching separators to the columns before them; separators are attached to columns as the argument list is scanned, and column duplication due to .Fl m duplicates the attached separators too. (This is the only case where using .Fl o (or .Fl O ) after the last column can be useful.) .Pp .Nm must of course read its input to EOF before it can generate any output, so it can compute how wide its columns are going to be. Files in .Pa /tmp are used to buffer the data, one file per column. As a result, too many columns will cause it to run out of file descriptors. (Columns with an alignment spec of .Ar x do not count against this limit, but using .Fl j or .Fl x will require one extra file.) .Sh AUTHOR der Mouse, .Aq mouse@rodents.montreal.qc.ca .