Documentation
¶
Overview ¶
Copyright 2023 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file.
Copyright 2025 The Joe-cli Authors. All rights reserved. Use of this source code is governed by a BSD-style license that can be found in the LICENSE file. 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 ListProviders ¶
func ListProviders(name string) cli.Action
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 ¶
func SetArgument(name string) cli.Action
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 *cli.Context) *ContextServices
Services obtains the contextual services used by the package. If not already present, it will be added to the context.
func WithServices ¶
func WithServices(c context.Context) (context.Context, *ContextServices)
WithServices obtains the context services from the specified context. If they do not exist, they are added and the context result is returned.
func (*ContextServices) Registry ¶
func (c *ContextServices) Registry(name string) *Registry
Registry gets the registry by name, if any
type Detail ¶
type Detail struct {
// Defaults specifies the default values for the provider
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
// FactoryFunc
Factory FactoryFunc
// 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
// HelpText contains text which briefly describes the usage of the provider.
HelpText string
}
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 FactoryFunc ¶
FactoryFunc describes the factory function for a provider
func Factory ¶
func Factory(fn any, options ...structure.DecoderOption) FactoryFunc
Factory 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 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, which is the same as 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
// 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 ¶
func (v *Value) ArgumentFlag() cli.Prototype
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 ¶
func (v *Value) Initializer() cli.Action
Source Files