internal/catmsg/catmsg.go - text - Git at Google

 // Copyright 2017 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // Package catmsg contains support types for package x/text/message/catalog.
 //
 // This package contains the low-level implementations of Message used by the
 // catalog package and provides primitives for other packages to implement their
 // own. For instance, the plural package provides functionality for selecting
 // translation strings based on the plural category of substitution arguments.
 //
 //
 // Encoding and Decoding
 //
 // Catalogs store Messages encoded as a single string. Compiling a message into
 // a string both results in compacter representation and speeds up evaluation.
 //
 // A Message must implement a Compile method to convert its arbitrary
 // representation to a string. The Compile method takes an Encoder which
 // facilitates serializing the message. Encoders also provide more context of
 // the messages's creation (such as for which language the message is intended),
 // which may not be known at the time of the creation of the message.
 //
 // Each message type must also have an accompanying decoder registered to decode
 // the message. This decoder takes a Decoder argument which provides the
 // counterparts for the decoding.
 //
 //
 // Renderers
 //
 // A Decoder must be initialized with a Renderer implementation. These
 // implementations must be provided by packages that use Catalogs, typically
 // formatting packages such as x/text/message. A typical user will not need to
 // worry about this type; it is only relevant to packages that do string
 // formatting and want to use the catalog package to handle localized strings.
 //
 // A package that uses catalogs for selecting strings receives selection results
 // as sequence of substrings passed to the Renderer. The following snippet shows
 // how to express the above example using the message package.
 //
 //   message.Set(language.English, "You are %d minute(s) late.",
 //       catalog.Var("minutes", plural.Select(1, "one", "minute")),
 //       catalog.String("You are %[1]d ${minutes} late."))
 //
 //   p := message.NewPrinter(language.English)
 //   p.Printf("You are %d minute(s) late.", 5) // always 5 minutes late.
 //
 // To evaluate the Printf, package message wraps the arguments in a Renderer
 // that is passed to the catalog for message decoding. The call sequence that
 // results from evaluating the above message, assuming the person is rather
 // tardy, is:
 //
 //   Render("You are %[1]d ")
 //   Arg(1)
 //   Render("minutes")
 //   Render(" late.")
 //
 // The calls to Arg is caused by the plural.Select execution, which evaluates
 // the argument to determine whether the singular or plural message form should
 // be selected. The calls to Render reports the partial results to the message
 // package for further evaluation.
 package catmsg

 import (
 	"errors"
 	"fmt"
 	"strconv"
 	"strings"
 	"sync"

 	"golang.org/x/text/language"
 )

 // A Handle refers to a registered message type.
 type Handle int

 // A Handler decodes and evaluates data compiled by a Message and sends the
 // result to the Decoder. The output may depend on the value of the substitution
 // arguments, accessible by the Decoder's Arg method. The Handler returns false
 // if there is no translation for the given substitution arguments.
 type Handler func(d *Decoder) bool

 // Register records the existence of a message type and returns a Handle that
 // can be used in the Encoder's EncodeMessageType method to create such
 // messages. The prefix of the name should be the package path followed by
 // an optional disambiguating string.
 // Register will panic if a handle for the same name was already registered.
 func Register(name string, handler Handler) Handle {
 	mutex.Lock()
 	defer mutex.Unlock()

 	if _, ok := names[name]; ok {
 		panic(fmt.Errorf("catmsg: handler for %q already exists", name))
 	}
 	h := Handle(len(handlers))
 	names[name] = h
 	handlers = append(handlers, handler)
 	return h
 }

 // These handlers require fixed positions in the handlers slice.
 const (
 	msgVars Handle = iota
 	msgFirst
 	msgRaw
 	msgString
 	msgAffix
 	// Leave some arbitrary room for future expansion: 20 should suffice.
 	numInternal = 20
 )

 const prefix = "golang.org/x/text/internal/catmsg."

 var (
 	// TODO: find a more stable way to link handles to message types.
 	mutex sync.Mutex
 	names = map[string]Handle{
 		prefix + "Vars":   msgVars,
 		prefix + "First":  msgFirst,
 		prefix + "Raw":    msgRaw,
 		prefix + "String": msgString,
 		prefix + "Affix":  msgAffix,
 	}
 	handlers = make([]Handler, numInternal)
 )

 func init() {
 	// This handler is a message type wrapper that initializes a decoder
 	// with a variable block. This message type, if present, is always at the
 	// start of an encoded message.
 	handlers[msgVars] = func(d *Decoder) bool {
 		blockSize := int(d.DecodeUint())
 		d.vars = d.data[:blockSize]
 		d.data = d.data[blockSize:]
 		return d.executeMessage()
 	}

 	// First takes the first message in a sequence that results in a match for
 	// the given substitution arguments.
 	handlers[msgFirst] = func(d *Decoder) bool {
 		for !d.Done() {
 			if d.ExecuteMessage() {
 				return true
 			}
 		}
 		return false
 	}

 	handlers[msgRaw] = func(d *Decoder) bool {
 		d.Render(d.data)
 		return true
 	}

 	// A String message alternates between a string constant and a variable
 	// substitution.
 	handlers[msgString] = func(d *Decoder) bool {
 		for !d.Done() {
 			if str := d.DecodeString(); str != "" {
 				d.Render(str)
 			}
 			if d.Done() {
 				break
 			}
 			d.ExecuteSubstitution()
 		}
 		return true
 	}

 	handlers[msgAffix] = func(d *Decoder) bool {
 		// TODO: use an alternative method for common cases.
 		prefix := d.DecodeString()
 		suffix := d.DecodeString()
 		if prefix != "" {
 			d.Render(prefix)
 		}
 		ret := d.ExecuteMessage()
 		if suffix != "" {
 			d.Render(suffix)
 		}
 		return ret
 	}
 }

 var (
 	// ErrIncomplete indicates a compiled message does not define translations
 	// for all possible argument values. If this message is returned, evaluating
 	// a message may result in the ErrNoMatch error.
 	ErrIncomplete = errors.New("catmsg: incomplete message; may not give result for all inputs")

 	// ErrNoMatch indicates no translation message matched the given input
 	// parameters when evaluating a message.
 	ErrNoMatch = errors.New("catmsg: no translation for inputs")
 )

 // A Message holds a collection of translations for the same phrase that may
 // vary based on the values of substitution arguments.
 type Message interface {
 	// Compile encodes the format string(s) of the message as a string for later
 	// evaluation.
 	//
 	// The first call Compile makes on the encoder must be EncodeMessageType.
 	// The handle passed to this call may either be a handle returned by
 	// Register to encode a single custom message, or HandleFirst followed by
 	// a sequence of calls to EncodeMessage.
 	//
 	// Compile must return ErrIncomplete if it is possible for evaluation to
 	// not match any translation for a given set of formatting parameters.
 	// For example, selecting a translation based on plural form may not yield
 	// a match if the form "Other" is not one of the selectors.
 	//
 	// Compile may return any other application-specific error. For backwards
 	// compatibility with package like fmt, which often do not do sanity
 	// checking of format strings ahead of time, Compile should still make an
 	// effort to have some sensible fallback in case of an error.
 	Compile(e *Encoder) error
 }

 // Compile converts a Message to a data string that can be stored in a Catalog.
 // The resulting string can subsequently be decoded by passing to the Execute
 // method of a Decoder.
 func Compile(tag language.Tag, macros Dictionary, m Message) (data string, err error) {
 	// TODO: pass macros so they can be used for validation.
 	v := &Encoder{inBody: true} // encoder for variables
 	v.root = v
 	e := &Encoder{root: v, parent: v, tag: tag} // encoder for messages
 	err = m.Compile(e)
 	// This package serves te message package, which in turn is meant to be a
 	// drop-in replacement for fmt.  With the fmt package, format strings are
 	// evaluated lazily and errors are handled by substituting strings in the
 	// result, rather then returning an error. Dealing with multiple languages
 	// makes it more important to check errors ahead of time. We chose to be
 	// consistent and compatible and allow graceful degradation in case of
 	// errors.
 	buf := e.buf[stripPrefix(e.buf):]
 	if len(v.buf) > 0 {
 		// Prepend variable block.
 		b := make([]byte, 1+maxVarintBytes+len(v.buf)+len(buf))
 		b[0] = byte(msgVars)
 		b = b[:1+encodeUint(b[1:], uint64(len(v.buf)))]
 		b = append(b, v.buf...)
 		b = append(b, buf...)
 		buf = b
 	}
 	if err == nil {
 		err = v.err
 	}
 	return string(buf), err
 }

 // FirstOf is a message type that prints the first message in the sequence that
 // resolves to a match for the given substitution arguments.
 type FirstOf []Message

 // Compile implements Message.
 func (s FirstOf) Compile(e *Encoder) error {
 	e.EncodeMessageType(msgFirst)
 	err := ErrIncomplete
 	for i, m := range s {
 		if err == nil {
 			return fmt.Errorf("catalog: message argument %d is complete and blocks subsequent messages", i-1)
 		}
 		err = e.EncodeMessage(m)
 	}
 	return err
 }

 // Var defines a message that can be substituted for a placeholder of the same
 // name. If an expression does not result in a string after evaluation, Name is
 // used as the substitution. For example:
 //    Var{
 //      Name:    "minutes",
 //      Message: plural.Select(1, "one", "minute"),
 //    }
 // will resolve to minute for singular and minutes for plural forms.
 type Var struct {
 	Name    string
 	Message Message
 }

 var errIsVar = errors.New("catmsg: variable used as message")

 // Compile implements Message.
 //
 // Note that this method merely registers a variable; it does not create an
 // encoded message.
 func (v *Var) Compile(e *Encoder) error {
 	if err := e.addVar(v.Name, v.Message); err != nil {
 		return err
 	}
 	// Using a Var by itself is an error. If it is in a sequence followed by
 	// other messages referring to it, this error will be ignored.
 	return errIsVar
 }

 // Raw is a message consisting of a single format string that is passed as is
 // to the Renderer.
 //
 // Note that a Renderer may still do its own variable substitution.
 type Raw string

 // Compile implements Message.
 func (r Raw) Compile(e *Encoder) (err error) {
 	e.EncodeMessageType(msgRaw)
 	// Special case: raw strings don't have a size encoding and so don't use
 	// EncodeString.
 	e.buf = append(e.buf, r...)
 	return nil
 }

 // String is a message consisting of a single format string which contains
 // placeholders that may be substituted with variables.
 //
 // Variable substitutions are marked with placeholders and a variable name of
 // the form ${name}. Any other substitutions such as Go templates or
 // printf-style substitutions are left to be done by the Renderer.
 //
 // When evaluation a string interpolation, a Renderer will receive separate
 // calls for each placeholder and interstitial string. For example, for the
 // message: "%[1]v ${invites} %[2]v to ${their} party." The sequence of calls
 // is:
 //   d.Render("%[1]v ")
 //   d.Arg(1)
 //   d.Render(resultOfInvites)
 //   d.Render(" %[2]v to ")
 //   d.Arg(2)
 //   d.Render(resultOfTheir)
 //   d.Render(" party.")
 // where the messages for "invites" and "their" both use a plural.Select
 // referring to the first argument.
 //
 // Strings may also invoke macros. Macros are essentially variables that can be
 // reused. Macros may, for instance, be used to make selections between
 // different conjugations of a verb. See the catalog package description for an
 // overview of macros.
 type String string

 // Compile implements Message. It parses the placeholder formats and returns
 // any error.
 func (s String) Compile(e *Encoder) (err error) {
 	msg := string(s)
 	const subStart = "${"
 	hasHeader := false
 	p := 0
 	b := []byte{}
 	for {
 		i := strings.Index(msg[p:], subStart)
 		if i == -1 {
 			break
 		}
 		b = append(b, msg[p:p+i]...)
 		p += i + len(subStart)
 		if i = strings.IndexByte(msg[p:], '}'); i == -1 {
 			b = append(b, "$!(MISSINGBRACE)"...)
 			err = fmt.Errorf("catmsg: missing '}'")
 			p = len(msg)
 			break
 		}
 		name := strings.TrimSpace(msg[p : p+i])
 		if q := strings.IndexByte(name, '('); q == -1 {
 			if !hasHeader {
 				hasHeader = true
 				e.EncodeMessageType(msgString)
 			}
 			e.EncodeString(string(b))
 			e.EncodeSubstitution(name)
 			b = b[:0]
 		} else if j := strings.IndexByte(name[q:], ')'); j == -1 {
 			// TODO: what should the error be?
 			b = append(b, "$!(MISSINGPAREN)"...)
 			err = fmt.Errorf("catmsg: missing ')'")
 		} else if x, sErr := strconv.ParseUint(strings.TrimSpace(name[q+1:q+j]), 10, 32); sErr != nil {
 			// TODO: handle more than one argument
 			b = append(b, "$!(BADNUM)"...)
 			err = fmt.Errorf("catmsg: invalid number %q", strings.TrimSpace(name[q+1:q+j]))
 		} else {
 			if !hasHeader {
 				hasHeader = true
 				e.EncodeMessageType(msgString)
 			}
 			e.EncodeString(string(b))
 			e.EncodeSubstitution(name[:q], int(x))
 			b = b[:0]
 		}
 		p += i + 1
 	}
 	b = append(b, msg[p:]...)
 	if !hasHeader {
 		// Simplify string to a raw string.
 		Raw(string(b)).Compile(e)
 	} else if len(b) > 0 {
 		e.EncodeString(string(b))
 	}
 	return err
 }

 // Affix is a message that adds a prefix and suffix to another message.
 // This is mostly used add back whitespace to a translation that was stripped
 // before sending it out.
 type Affix struct {
 	Message Message
 	Prefix  string
 	Suffix  string
 }

 // Compile implements Message.
 func (a Affix) Compile(e *Encoder) (err error) {
 	// TODO: consider adding a special message type that just adds a single
 	// return. This is probably common enough to handle the majority of cases.
 	// Get some stats first, though.
 	e.EncodeMessageType(msgAffix)
 	e.EncodeString(a.Prefix)
 	e.EncodeString(a.Suffix)
 	e.EncodeMessage(a.Message)
 	return nil
 }
	// Copyright 2017 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// Package catmsg contains support types for package x/text/message/catalog.
	//
	// This package contains the low-level implementations of Message used by the
	// catalog package and provides primitives for other packages to implement their
	// own. For instance, the plural package provides functionality for selecting
	// translation strings based on the plural category of substitution arguments.
	//
	//
	// Encoding and Decoding
	//
	// Catalogs store Messages encoded as a single string. Compiling a message into
	// a string both results in compacter representation and speeds up evaluation.
	//
	// A Message must implement a Compile method to convert its arbitrary
	// representation to a string. The Compile method takes an Encoder which
	// facilitates serializing the message. Encoders also provide more context of
	// the messages's creation (such as for which language the message is intended),
	// which may not be known at the time of the creation of the message.
	//
	// Each message type must also have an accompanying decoder registered to decode
	// the message. This decoder takes a Decoder argument which provides the
	// counterparts for the decoding.
	//
	//
	// Renderers
	//
	// A Decoder must be initialized with a Renderer implementation. These
	// implementations must be provided by packages that use Catalogs, typically
	// formatting packages such as x/text/message. A typical user will not need to
	// worry about this type; it is only relevant to packages that do string
	// formatting and want to use the catalog package to handle localized strings.
	//
	// A package that uses catalogs for selecting strings receives selection results
	// as sequence of substrings passed to the Renderer. The following snippet shows
	// how to express the above example using the message package.
	//
	// message.Set(language.English, "You are %d minute(s) late.",
	// catalog.Var("minutes", plural.Select(1, "one", "minute")),
	// catalog.String("You are %[1]d ${minutes} late."))
	//
	// p := message.NewPrinter(language.English)
	// p.Printf("You are %d minute(s) late.", 5) // always 5 minutes late.
	//
	// To evaluate the Printf, package message wraps the arguments in a Renderer
	// that is passed to the catalog for message decoding. The call sequence that
	// results from evaluating the above message, assuming the person is rather
	// tardy, is:
	//
	// Render("You are %[1]d ")
	// Arg(1)
	// Render("minutes")
	// Render(" late.")
	//
	// The calls to Arg is caused by the plural.Select execution, which evaluates
	// the argument to determine whether the singular or plural message form should
	// be selected. The calls to Render reports the partial results to the message
	// package for further evaluation.
	package catmsg

	import (
	"errors"
	"fmt"
	"strconv"
	"strings"
	"sync"

	"golang.org/x/text/language"
	)

	// A Handle refers to a registered message type.
	type Handle int

	// A Handler decodes and evaluates data compiled by a Message and sends the
	// result to the Decoder. The output may depend on the value of the substitution
	// arguments, accessible by the Decoder's Arg method. The Handler returns false
	// if there is no translation for the given substitution arguments.
	type Handler func(d *Decoder) bool

	// Register records the existence of a message type and returns a Handle that
	// can be used in the Encoder's EncodeMessageType method to create such
	// messages. The prefix of the name should be the package path followed by
	// an optional disambiguating string.
	// Register will panic if a handle for the same name was already registered.
	func Register(name string, handler Handler) Handle {
	mutex.Lock()
	defer mutex.Unlock()

	if _, ok := names[name]; ok {
	panic(fmt.Errorf("catmsg: handler for %q already exists", name))
	}
	h := Handle(len(handlers))
	names[name] = h
	handlers = append(handlers, handler)
	return h
	}

	// These handlers require fixed positions in the handlers slice.
	const (
	msgVars Handle = iota
	msgFirst
	msgRaw
	msgString
	msgAffix
	// Leave some arbitrary room for future expansion: 20 should suffice.
	numInternal = 20
	)

	const prefix = "golang.org/x/text/internal/catmsg."

	var (
	// TODO: find a more stable way to link handles to message types.
	mutex sync.Mutex
	names = map[string]Handle{
	prefix + "Vars": msgVars,
	prefix + "First": msgFirst,
	prefix + "Raw": msgRaw,
	prefix + "String": msgString,
	prefix + "Affix": msgAffix,
	}
	handlers = make([]Handler, numInternal)
	)

	func init() {
	// This handler is a message type wrapper that initializes a decoder
	// with a variable block. This message type, if present, is always at the
	// start of an encoded message.
	handlers[msgVars] = func(d *Decoder) bool {
	blockSize := int(d.DecodeUint())
	d.vars = d.data[:blockSize]
	d.data = d.data[blockSize:]
	return d.executeMessage()
	}

	// First takes the first message in a sequence that results in a match for
	// the given substitution arguments.
	handlers[msgFirst] = func(d *Decoder) bool {
	for !d.Done() {
	if d.ExecuteMessage() {
	return true
	}
	}
	return false
	}

	handlers[msgRaw] = func(d *Decoder) bool {
	d.Render(d.data)
	return true
	}

	// A String message alternates between a string constant and a variable
	// substitution.
	handlers[msgString] = func(d *Decoder) bool {
	for !d.Done() {
	if str := d.DecodeString(); str != "" {
	d.Render(str)
	}
	if d.Done() {
	break
	}
	d.ExecuteSubstitution()
	}
	return true
	}

	handlers[msgAffix] = func(d *Decoder) bool {
	// TODO: use an alternative method for common cases.
	prefix := d.DecodeString()
	suffix := d.DecodeString()
	if prefix != "" {
	d.Render(prefix)
	}
	ret := d.ExecuteMessage()
	if suffix != "" {
	d.Render(suffix)
	}
	return ret
	}
	}

	var (
	// ErrIncomplete indicates a compiled message does not define translations
	// for all possible argument values. If this message is returned, evaluating
	// a message may result in the ErrNoMatch error.
	ErrIncomplete = errors.New("catmsg: incomplete message; may not give result for all inputs")

	// ErrNoMatch indicates no translation message matched the given input
	// parameters when evaluating a message.
	ErrNoMatch = errors.New("catmsg: no translation for inputs")
	)

	// A Message holds a collection of translations for the same phrase that may
	// vary based on the values of substitution arguments.
	type Message interface {
	// Compile encodes the format string(s) of the message as a string for later
	// evaluation.
	//
	// The first call Compile makes on the encoder must be EncodeMessageType.
	// The handle passed to this call may either be a handle returned by
	// Register to encode a single custom message, or HandleFirst followed by
	// a sequence of calls to EncodeMessage.
	//
	// Compile must return ErrIncomplete if it is possible for evaluation to
	// not match any translation for a given set of formatting parameters.
	// For example, selecting a translation based on plural form may not yield
	// a match if the form "Other" is not one of the selectors.
	//
	// Compile may return any other application-specific error. For backwards
	// compatibility with package like fmt, which often do not do sanity
	// checking of format strings ahead of time, Compile should still make an
	// effort to have some sensible fallback in case of an error.
	Compile(e *Encoder) error
	}

	// Compile converts a Message to a data string that can be stored in a Catalog.
	// The resulting string can subsequently be decoded by passing to the Execute
	// method of a Decoder.
	func Compile(tag language.Tag, macros Dictionary, m Message) (data string, err error) {
	// TODO: pass macros so they can be used for validation.
	v := &Encoder{inBody: true} // encoder for variables
	v.root = v
	e := &Encoder{root: v, parent: v, tag: tag} // encoder for messages
	err = m.Compile(e)
	// This package serves te message package, which in turn is meant to be a
	// drop-in replacement for fmt. With the fmt package, format strings are
	// evaluated lazily and errors are handled by substituting strings in the
	// result, rather then returning an error. Dealing with multiple languages
	// makes it more important to check errors ahead of time. We chose to be
	// consistent and compatible and allow graceful degradation in case of
	// errors.
	buf := e.buf[stripPrefix(e.buf):]
	if len(v.buf) > 0 {
	// Prepend variable block.
	b := make([]byte, 1+maxVarintBytes+len(v.buf)+len(buf))
	b[0] = byte(msgVars)
	b = b[:1+encodeUint(b[1:], uint64(len(v.buf)))]
	b = append(b, v.buf...)
	b = append(b, buf...)
	buf = b
	}
	if err == nil {
	err = v.err
	}
	return string(buf), err
	}

	// FirstOf is a message type that prints the first message in the sequence that
	// resolves to a match for the given substitution arguments.
	type FirstOf []Message

	// Compile implements Message.
	func (s FirstOf) Compile(e *Encoder) error {
	e.EncodeMessageType(msgFirst)
	err := ErrIncomplete
	for i, m := range s {
	if err == nil {
	return fmt.Errorf("catalog: message argument %d is complete and blocks subsequent messages", i-1)
	}
	err = e.EncodeMessage(m)
	}
	return err
	}

	// Var defines a message that can be substituted for a placeholder of the same
	// name. If an expression does not result in a string after evaluation, Name is
	// used as the substitution. For example:
	// Var{
	// Name: "minutes",
	// Message: plural.Select(1, "one", "minute"),
	// }
	// will resolve to minute for singular and minutes for plural forms.
	type Var struct {
	Name string
	Message Message
	}

	var errIsVar = errors.New("catmsg: variable used as message")

	// Compile implements Message.
	//
	// Note that this method merely registers a variable; it does not create an
	// encoded message.
	func (v Var) Compile(e Encoder) error {
	if err := e.addVar(v.Name, v.Message); err != nil {
	return err
	}
	// Using a Var by itself is an error. If it is in a sequence followed by
	// other messages referring to it, this error will be ignored.
	return errIsVar
	}

	// Raw is a message consisting of a single format string that is passed as is
	// to the Renderer.
	//
	// Note that a Renderer may still do its own variable substitution.
	type Raw string

	// Compile implements Message.
	func (r Raw) Compile(e *Encoder) (err error) {
	e.EncodeMessageType(msgRaw)
	// Special case: raw strings don't have a size encoding and so don't use
	// EncodeString.
	e.buf = append(e.buf, r...)
	return nil
	}

	// String is a message consisting of a single format string which contains
	// placeholders that may be substituted with variables.
	//
	// Variable substitutions are marked with placeholders and a variable name of
	// the form ${name}. Any other substitutions such as Go templates or
	// printf-style substitutions are left to be done by the Renderer.
	//
	// When evaluation a string interpolation, a Renderer will receive separate
	// calls for each placeholder and interstitial string. For example, for the
	// message: "%[1]v ${invites} %[2]v to ${their} party." The sequence of calls
	// is:
	// d.Render("%[1]v ")
	// d.Arg(1)
	// d.Render(resultOfInvites)
	// d.Render(" %[2]v to ")
	// d.Arg(2)
	// d.Render(resultOfTheir)
	// d.Render(" party.")
	// where the messages for "invites" and "their" both use a plural.Select
	// referring to the first argument.
	//
	// Strings may also invoke macros. Macros are essentially variables that can be
	// reused. Macros may, for instance, be used to make selections between
	// different conjugations of a verb. See the catalog package description for an
	// overview of macros.
	type String string

	// Compile implements Message. It parses the placeholder formats and returns
	// any error.
	func (s String) Compile(e *Encoder) (err error) {
	msg := string(s)
	const subStart = "${"
	hasHeader := false
	p := 0
	b := []byte{}
	for {
	i := strings.Index(msg[p:], subStart)
	if i == -1 {
	break
	}
	b = append(b, msg[p:p+i]...)
	p += i + len(subStart)
	if i = strings.IndexByte(msg[p:], '}'); i == -1 {
	b = append(b, "$!(MISSINGBRACE)"...)
	err = fmt.Errorf("catmsg: missing '}'")
	p = len(msg)
	break
	}
	name := strings.TrimSpace(msg[p : p+i])
	if q := strings.IndexByte(name, '('); q == -1 {
	if !hasHeader {
	hasHeader = true
	e.EncodeMessageType(msgString)
	}
	e.EncodeString(string(b))
	e.EncodeSubstitution(name)
	b = b[:0]
	} else if j := strings.IndexByte(name[q:], ')'); j == -1 {
	// TODO: what should the error be?
	b = append(b, "$!(MISSINGPAREN)"...)
	err = fmt.Errorf("catmsg: missing ')'")
	} else if x, sErr := strconv.ParseUint(strings.TrimSpace(name[q+1:q+j]), 10, 32); sErr != nil {
	// TODO: handle more than one argument
	b = append(b, "$!(BADNUM)"...)
	err = fmt.Errorf("catmsg: invalid number %q", strings.TrimSpace(name[q+1:q+j]))
	} else {
	if !hasHeader {
	hasHeader = true
	e.EncodeMessageType(msgString)
	}
	e.EncodeString(string(b))
	e.EncodeSubstitution(name[:q], int(x))
	b = b[:0]
	}
	p += i + 1
	}
	b = append(b, msg[p:]...)
	if !hasHeader {
	// Simplify string to a raw string.
	Raw(string(b)).Compile(e)
	} else if len(b) > 0 {
	e.EncodeString(string(b))
	}
	return err
	}

	// Affix is a message that adds a prefix and suffix to another message.
	// This is mostly used add back whitespace to a translation that was stripped
	// before sending it out.
	type Affix struct {
	Message Message
	Prefix string
	Suffix string
	}

	// Compile implements Message.
	func (a Affix) Compile(e *Encoder) (err error) {
	// TODO: consider adding a special message type that just adds a single
	// return. This is probably common enough to handle the majority of cases.
	// Get some stats first, though.
	e.EncodeMessageType(msgAffix)
	e.EncodeString(a.Prefix)
	e.EncodeString(a.Suffix)
	e.EncodeMessage(a.Message)
	return nil
	}