cli

Documentation

Overview

Package cli contains helpers used by transport-specific command-line client generators for parsing the command-line flags to identify the service and the method to make a request along with the request payload to be sent.

Index

• func CommandUsage(data *CommandData) *codegen.SectionTemplate
• func FieldLoadCode(f *FlagData, argName, argTypeName, validate string, defaultValue any, ...) (string, bool)
• func FlagsCode(data []*CommandData) string
• func PayloadBuilderSection(buildFunction *BuildFunctionData) *codegen.SectionTemplate
• func UsageCommands(data []*CommandData) *codegen.SectionTemplate
• func UsageExamples(data []*CommandData) *codegen.SectionTemplate
• type BuildFunctionData
• type CommandData
  • func BuildCommandData(data *service.Data) *CommandData
• type FieldData
• type FlagData
  • func NewFlagData(svcn, en, name, typeName, description string, required bool, example, def any) *FlagData
• type PayloadInitData
• type SubcommandData
  • func BuildSubcommandData(svcName string, m *service.MethodData, buildFunction *BuildFunctionData, ...) *SubcommandData

Functions

func CommandUsage

func CommandUsage(data *CommandData) *codegen.SectionTemplate

CommandUsage builds the section templates that can be used to generate the endpoint command usage code.

func FieldLoadCode

func FieldLoadCode(f *FlagData, argName, argTypeName, validate string, defaultValue any, payload expr.DataType, payloadRef string) (string, bool)

FieldLoadCode returns the code used in the build payload function that initializes one of the payload object fields. It returns the initialization code and a boolean indicating whether the code requires an "err" variable.

func FlagsCode

func FlagsCode(data []*CommandData) string

FlagsCode returns a string containing the code that parses the command-line flags to infer the command (service), sub-command (method), and the arguments (method payload) invoked by the tool. It panics if any error occurs during the generation of flag parsing code.

func PayloadBuilderSection

func PayloadBuilderSection(buildFunction *BuildFunctionData) *codegen.SectionTemplate

PayloadBuilderSection builds the section template that can be used to generate the payload builder code.

func UsageCommands

func UsageCommands(data []*CommandData) *codegen.SectionTemplate

UsageCommands builds a section template that generates a help text showing the list of allowed commands and sub-commands.

func UsageExamples

func UsageExamples(data []*CommandData) *codegen.SectionTemplate

UsageExamples builds a section template that generates a help text showing a valid invocation of the CLI tool.

Types

type BuildFunctionData

type BuildFunctionData struct {
	// Name is the build payload function name.
	Name string
	// Description describes the payload function.
	Description string
	// ActualParams is the list of passed build function parameters.
	ActualParams []string
	// FormalParams is the list of build function formal parameter
	// names.
	FormalParams []string
	// ServiceName is the name of the service.
	ServiceName string
	// MethodName is the name of the method.
	MethodName string
	// ResultType is the fully qualified payload type name.
	ResultType string
	// Fields describes the payload fields.
	Fields []*FieldData
	// PayloadInit contains the data needed to render the function
	// body.
	PayloadInit *PayloadInitData
	// CheckErr is true if the payload initialization code requires an
	// "err error" variable that must be checked.
	CheckErr bool
}

BuildFunctionData contains the data needed to generate a constructor function that builds a service method payload type from the command-line flags.

type CommandData

type CommandData struct {
	// Name of command e.g. "cellar-storage"
	Name string
	// VarName is the name of the command variable e.g.
	// "cellarStorage"
	VarName string
	// Description is the help text.
	Description string
	// Subcommands is the list of endpoint commands.
	Subcommands []*SubcommandData
	// Example is a valid command invocation, starting with the
	// command name.
	Example string
	// PkgName is the service HTTP client package import name,
	// e.g. "storagec".
	PkgName string
}

CommandData contains the data needed to render a command.

func BuildCommandData

func BuildCommandData(data *service.Data) *CommandData

BuildCommandData builds the data needed by CLI code generators to render the parsing of the service command.

type FieldData

type FieldData struct {
	// Name is the field name, e.g. "Vintage"
	Name string
	// VarName is the name of the local variable holding the field
	// value, e.g. "vintage"
	VarName string
	// TypeRef is the reference to the type.
	TypeRef string
	// Init is the code initializing the variable.
	Init string
}

FieldData contains the data needed to generate the code that initializes a field in the method payload type.

type FlagData

type FlagData struct {
	// Name is the name of the flag, e.g. "list-vintage"
	Name string
	// VarName is the name of the flag variable, e.g. "listVintage"
	VarName string
	// Type is the type of the flag, e.g. INT
	Type string
	// FullName is the flag full name e.g. "storageAddVintage"
	FullName string
	// Description is the flag help text.
	Description string
	// Required is true if the flag is required.
	Required bool
	// Example returns a JSON serialized example value.
	Example string
	// Default returns the default value if any.
	Default any
}

FlagData contains the data needed to render a command-line flag.

func NewFlagData

func NewFlagData(svcn, en, name, typeName, description string, required bool, example, def any) *FlagData

NewFlagData creates a new FlagData from the given argument attributes.

svcn is the service name en is the endpoint name name is the flag name typeName is the flag type description is the flag description required determines if the flag is required example is an example value for the flag

type PayloadInitData

type PayloadInitData struct {
	// Code is the payload initialization code.
	Code string
	// ReturnTypeAttribute if non-empty returns an attribute in the payload
	// type that describes the shape of the method payload.
	ReturnTypeAttribute string
	// ReturnTypeAttributePointer is true if the return type attribute
	// generated struct field holds a pointer
	ReturnTypeAttributePointer bool
	// ReturnIsStruct if true indicates that the method payload is an object.
	ReturnIsStruct bool
	// ReturnTypeName is the fully-qualified name of the payload.
	ReturnTypeName string
	// ReturnTypePkg is the package name where the payload is present.
	ReturnTypePkg string
	// Args is the list of arguments for the constructor.
	Args []*codegen.InitArgData
}

PayloadInitData contains the data needed to generate a constructor function that initializes a service method payload type from the command-ling arguments.

type SubcommandData

type SubcommandData struct {
	// Name is the sub-command name e.g. "add"
	Name string
	// FullName is the sub-command full name e.g. "storageAdd"
	FullName string
	// Description is the help text.
	Description string
	// Flags is the list of flags supported by the subcommand.
	Flags []*FlagData
	// MethodVarName is the endpoint method name, e.g. "Add"
	MethodVarName string
	// BuildFunction contains the data to generate a payload builder function
	// if any. Exclusive with Conversion.
	BuildFunction *BuildFunctionData
	// Conversion contains the flag value to payload conversion function if
	// any. Exclusive with BuildFunction.
	Conversion string
	// Example is a valid command invocation, starting with the command name.
	Example string
}

SubcommandData contains the data needed to render a sub-command.

func BuildSubcommandData

func BuildSubcommandData(svcName string, m *service.MethodData, buildFunction *BuildFunctionData, flags []*FlagData) *SubcommandData

BuildSubcommandData builds the data needed by CLI code generators to render the CLI parsing of the service sub-command.