genall

Documentation

Overview

Package genall defines entrypoints for generation tools to hook into and share the same set of parsing, typechecking, and marker information.

Generators

Each Generator knows how to register its markers into a central Registry, and then how to generate output using a Collector and some root packages. Each generator can be considered to be the output type of a marker, for easy command line parsing.

Output and Input

Generators output artifacts via an OutputRule. OutputRules know how to write output for different package-associated (code) files, as well as config files. Each OutputRule should also be considered to be the output type as a marker, for easy command-line parsing.

OutputRules groups together an OutputRule per generator, plus a default output rule for any not explicitly specified.

OutputRules are defined for stdout, file writing, and sending to /dev/null (useful for doing "type-checking" without actually saving the results).

InputRule defines custom input loading, but its shared across all Generators. There's currently only a filesystem implementation.

Runtime and Context

Runtime maps together Generators, and constructs "contexts" which provide the common collector and roots, plus the output rule for that generator, and a handle for reading files (like boilerplate headers).

It will run all associated generators, printing errors and automatically skipping type-checking errors (since those are commonly caused by the partial type-checking of loader.TypeChecker).

Index

• Variables
• type GenerationContext
  • func (g GenerationContext) ReadFile(path string) ([]byte, error)
  • func (g GenerationContext) WriteYAML(itemPath string, objs ...interface{}) error
• type Generator
• type Generators
  • func (g Generators) ForRoots(rootPaths ...string) (*Runtime, error)
  • func (g Generators) RegisterMarkers(reg *markers.Registry) error
• type InputRule
• type OutputArtifacts
  • func (o OutputArtifacts) Open(pkg *loader.Package, itemPath string) (io.WriteCloser, error)
• type OutputRule
• type OutputRules
  • func DirectoryPerGenerator(base string, generators map[string]Generator) OutputRules
  • func (o OutputRules) ForGenerator(gen Generator) OutputRule
• type OutputToDirectory
  • func (o OutputToDirectory) Open(_ *loader.Package, itemPath string) (io.WriteCloser, error)
• type Runtime
  • func (r *Runtime) Run() bool

Variables

var InputFromFileSystem = inputFromFileSystem{}

InputFromFileSystem reads from the filesystem as normal.

var OutputToNothing = outputToNothing{}

OutputToNothing skips outputting anything.

var OutputToStdout = outputToStdout{}

OutputToStdout outputs everything to standard-out, with no separation. Generally useful for single-artifact outputs.

Types

type GenerationContext

type GenerationContext struct {
	// Collector is the shared marker collector.
	Collector *markers.Collector
	// Roots are the base packages to be processed.
	Roots []*loader.Package
	// Checker is the shared partial type-checker.
	Checker *loader.TypeChecker
	// OutputRule describes how to output artifacts.
	OutputRule
	// InputRule describes how to load associated boilerplate artifacts.
	// It should *not* be used to load source files.
	InputRule
}

GenerationContext defines the common information needed for each Generator to run.

func (GenerationContext) ReadFile

func (g GenerationContext) ReadFile(path string) ([]byte, error)

ReadFile reads the given boilerplate artifact using the context's InputRule.

func (GenerationContext) WriteYAML

func (g GenerationContext) WriteYAML(itemPath string, objs ...interface{}) error

WriteYAML writes the given objects out, serialized as YAML, using the context's OutputRule.

type Generator

type Generator interface {
	// RegisterMarkers registers all markers needed by this Generator
	// into the given registry.
	RegisterMarkers(into *markers.Registry) error
	// Generate generates artifacts produced by this marker.
	// It's called *after* RegisterMarkers has been called.
	Generate(*GenerationContext) error
}

Generator knows how to register some set of markers, and then produce output artifacts based on loaded code containing those markers, sharing common loaded data.

type Generators

type Generators []Generator

Generators are a list of Generators.

func (Generators) ForRoots

func (g Generators) ForRoots(rootPaths ...string) (*Runtime, error)

ForRoots produces a Runtime to run the given generators against the given packages. It outputs to /dev/null by default.

func (Generators) RegisterMarkers

func (g Generators) RegisterMarkers(reg *markers.Registry) error

RegisterMarkers registers all markers defined by each of the Generators in this list into the given registry.

type InputRule

type InputRule interface {
	// OpenForRead opens the given non-code artifact for reading.
	OpenForRead(path string) (io.ReadCloser, error)
}

InputRule describes how to load non-code boilerplate artifacts. It's not used for loading code.

type OutputArtifacts

type OutputArtifacts struct {
	Config OutputToDirectory
	Code   OutputToDirectory `marker:",optional"`
}

OutputArtifacts outputs artifacts to different locations, depending on whether they're package-associated or not. Non-package associated artifacts are output to the Config directory, while package-associated ones are output to their package's source files' directory, unless an alternate path is specified in Code.

func (OutputArtifacts) Open

func (o OutputArtifacts) Open(pkg *loader.Package, itemPath string) (io.WriteCloser, error)

type OutputRule

type OutputRule interface {
	// Open opens the given artifact path for writing.  If a package is passed,
	// the artifact is considered to be used as part of the package (e.g.
	// generated code), while a nil package indicates that the artifact is
	// config (or something else not involved in Go compilation).
	Open(pkg *loader.Package, path string) (io.WriteCloser, error)
}

OutputRule defines how to output artifacts from a generator.

type OutputRules

type OutputRules struct {
	// Default is the output rule used when no specific per-generator overrides match.
	Default OutputRule
	// ByGenerator contains specific per-generator overrides.
	ByGenerator map[Generator]OutputRule
}

OutputRules defines how to output artificats on a per-generator basis.

func DirectoryPerGenerator

func DirectoryPerGenerator(base string, generators map[string]Generator) OutputRules

DirectoryPerGenerator produces output rules mapping output to a different subdirectory of the given base directory for each generator (with each subdirectory specified as the key in the input map).

func (OutputRules) ForGenerator

func (o OutputRules) ForGenerator(gen Generator) OutputRule

ForGenerator returns the output rule that should be used by the given Generator.

type OutputToDirectory

type OutputToDirectory string

OutputToDirectory outputs each artifact to the given directory, regardless of if it's package-associated or not.

func (OutputToDirectory) Open

func (o OutputToDirectory) Open(_ *loader.Package, itemPath string) (io.WriteCloser, error)

type Runtime

type Runtime struct {
	// Generators are the Generators to be run by this Runtime.
	Generators Generators
	// GenerationContext is the base generation context that's copied
	// to produce the context for each Generator.
	GenerationContext
	// OutputRules defines how to output artifacts for each Generator.
	OutputRules OutputRules
}

Runtime collects generators, loaded program data (Collector, root Packages), and I/O rules, running them together.

func (*Runtime) Run

func (r *Runtime) Run() bool

Run runs the Generators in this Runtime against its packages, printing errors (except type errors, which common result from using TypeChecker with filters), returning true if errors were found.