Documentation

Overview

    Package base contains code shared by other CLI subpackages.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func CollectErrorMessages

    func CollectErrorMessages(err error, in []string) (out []string)

      CollectErrorMessages traverses err (which can be a MultiError, recursively), and appends all error messages there to 'in', returning the resulting slice.

      They are eventually used in JSON output and printed to stderr.

      func ExpandDirectories

      func ExpandDirectories(paths []string) ([]string, error)

        ExpandDirectories recursively traverses directories in `paths` discovering *.star files in them.

        If `paths` is empty, expands `.`.

        Returns the overall list of discovered files.

        func GenerateConfigs

        func GenerateConfigs(ctx context.Context, inputFile string, meta, flags *lucicfg.Meta, vars map[string]string) (*lucicfg.State, error)

          GenerateConfigs executes the Starlark script and assembles final values for meta config.

          It is a common part of subcommands that generate configs.

          'meta' is initial Meta config with default parameters, it will be mutated in-place to contain the final parameters (based on lucicfg.config(...) calls in Starlark and the config populated via CLI flags, passed as 'flags'). 'flags' are also mutated in-place to rebase ConfigDir onto cwd.

          'vars' are a collection of k=v pairs passed via CLI flags as `-var k=v`. They are used to pre-set lucicfg.var(..., exposed_as=<k>) variables.

          func MissingFlagError

          func MissingFlagError(flag string) error

            MissingFlagError is CommandLineError about a missing flag.

            func NewCLIError

            func NewCLIError(msg string, args ...interface{}) error

              NewCLIError returns new CommandLineError.

              func PathLoader

              func PathLoader(path string) (starlark.StringDict, string, error)

                PathLoader is an interpreter.Loader that loads files using file system paths.

                func Validate

                  Validate validates both input source code and generated config files.

                  It is a common part of subcommands that validate configs.

                  Source code is checked using buildifier linters and formatters, if enabled. This is controlled by LintChecks meta args.

                  Generated config files are split into 0 or more config sets and sent to the LUCI Config remote service for validation, if enabled. This is controlled by ConfigServiceHost meta arg.

                  Dumps all validation errors to the stderr. In addition to detailed validation results, also returns a multi-error with all blocking errors.

                  Types

                  type CommandLineError

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

                    CommandLineError is used to tag errors related to command line arguments.

                    Subcommand.Done(..., err) will print the usage string if it finds such error.

                    type ConfigServiceFactory

                    type ConfigServiceFactory func(ctx context.Context, host string) (*config.Service, error)

                      ConfigServiceFactory returns a LUCI Config RPC client that sends requests to the given host.

                      type Parameters

                      type Parameters struct {
                      	AuthOptions       auth.Options // mostly for client ID and client secret
                      	ConfigServiceHost string       // e.g. "luci-config.appspot.com"
                      }

                        Parameters can be used to customize CLI defaults.

                        type Subcommand

                        type Subcommand struct {
                        	subcommands.CommandRunBase
                        
                        	Meta lucicfg.Meta        // meta config settable via CLI flags
                        	Vars stringmapflag.Value // all `-var k=v` flags
                        	// contains filtered or unexported fields
                        }

                          Subcommand is a base of all subcommands.

                          It defines some common flags, such as logging and JSON output parameters, and some common methods to report errors and dump JSON output.

                          It's Init() method should be called from within CommandRun to register base flags.

                          func (*Subcommand) AddGeneratorFlags

                          func (c *Subcommand) AddGeneratorFlags()

                            AddGeneratorFlags registers c.Meta and c.Vars in the FlagSet.

                            Used by subcommands that end up executing Starlark.

                            func (*Subcommand) CheckArgs

                            func (c *Subcommand) CheckArgs(args []string, minPosCount, maxPosCount int) bool

                              CheckArgs checks command line args.

                              It ensures all required positional and flag-like parameters are set. Setting maxPosCount to -1 indicates there is unbounded number of positional arguments allowed.

                              Returns true if they are, or false (and prints to stderr) if not.

                              func (*Subcommand) ConfigService

                              func (c *Subcommand) ConfigService(ctx context.Context, host string) (*config.Service, error)

                                ConfigService returns a wrapper around LUCI Config API.

                                It is ready for making authenticated RPCs. 'host' is a hostname of the service to hit, e.g. "luci-config.appspot.com".

                                func (*Subcommand) DefaultMeta

                                func (c *Subcommand) DefaultMeta() lucicfg.Meta

                                  DefaultMeta returns Meta values to use by default if not overridden via flags or via lucicfg.config(...).

                                  func (*Subcommand) Done

                                  func (c *Subcommand) Done(result interface{}, err error) int

                                    Done is called as the last step of processing a subcommand.

                                    It dumps the command result (or an error) to the JSON output file, prints the error message and generates the process exit code.

                                    func (*Subcommand) Init

                                    func (c *Subcommand) Init(params Parameters)

                                      Init registers common flags.

                                      func (*Subcommand) ModifyContext

                                      func (c *Subcommand) ModifyContext(ctx context.Context) context.Context

                                        ModifyContext implements cli.ContextModificator.

                                        type ValidateParams

                                        type ValidateParams struct {
                                        	Loader interpreter.Loader // represents the main package
                                        	Source []string           // paths to lint, relative to the main package
                                        	Output lucicfg.Output     // generated output files to validate
                                        	Meta   lucicfg.Meta       // validation options (settable through Starlark)
                                        
                                        	// ConfigService returns a LUCI Config RPC client that sends requests
                                        	// to the given host.
                                        	//
                                        	// This is usually just subcommand.ConfigService.
                                        	ConfigService ConfigServiceFactory
                                        }

                                          ValidateParams contains parameters for Validate call.