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).

Options

The FromOptions (and associated helpers) function makes it easy to use generators and output rules as markers that can be parsed from the command line, producing a registry from command line args.

Index

• Variables
• func RegisterOptionsMarkers(into *markers.Registry) error
• func RegistryFromOptions(optionsRegistry *markers.Registry, options []string) (*markers.Registry, error)
• func TransformRemoveCreationTimestamp(obj map[string]interface{}) error
• type GenerationContext
  • func (g GenerationContext) ReadFile(path string) ([]byte, error)
  • func (g GenerationContext) WriteYAML(itemPath, headerText string, objs []interface{}, options ...*WriteYAMLOptions) error
• type Generator
• type Generators
  • func (g Generators) CheckFilters() []loader.NodeFilter
  • func (g Generators) ForRoots(rootPaths ...string) (*Runtime, error)
  • func (g Generators) RegisterMarkers(reg *markers.Registry) error
• type HasHelp
• type InputPaths
  • func (InputPaths) Help() *markers.DefinitionHelp
• type InputRule
• type NeedsTypeChecking
• type OutputArtifacts
  • func (OutputArtifacts) Help() *markers.DefinitionHelp
  • 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 (OutputToDirectory) Help() *markers.DefinitionHelp
  • func (o OutputToDirectory) Open(_ *loader.Package, itemPath string) (io.WriteCloser, error)
• type Runtime
  • func FromOptions(optionsRegistry *markers.Registry, options []string) (*Runtime, error)
  • func (r *Runtime) Run() bool
• type WriteYAMLOptions
  • func WithTransform(transform func(obj map[string]interface{}) error) *WriteYAMLOptions

Variables

var InputFromFileSystem = inputFromFileSystem{}

InputFromFileSystem reads from the filesystem as normal.

var (
	InputPathsMarker = markers.Must(markers.MakeDefinition("paths", markers.DescribesPackage, InputPaths(nil)))
)

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.

Functions

func RegisterOptionsMarkers

func RegisterOptionsMarkers(into *markers.Registry) error

RegisterOptionsMarkers registers "mandatory" options markers for FromOptions into the given registry. At this point, that's just InputPaths.

func RegistryFromOptions

func RegistryFromOptions(optionsRegistry *markers.Registry, options []string) (*markers.Registry, error)

RegistryFromOptions produces just the marker registry that would be used by FromOptions, without attempting to produce a full Runtime. This can be useful if you want to display help without trying to load roots.

func TransformRemoveCreationTimestamp

func TransformRemoveCreationTimestamp(obj map[string]interface{}) error

TransformRemoveCreationTimestamp ensures we do not write the metadata.creationTimestamp field.

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, headerText string, objs []interface{}, options ...*WriteYAMLOptions) error

WriteYAML writes the given objects out, serialized as YAML, using the context's OutputRule. Objects are written as separate documents, separated from each other by `---` (as per the YAML spec).

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. NB(directxman12): this is a pointer so that we can uniquely identify each instance of a generator, even if it's not hashable. Different *instances* of a generator are treated differently.

func (Generators) CheckFilters

func (g Generators) CheckFilters() []loader.NodeFilter

CheckFilters returns the set of NodeFilters for all Generators that implement NeedsTypeChecking.

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 HasHelp

type HasHelp interface {
	// Help returns help for this generator.
	Help() *markers.DefinitionHelp
}

HasHelp is some Generator, OutputRule, etc with a help method.

type InputPaths

type InputPaths []string

InputPaths represents paths and go-style path patterns to use as package roots.

Multiple paths can be specified using "{path1, path2, path3}".

func (InputPaths) Help

func (InputPaths) Help() *markers.DefinitionHelp

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 NeedsTypeChecking

type NeedsTypeChecking interface {
	// CheckFilter indicates the loader.NodeFilter (if any) that should be used
	// to prune out unused types/packages when type-checking (nodes for which
	// the filter returns true are considered "interesting").  This filter acts
	// as a baseline -- all types the pass through this filter will be checked,
	// but more than that may also be checked due to other generators' filters.
	CheckFilter() loader.NodeFilter
}

NeedsTypeChecking indicates that a particular generator needs & has opinions on typechecking. If this is not implemented, a generator will be given a context with a nil typechecker.

type OutputArtifacts

type OutputArtifacts struct {
	// Config points to the directory to which to write configuration.
	Config OutputToDirectory
	// Code overrides the directory in which to write new code (defaults to where the existing code lives).
	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) Help

func (OutputArtifacts) Help() *markers.DefinitionHelp

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.
	// NB(directxman12): this is a pointer to avoid issues if a given Generator becomes unhashable
	// (interface values compare by "dereferencing" their internal pointer first, whereas pointers
	// compare by the actual pointer itself).
	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) Help

func (OutputToDirectory) Help() *markers.DefinitionHelp

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
	// ErrorWriter defines where to write error messages.
	ErrorWriter io.Writer
}

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

func FromOptions

func FromOptions(optionsRegistry *markers.Registry, options []string) (*Runtime, error)

FromOptions parses the options from markers stored in the given registry out into a runtime. The markers in the registry must be either

a) Generators b) OutputRules c) InputPaths

The paths specified in InputPaths are loaded as package roots, and the combined with the generators and the specified output rules to produce a runtime that can be run or further modified. Not default generators are used if none are specified -- you can check the output and rerun for that.

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.

type WriteYAMLOptions

type WriteYAMLOptions struct {
	// contains filtered or unexported fields
}

WriteYAMLOptions implements the Options Pattern for WriteYAML.

func WithTransform

func WithTransform(transform func(obj map[string]interface{}) error) *WriteYAMLOptions

WithTransform applies a transformation to objects just before writing them.