render

Documentation

Index

• type Params
• type Result
  • func Render(ctx context.Context, p *Params) (_ *Result, rErr error)
  • func RenderAlreadyDownloaded(ctx context.Context, dlMeta *templatesource.DownloadMetadata, ...) (_ *Result, rErr error)

Types

type Params

type Params struct {
	// The value of --accept-defaults.
	AcceptDefaults bool

	// Only used when BackfillManifestOnly is set. The user acknowledges that
	// the backfilled manifest file will be missing patches for files that were
	// "included from destination".
	ContinueWithoutPatches bool

	// BackupDir is the directory where overwritten files will be backed up.
	// BackupDir is ignored if Backups is false.
	BackupDir string
	Backups   bool

	// If len(OverrideBuiltinVars)>0, then these values replace the normal
	// undercore-prefixed vars (_git_tag,  All map keys must begin with
	// underscore.
	OverrideBuiltinVars map[string]string

	// Fakeable time for testing.
	Clock clock.Clock

	// The fakeable working directory for testing.
	Cwd string

	// The value of --debug-scratch-contents.
	DebugScratchContents bool

	// The value of --debug-step-diffs.
	DebugStepDiffs bool

	// The directory that this operation is targeting, from the user's point of
	// view. It's sometimes the same as OutDir:
	//   - When Render() is being called as part of `abc render`,
	//     this is the same as OutDir.
	//   - When Render() is being called as part of `abc upgrade`,
	//     this is the directory that the template is installed to, and NOT the
	//     temp dir that receives the output of Render().
	//
	// This is optional. If unset, the value of OutDir will be used.
	DestDir string

	// The downloader that will provide the template.
	Downloader templatesource.Downloader

	// The value of --force-overwrite.
	ForceOverwrite bool

	// A fakeable filesystem for error injection in tests.
	FS common.FS

	// The value of --git-protocol.
	GitProtocol string

	// Ignore any values in the Inputs map that aren't valid template inputs,
	// rather than returning error.
	IgnoreUnknownInputs bool

	// An optional extra directory that will be copied from in the case where an
	// "include" action has "from: destination". This is in addition to DestDir
	// above. The include action will copy from DestDir first and then from this
	// directory afterward, so files in this directory will take precedence.
	// Essentially, files in this dir are overlaid on top of other includes
	// files in an include-from-destination operation.
	IncludeFromDestExtraDir string

	// The value of --input-files.
	InputFiles []string

	// The value of --input, or another source of input values (e.g. the golden
	// test test.yaml).
	InputsFromFlags map[string]string

	// This is only set in the case where this template is being rendered as
	// part of an upgrade operation, and contains the set of inputs that were
	// saved in the manifest from the previous render operation. They're
	// separate from the other inputs so they can be given lowest precedence.
	InputsFromManifest map[string]string

	// The value of --keep-temp-dirs.
	KeepTempDirs bool

	// Override the default behavior of outputting a manifest for the rendered
	// template.
	SkipManifest bool

	// The value of --backfill-manifest-only. Whether to *only* create a
	// manifest file without outputting any other files from the template.
	BackfillManifestOnly bool

	// The directory where the rendered output will be written.
	OutDir string

	// Whether to prompt the user for inputs on stdin in the case where they're
	// not all provided in Inputs or InputFiles.
	Prompt bool

	// If Prompt is true, Prompter will be used if needed to ask the user for
	// any missing inputs. If Prompt is false, this is ignored.
	Prompter input.Prompter

	// The value of --skip-input-validation.
	SkipInputValidation bool

	// Normally, we'll only prompt if the input is a TTY. For testing, this
	// can be set to true to bypass the check and allow stdin to be something
	// other than a TTY, like an os.Pipe.
	SkipPromptTTYCheck bool

	// The location from which the template is installed, as provided by the
	// user on the command line, or from the manifest. This is only used in
	// log messages and for the _flag_source variable in print actions.
	SourceForMessages string

	// The output stream used by "print" actions.
	Stdout io.Writer

	// The directory under which to create temp directories. Normally empty,
	// except in testing.
	TempDirBase string

	// The value of the --upgrade-channel flag. Leave blank to use the
	// autodetected upgrade channel (most common).
	UpgradeChannel string
}

Params contains the arguments to Render().

type Result

type Result struct {
	// IncludedFromDestination is a set of files that were the subject of an
	// "include" action that had "from: destination". This exists primarily for
	// the sake of the "upgrade" command, which needs to know this. Other
	// callers should not use this field.
	IncludedFromDestination []string

	// ManifestPath, if set, is the relative path to the manifest file, starting
	// from the destination directory (e.g. ".abc/manifest_123.yaml"). If
	// manifest output wasn't enabled (see the --skip-manifest flag), then this
	// will be empty.
	ManifestPath string
}

Result gives some metadata about the outcome of the render operation.

func Render

func Render(ctx context.Context, p *Params) (_ *Result, rErr error)

Render does the full sequence of steps involved in rendering a template. It downloads the template, parses the spec file, read template inputs, conditionally prompts the user for missing inputs, runs all the template actions, commits the output to the destination, and more.

This is a library function because template rendering is a reusable operation that is called as a subroutine by "golden-test" and "upgrade" commands.

func RenderAlreadyDownloaded

func RenderAlreadyDownloaded(ctx context.Context, dlMeta *templatesource.DownloadMetadata, templateDir string, p *Params) (_ *Result, rErr error)

RenderAlreadyDownloaded is for the unusual case where the template has already been downloaded to the local filesystem. Most callers should prefer to call Render() instead.

The Params.Downloader field is ignored by this function.