Documentation
¶
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.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Environment ¶
type Environment interface {
Copy() Environment
}
An application-specific environment may be provided to Format.Apply; the environment is available inside custom formatters via State.Env(). Environments must implement copying; the Copy method must return an complete copy of the receiver. This is necessary so that the formatter can save and restore an environment (in case of an absent expression).
If the Environment doesn't change during formatting (this is under control of the custom formatters), the Copy function can simply return the receiver, and thus can be very light-weight.
type Format ¶
type Format map[string]expr
A Format is the result of parsing a format specification. The format may be applied repeatedly to format values.
func Parse ¶
Parse parses a set of format productions from source src. Custom formatters may be provided via a map of formatter functions. If there are no errors, the result is a Format and the error is nil. Otherwise the format is nil and a non-empty ErrorList is returned.
func (Format) Eval ¶
func (f Format) Eval(env Environment, args ...interface{}) ([]byte, os.Error)
Eval formats each argument according to the format f and returns the resulting []byte and os.Error. If an error occurred, the []byte contains the partially formatted result. An environment env may be passed in which is available in custom formatters through the state parameter.
func (Format) Fprint ¶
Fprint formats each argument according to the format f and writes to w. The result is the total number of bytes written and an os.Error, if any.
type Formatter ¶
Custom formatters implement the Formatter function type. A formatter is invoked with the current formatting state, the value to format, and the rule name under which the formatter was installed (the same formatter function may be installed under different names). The formatter may access the current state to guide formatting and use State.Write to append to the state's output.
A formatter must return a boolean value indicating if it evaluated to a non-nil value (true), or a nil value (false).
type FormatterMap ¶
A FormatterMap is a set of custom formatters. It maps a rule name to a formatter function.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State represents the current formatting state. It is provided as argument to custom formatters.
func (*State) Env ¶
func (s *State) Env() interface{}
Env returns the environment passed to Format.Apply.
func (*State) LinePos ¶
LinePos returns the position of the current line beginning in the state's output buffer. Line numbers start at 1.
Source Files