datafmt

Overview ¶

Package datafmt implements syntax-directed, type-driven formatting of arbitrary data structures. Formatting a data structure consists of two phases: first, a parser reads a format specification and builds a "compiled" format. Then, the format can be applied repeatedly to arbitrary values. Applying a format to a value evaluates to a []byte containing the formatted value bytes, or nil.

A format specification is a set of package declarations and format rules:

Format      = [ Entry { ";" Entry } [ ";" ] ] .
Entry       = PackageDecl | FormatRule .

(The syntax of a format specification is presented in the same EBNF notation as used in the Go language specification. The syntax of white space, comments, identifiers, and string literals is the same as in Go.)

A package declaration binds a package name (such as 'ast') to a package import path (such as '"go/ast"'). Each package used (in a type name, see below) must be declared once before use.

PackageDecl = PackageName ImportPath .
PackageName = identifier .
ImportPath  = string .

A format rule binds a rule name to a format expression. A rule name may be a type name or one of the special names 'default' or '/'. A type name may be the name of a predeclared type (for example, 'int', 'float32', etc.), the package-qualified name of a user-defined type (for example, 'ast.MapType'), or an identifier indicating the structure of unnamed composite types ('array', 'chan', 'func', 'interface', 'map', or 'ptr'). Each rule must have a unique name; rules can be declared in any order.

FormatRule  = RuleName "=" Expression .
RuleName    = TypeName | "default" | "/" .
TypeName    = [ PackageName "." ] identifier .

To format a value, the value's type name is used to select the format rule (there is an override mechanism, see below). The format expression of the selected rule specifies how the value is formatted. Each format expression, when applied to a value, evaluates to a byte sequence or nil.

In its most general form, a format expression is a list of alternatives, each of which is a sequence of operands:

Expression  = [ Sequence ] { "|" [ Sequence ] } .
Sequence    = Operand { Operand } .

The formatted result produced by an expression is the result of the first alternative sequence that evaluates to a non-nil result; if there is no such alternative, the expression evaluates to nil. The result produced by an operand sequence is the concatenation of the results of its operands. If any operand in the sequence evaluates to nil, the entire sequence evaluates to nil.

There are five kinds of operands:

Operand     = Literal | Field | Group | Option | Repetition .

Literals evaluate to themselves, with two substitutions. First, %-formats expand in the manner of fmt.Printf, with the current value passed as the parameter. Second, the current indentation (see below) is inserted after every newline or form feed character.

Literal     = string .

This table shows string literals applied to the value 42 and the corresponding formatted result:

"foo"       foo
"%x"        2a
"x = %d"    x = 42
"%#x = %d"  0x2a = 42

A field operand is a field name optionally followed by an alternate rule name. The field name may be an identifier or one of the special names @ or *.

Field       = FieldName [ ":" RuleName ] .
FieldName   = identifier | "@" | "*" .

If the field name is an identifier, the current value must be a struct, and there must be a field with that name in the struct. The same lookup rules apply as in the Go language (for instance, the name of an anonymous field is the unqualified type name). The field name denotes the field value in the struct. If the field is not found, formatting is aborted and an error message is returned. (TODO consider changing the semantics such that if a field is not found, it evaluates to nil).

The special name '@' denotes the current value.

The meaning of the special name '*' depends on the type of the current value:

array, slice types   array, slice element (inside {} only, see below)
interfaces           value stored in interface
pointers             value pointed to by pointer

(Implementation restriction: channel, function and map types are not supported due to missing reflection support).

Fields are evaluated as follows: If the field value is nil, or an array or slice element does not exist, the result is nil (see below for details on array/slice elements). If the value is not nil the field value is formatted (recursively) using the rule corresponding to its type name, or the alternate rule name, if given.

The following example shows a complete format specification for a struct 'myPackage.Point'. Assume the package

package myPackage  // in directory myDir/myPackage
type Point struct {
	name string;
	x, y int;
}

Applying the format specification

myPackage "myDir/myPackage";
int = "%d";
hexInt = "0x%x";
string = "---%s---";
myPackage.Point = name "{" x ", " y:hexInt "}";

to the value myPackage.Point{"foo", 3, 15} results in

---foo---{3, 0xf}

Finally, an operand may be a grouped, optional, or repeated expression. A grouped expression ("group") groups a more complex expression (body) so that it can be used in place of a single operand:

Group       = "(" [ Indentation ">>" ] Body ")" .
Indentation = Expression .
Body        = Expression .

A group body may be prefixed by an indentation expression followed by '>>'. The indentation expression is applied to the current value like any other expression and the result, if not nil, is appended to the current indentation during the evaluation of the body (see also formatting state, below).

An optional expression ("option") is enclosed in '[]' brackets.

Option      = "[" Body "]" .

An option evaluates to its body, except that if the body evaluates to nil, the option expression evaluates to an empty []byte. Thus an option's purpose is to protect the expression containing the option from a nil operand.

A repeated expression ("repetition") is enclosed in '{}' braces.

Repetition  = "{" Body [ "/" Separator ] "}" .
Separator   = Expression .

A repeated expression is evaluated as follows: The body is evaluated repeatedly and its results are concatenated until the body evaluates to nil. The result of the repetition is the (possibly empty) concatenation, but it is never nil. An implicit index is supplied for the evaluation of the body: that index is used to address elements of arrays or slices. If the corresponding elements do not exist, the field denoting the element evaluates to nil (which in turn may terminate the repetition).

The body of a repetition may be followed by a '/' and a "separator" expression. If the separator is present, it is invoked between repetitions of the body.

The following example shows a complete format specification for formatting a slice of unnamed type. Applying the specification

int = "%b";
array = { * / ", " };  // array is the type name for an unnamed slice

to the value '[]int{2, 3, 5, 7}' results in

10, 11, 101, 111

Default rule: If a format rule named 'default' is present, it is used for formatting a value if no other rule was found. A common default rule is

default = "%v"

to provide default formatting for basic types without having to specify a specific rule for each basic type.

Global separator rule: If a format rule named '/' is present, it is invoked with the current value between literals. If the separator expression evaluates to nil, it is ignored.

For instance, a global separator rule may be used to punctuate a sequence of values with commas. The rules:

default = "%v";
/ = ", ";

will format an argument list by printing each one in its default format, separated by a comma and a space.