NAME

bprintf — formatted output with named arguments

SYNOPSIS

bprintf format [field=value ...]

DESCRIPTION

The bprintf command is an advanced string formatting utility. It is a semantic wrapper for printf(1). bprintf replaces argument order with named arguments and can perform arithmetic within format specifications.

A format string can contain a set of substitutions. A substitution consists of a field name and an optional format specification. The format specification determines how the field value is interpreted and displayed. A single field may be used within multiple substitutions, each with its own formatting.

Format Syntax

The format string is reproduced on stdout after performing substitutions.

The backslash notation character escape sequences supported by printf(1) can be used. The ‘%’ character has no special meaning.

A substitution is enclosed in curly braces. To print a literal opening or closing curly brace escape it with a backslash, i.e. ‘\{’ and ‘\}’ respectively.

A substitution consists of the field name and an optional format specification:

{field[:specification]}

A substitution without a specification behaves like a ‘%s’ field in printf(1).

The format specification consists of the same flags, Field Width, Precision and Format characters described by printf(1). If the format character is not supplied, ‘s’ is implied. An arithmetic expression can be inserted into the format by enclosing it in parenthesis.

Arithmetic Expressions

Arithmetic expressions support the same Values, Constants and Variables as well as the same Unary, Binary and Conditional operators as described in the Arithmetic Expansion section of sh(1).

Note, this list does not include Assignment operators.

All variables referred to within an expression must have a corresponding field with an integral value assigned. Variables can be assigned values with the same syntax as constants, i.e. an optional sign followed by either a decimal value, hexadecimal value starting with ‘0x’ or an octal value starting with ‘0’.

Field Assignments

The format string may use all and any fields supplied by the subsequent field=value arguments. Fields not occurring in the format string are discarded from the output. Values are arbitrary unless used within arithmetic expressions.

Field names must be made up of the pattern ‘[a-zA-Z][a-zA-Z0-9_]*’.

EXIT STATUS

The following is a list of all anticipated exit codes:

EOK=0: Command completed successfully.
ESIGNAL=1: Interrupted by signal.
EFAIL=2: Generic application logic error.
ENOARGS=3: No format string was supplied.
ESUB=4: A substitution field has no corresponding field assignment argument.
EID=5: A substitution field name is illegal.
EFORMAT=6: A substitution format specification is ill-formed.
EEXPR=7: An arithmetic expression is ill-formed.
EASSIGN=8: An arithmetic expression contains an assignment.
EARG=9: An argument uses an illegal field name.
ETYPE=10: A field value used in an arithmetic expression is not an integer.

EXAMPLES

Simple substitution:

$ bprintf 'My name is {name}.\n' name=Johnny
My name is Johnny.

Using a field multiple times:

$ bprintf '{str:.5}\n{str:.10}\n{str}\n' str=SugarHoneyMilk
Sugar
SugarHoney
SugarHoneyMilk

Use different field types:

$ bprintf '{var:16} = {value:g} {unit}\n' var=g value=9.81 unit=mps^2
               g = 9.81 mps^2

Compute column width using arithmetic expressions:

$ bprintf '| {name:-16} | {val:(cols-36)} {unit:-12} |\n' cols=64 name=Name val=Value unit=Unit
| Name             |                        Value Unit         |
$ bprintf '| {name:-16} | {val:(cols-36).3f} {unit:-12} |\n' cols=64 name=g val=9.81 unit=mps^2
| g                |                        9.810 mps^2        |

HISTORY

The bprintf command was added with the bsda2-0.4.0 release.

AUTHORS

Dominic Fandrey <freebsd@k4m1.org>