generator

README

pifke.org/generator

Utility functions for code generation.

Downloading

If you use this library in your own code, please use the canonical URL in your Go code, instead of Github:

go get pifke.org/generator

Or (until I finish setting up the self-hosted repository):

# From the root of your project:
git submodule add https://github.com/dpifke/golang-generator vendor/pifke.org/generator

Then:

import (
        "pifke.org/generator"
)

As opposed to the pifke.org URL, I make no guarantee this Github repository will exist or be up-to-date in the future.

Documentation

Available on godoc.org.

License

Three-clause BSD. See LICENSE.txt.

Contact me if you want to use this code under different terms.

Author

Dave Pifke. My email address is my first name "at" my last name "dot org."

I'm @dpifke on Twitter. My PGP key is available on Keybase.

Documentation

Overview

Package generator provides some utility functions for code generation.

Index

• func AtomicFileReplace(src, dest []string) error
• func Download(src string, args ...string) (string, error)
• func GolangCommentWriter(out io.Writer, indentLevel, maxLineLen int) io.WriteCloser
• func MakeStableEnum(values, special []string) (map[int]string, error)
• func ProtobufEnumName(origName string) string
• func WriteGolangHeader(out io.Writer, src, pkg string, imports ...string) error
• func WriteProtobufEnum(out io.Writer, name string, values interface{}, special []string) error
• func WriteProtobufHeader(out io.Writer, src, pkg string) error
• type ParseError
  • func (e *ParseError) Error() string

Functions

func AtomicFileReplace

func AtomicFileReplace(src, dest []string) error

AtomicFileReplace overwrites a series of files, but in a safe manner. If any of the file operations fail, they are all rolled back to their original state.

func Download

func Download(src string, args ...string) (string, error)

Download fetches a file over HTTP, saving it to the current directory. It returns the filename and/or any error encountered during the download.

The optional args currently consist only of the destination filename. If not specified, it defaults to the filename portion of src.

Attempts are made to reuse any existing download, if it hasn't changed. If no destination filename was specified, and the server sets the filename on download to something other than what's contained in the URL, the existing file may not be detected.

func GolangCommentWriter

func GolangCommentWriter(out io.Writer, indentLevel, maxLineLen int) io.WriteCloser

GolangCommentWriter returns an io.WriteCloser to wrap an existing io.Writer. Data written will be formatted as Golang comments, including word wrapping. (If word wrapping is not desired, maxLineLen can be set to zero.)

indentLevel is the number of tab stops by which to indent the output.

The caller *must* call Close() on the returned object when done writing, in order to flush any buffered text. Doing so will not close the underlying io.Writer.

func MakeStableEnum

func MakeStableEnum(values, special []string) (map[int]string, error)

MakeStableEnum assigns stable integer values to enum names, for use in a protocol buffer declaration. This is used if in the future the enum may have its entries reordered or new entries added, and we don't want existing protocol buffers to break.

A list of "special" entries can be provided, which must be a subset of the main list. Values 1 to 127 (which encode as a single byte) are reserved for the members of this list. It's normally used for the most common entries, although it can also be a workaround for hash collisions, by moving one of colliding entries to this list.

N.B. the order of the special list can never change! Additional entries can be appended later, but if any entries are removed, existing protocol buffers will be incompatible with the new definition.

func ProtobufEnumName

func ProtobufEnumName(origName string) string

ProtobufEnumName mangles a name to make it a legal (and style guide approved) identifier within a protocol buffer definition.

The return value will consist only of upper case letters, numbers, and underscores. Any non-alphanumeric characters in the input are converted to underscores.

If the first character of the input is numeric, an underscore is prepended, to differentiate the identifier from a numeric constant. If the input begins with one or more non-alphanumeric characters followed by a number, an underscore is also prepended. This latter rule is to ensure that the name mangling doesn't produce duplicate identifiers, however it means that this function should not be called multiple times over the same string.

func WriteGolangHeader

func WriteGolangHeader(out io.Writer, src, pkg string, imports ...string) error

WriteGolangHeader writes the file header for a generated Go source file to the specified io.Writer.

func WriteProtobufEnum

func WriteProtobufEnum(out io.Writer, name string, values interface{}, special []string) error

WriteProtobufEnum writes a protocol buffer enum definition to the specified io.Writer.

This function can be passed a map[int]string, where the enum value is assigned, or a []string, in which case the enum value will be allocated automatically.

A list of "special" entries can be provided, which may be a subset of the main list. Values 1 to 127 (which encode as a single byte) are reserved for the members of this list. It's normally used for the most common entries.

N.B. the order of any []string input to this function can never change! Additional entries can be appended later, but if any entries are removed, existing protocol buffers will be incompatible with the new definition. MakeStableEnum can be used to convert a []string to a map[int]string with stable assignments.

func WriteProtobufHeader

func WriteProtobufHeader(out io.Writer, src, pkg string) error

WriteProtobufHeader writes the file header for a generated protocol buffer definition.

Types

type ParseError

type ParseError struct {
	Filename  string
	Line, Row int
	Err       error
	ErrStr    string
}

ParseError provides an error implementation which optionally includes source filename and line or row number information. It can encapsulate another error, or be built with an error string.

func (*ParseError) Error

func (e *ParseError) Error() string