Documentation
¶
Overview ¶
Package provider implements a technique for identifying named providers with arguments. The main use case for providers is extensibility. For example, in a command line tool that lets the user decide which output format to use, you could use providers to name the output format and their arguments. For example, say a tool converts from one Go marshaler to another such as from YAML to JSON. This would (say) enable the user to specify their desired output format:
conversiontool --format json --format-arg indent=2 --format-arg encoding=utf-16 inputFile.yaml
Notice that --format names the desired output format (JSON) and --format-arg provides arguments that the JSON formatter presumably uses.
Value is used to implement the provider specification, which is the name of the provider and optionally a shorthand for arg syntax. In the case that you want a separate flag to provide the arguments, you use the SetArgument action.
Usually, a registry of well-known provider names is used. To support this, you can use a Registry.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Bind ¶ added in v0.11.0
Bind provides the binder the invokes the provider factory with its configured arguments
func ListProviders ¶
ListProviders provides an action that can be used to display the list of providers. This requires that the provider registry was specified. If the action is set to initialize a flag that is unnamed, the prefix list- is implied. The template "providers" is used, which is set to a default if unspecified.
func SetArgument ¶
SetArgument provides an action that can be used to set the argument for a provider. This enables you to have a dedicated flag to handle setting provider arguments:
&cli.Flag{
Name: "provider"
Value: new(provider.Provider),
},
&cli.Flag {
Name: "provider-arg",
Uses: provider.SetArgument("provider"),
}
Thus, the user could specify a provider using two flags as in:
--provider download --provider-arg downloader=curl
If the action is set to initialize a flag that is unnamed, the suffix -arg is implied.
Types ¶
type ContextServices ¶
type ContextServices struct {
// contains filtered or unexported fields
}
ContextServices provides an adapter around the context to
func Services ¶
func Services(c context.Context) *ContextServices
Services gets the context services for working with providers. This function panics if the context does not contain context services, which are initialized with the app
func (*ContextServices) LookupRegistry ¶ added in v0.11.0
func (c *ContextServices) LookupRegistry(name any) (*Registry, bool)
LookupRegistry gets the registry by name, if any. The name argument is the name of the registry, but as a special case, if the name starts with dashes as if the name of a flag, those are trimmed. The argument can also be a Flag. The name of the flag is used, or registry specified by the flag's Value.
type Detail ¶
type Detail struct {
// Defaults specifies the default values for the provider.
// The factory or value can provide conventional values as an alternative
// to specifying this value by containing a method Defaults()map[string]string
Defaults map[string]string
// Factory is responsible for creating the provider given the options.
// The value is a function, and must be one of the functions available to
// Factory. //
Factory Factory
// Value is a discrete value to use for the provider. Factory and Value
// are designed to be mutually exclusive; however, when both as specified,
// Factory is used. The use of Value also implies that the provider has
// no defaults.
Value any
// Aliases specifies the aliases that can be used
Aliases []string
// HelpText contains text which briefly describes the usage of the provider.
// The factory or value can provide conventional values as an alternative
// to specifying this value by containing a method HelpText()string
HelpText string
// ManualText provides the text shown in the manual. The default templates don't use this value
ManualText string
// UsageText provides the usage for the provider. If left blank, a succinct synopsis
// is generated from the type of the provider's value
UsageText string
// Description provides a long description for the provider. The long description is
// not used in any templates by default. The type of Description should be string or
// fmt.Stringer. Refer to func Description for details.
Description any
}
Detail provides information about a provider
type Details ¶
Details provides a lookup that provides information about a provider and a factory for instancing it.
func (Details) ProviderNames ¶
type Factory ¶
func FactoryOf ¶ added in v0.10.0
func FactoryOf(fn any, options ...structure.DecoderOption) Factory
FactoryOf uses reflection to create a provider factory function. In particular, the function argument must have a signature that takes one argument for options and return the provider and optionally an error. The actual types can be more specific than interface{}. When they are, type conversion is provided using the Decode method
type FactoryFunc ¶
FactoryFunc describes the factory function for a provider
type Map ¶
Map provides a map that names the providers and their the default values.
func (Map) ProviderNames ¶
type Registry ¶
type Registry struct {
// Name of the registry. This typically shares the name of the flag.
Name string
// Providers names each of the providers which are allowed with a mapping to
// the provider's arguments' defaults. For example, given the example in the
// package overview, a valid initializer would be:
//
// &provider.Registry{
// Providers: provider.Map{
// "json": {
// "indent": "2",
// "encoding": "utf-16",
// },
// },
// }
Providers Lookup
// AllowUnknown determines whether unknown provider names are allowed.
// The default is false, which causes an error when trying to set an unknown
// name.
AllowUnknown bool
}
Registry can be used to add validation to the Provider value and to determine what to be listed. This value is used in the Uses pipeline of either the flag or its containing command.
func (*Registry) ProviderNames ¶
type Value ¶
type Value struct {
// Name is the name of the provider to use
Name string
// Registry specifies the name of the registry to use. If empty, the name of
// the flag selects it
Registry string
// Args provides the arguments to the provider. Args should be any supported
// flag type. If unspecified, a map[string]string is used.
Args any
// contains filtered or unexported fields
}
Value implements a value which can be used as a flag that names a provider. A short syntax allows specifying parameters to the provider. For example, given the flag
&cli.Flag{
Name: "p"
Value: new(provider.Value),
}
It becomes possible to specify the syntax -p Name,arg1=v,arg2=v, which provides the name of the provider to use and argument values to set.
func (*Value) ArgumentFlag ¶
ArgumentFlag obtains a conventions-based flag for setting an argument
func (*Value) DisableSplitting ¶
func (v *Value) DisableSplitting()
DisableSplitting causes commas to be treated literally instead of as delimiters between values.
func (*Value) Initializer ¶
type ValueBinder ¶ added in v0.11.0
type ValueBinder struct {
// contains filtered or unexported fields
}
ValueBinder provides a binder which works with the *provider.Value
func BindValue ¶ added in v0.11.0
func BindValue(nameopt ...any) *ValueBinder
BindValue provides the binder the obtains the provider *Value
func (*ValueBinder) Bind ¶ added in v0.11.0
func (v *ValueBinder) Bind(ctx context.Context) (*Value, error)