schema

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 12, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultSlug = "default"
View Source 
const GlobalDefaultSlug = "global-default"

Variables

This section is empty.

Functions

func AddFlagGroupToCobraCommand added in v1.0.0 

func AddFlagGroupToCobraCommand(
	cmd *cobra.Command,
	id string,
	name string,
	flags *fields.Definitions,
	prefix string,
)

AddFlagGroupToCobraCommand adds a flag group to a cobra command. This is done by adding a set of annotations to the command:

  • glazed:flag-group-order: a comma-separated list of flag group IDs in the order they should be displayed
  • glazed:flag-group-count: the number of flag groups
  • glazed:flag-group:<id>:<name> - a list of the flag names in the group
  • glazed:flag-group-prefix:<id> - the prefix to use for the group

func InitializeSectionWithDefaults added in v1.0.0 

func InitializeSectionWithDefaults(
	v Section,
	sectionValues *values.SectionValues,
	options ...fields.ParseOption,
) error

func SetFlagGroupOrder added in v1.0.0 

func SetFlagGroupOrder(cmd *cobra.Command, order []string)

Types

type BlacklistSection added in v1.0.0 

type BlacklistSection struct {
	Section
	BlacklistedFields map[string]interface{}
}

func NewBlacklistSection added in v1.0.0 

func NewBlacklistSection(section Section, blacklistedFields map[string]interface{}) *BlacklistSection

func (*BlacklistSection) GetDefinitions added in v1.0.0 

func (l *BlacklistSection) GetDefinitions() *fields.Definitions

type CobraSection added in v1.0.0 

type CobraSection interface {
	Section
	// AddSectionToCobraCommand adds all the flags and arguments defined in this section to the given cobra command.
	AddSectionToCobraCommand(cmd *cobra.Command) error
	ParseSectionFromCobraCommand(cmd *cobra.Command, options ...fields.ParseOption) (*values.SectionValues, error)
}

type CommandFlagGroupUsage added in v1.0.0 

type CommandFlagGroupUsage struct {
	LocalGroupUsages     []*FlagGroupUsage
	InheritedGroupUsages []*FlagGroupUsage
}

CommandFlagGroupUsage is used to render the flags for an entire command. This gets parsed at rendering time, and passed along the command to the usage or help template. Fields that are not assigned to any group are passed as the "" group, with the name "Other flags".

func ComputeCommandFlagGroupUsage added in v1.0.0 

func ComputeCommandFlagGroupUsage(c *cobra.Command) *CommandFlagGroupUsage

ComputeCommandFlagGroupUsage is used to compute the flag groups to be shown in the Usage help function.

It is a fairly complex function that gathers all LocalFlags() and InheritedFlags() from the cobra backend. It then iterated over the FlagGroups that have been added through sections usually.

func (*CommandFlagGroupUsage) String added in v1.0.0 

func (c *CommandFlagGroupUsage) String() string

type ErrInvalidSection added in v1.0.0 

type ErrInvalidSection struct {
	Name     string
	Expected string
}

func (ErrInvalidSection) Error added in v1.0.0 

func (e ErrInvalidSection) Error() string

type FlagGroup added in v1.0.0 

type FlagGroup struct {
	ID     string
	Name   string
	Prefix string
	Flags  []string
	Order  int
}

FlagGroup is a group of flags that can be added to a cobra command. While we mostly deal with Definitions, this uses strings because it can be applied to any cobra flag in general.

It limits us in the sense that we can't just get the full FieldDefinition here, but at least we can format our help a little bit more nicely.

NOTE(manuel, 2023-02-20) This doesn't allow for hierarchical flag groups yet. Let's see how this feels overall, and if this is something we want to add later on. This is useful I think because subsystems such as glaze already pull in so many flags, and it could be used in conjunction with renaming the actual flags used on the CLI as more colisions are prone to happen.

func GetFlagGroups added in v1.0.0 

func GetFlagGroups(cmd *cobra.Command) []*FlagGroup

GetFlagGroups returns a list of flag groups for the given command. It does so by gathering all parents flag groups and then checking for cobra Annotations of the form `glazed:flag-group:<id>:<name>`.

The order of the groups is determined by the order of the ids in the `glazed:flag-group-order` annotation.

Finally, the `glazed:flag-group-prefix:<id>:<prefix>` annotation is used to determine the prefix for the group.

type FlagGroupUsage added in v1.0.0 

type FlagGroupUsage struct {
	Slug          string
	Name          string
	FlagUsages    []*FlagUsage
	MaxFlagLength int
}

FlagGroupUsage is used to render the help for a flag group. It consists of the group Name for rendering purposes, and a single string per flag in the group

func (*FlagGroupUsage) AddFlagUsage added in v1.0.0 

func (f *FlagGroupUsage) AddFlagUsage(flag *FlagUsage)

func (*FlagGroupUsage) String added in v1.0.0 

func (f *FlagGroupUsage) String() string

type FlagUsage added in v1.0.0 

type FlagUsage struct {
	ShortHand  string
	Long       string
	FlagString string
	Help       string
	Default    string
}

FlagUsage is the structured information we want to show at help time. Instead of rendering the full time, we leave how these things are formatted all the way to the end, because for example aligning strings can only be done at runtime since we don't know which other flags might have been added to the one group.

type Schema 

type Schema struct {
	*orderedmap.OrderedMap[string, Section]
}

func NewSchema 

func NewSchema(options ...SchemaOption) *Schema

func (*Schema) AddToCobraCommand added in v1.0.0 

func (pl *Schema) AddToCobraCommand(cmd *cobra.Command) error

func (*Schema) AppendSections added in v1.0.0 

func (pl *Schema) AppendSections(sections ...Section)

func (*Schema) AsList added in v1.0.0 

func (pl *Schema) AsList() []Section

func (*Schema) Clone added in v1.0.0 

func (pl *Schema) Clone() *Schema

func (*Schema) ForEach added in v1.0.0 

func (pl *Schema) ForEach(f func(key string, p Section))

ForEach iterates over each element in the Schema map and applies the given function to each key-value pair.

func (*Schema) ForEachE added in v1.0.0 

func (pl *Schema) ForEachE(f func(key string, p Section) error) error

ForEachE applies a function to each key-value pair in the Schema, in oldest-to-newest order. It stops iteration and returns the first error encountered, if any.

func (*Schema) GetAllDefinitions added in v1.0.0 

func (pl *Schema) GetAllDefinitions() *fields.Definitions

func (*Schema) InitializeFromDefaults added in v1.0.0 

func (pl *Schema) InitializeFromDefaults(options ...fields.ParseOption) (*values.Values, error)

func (*Schema) MarshalJSON added in v1.0.0 

func (pl *Schema) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler interface

func (*Schema) MarshalYAML added in v1.0.0 

func (pl *Schema) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler interface

func (*Schema) Merge added in v1.0.0 

func (pl *Schema) Merge(p *Schema) *Schema

func (*Schema) PrependSections added in v1.0.0 

func (pl *Schema) PrependSections(sections ...Section)

func (*Schema) Subset added in v1.0.0 

func (pl *Schema) Subset(slugs ...string) *Schema

func (*Schema) UpdateWithDefaults added in v1.0.0 

func (pl *Schema) UpdateWithDefaults(parsedValues *values.Values, options ...fields.ParseOption) error

type SchemaOption 

type SchemaOption func(*Schema)

func WithSections 

func WithSections(sections ...Section) SchemaOption

type Section 

type Section interface {
	AddFields(defs ...*fields.Definition)
	GetDefinitions() *fields.Definitions

	InitializeDefaultsFromStruct(s interface{}) error

	GetName() string
	GetSlug() string
	GetDescription() string
	GetPrefix() string

	Clone() Section
}

Section is a struct that is used by one specific functionality section to group and describe all the field definitions that it uses. It also provides a location for a name, slug and description to be used in help pages.

TODO(manuel, 2023-12-20) This is a pretty messy interface, I think it used to be a struct?

type SectionImpl 

type SectionImpl struct {
	Name          string              `yaml:"name"`
	Slug          string              `yaml:"slug"`
	Description   string              `yaml:"description"`
	Prefix        string              `yaml:"prefix"`
	Definitions   *fields.Definitions `yaml:"flags,omitempty"`
	ChildSections []Section           `yaml:"childSections,omitempty"`
}

SectionImpl is a straight forward simple implementation of Section that can easily be reused in more complex implementations.

func NewSection 

func NewSection(slug string, name string, options ...SectionOption) (*SectionImpl, error)

func NewSectionFromYAML added in v1.0.0 

func NewSectionFromYAML(s []byte, options ...SectionOption) (*SectionImpl, error)

func (*SectionImpl) AddFields added in v1.0.0 

func (p *SectionImpl) AddFields(flag ...*fields.Definition)

func (*SectionImpl) AddSectionToCobraCommand added in v1.0.0 

func (p *SectionImpl) AddSectionToCobraCommand(cmd *cobra.Command) error

AddSectionToCobraCommand adds all flags of the section to the given Cobra command. It also creates a flag group representing the section and adds it to the command. If the section has a prefix, the flags are added with that prefix.

func (*SectionImpl) Clone added in v1.0.0 

func (p *SectionImpl) Clone() Section

func (*SectionImpl) GatherFieldsFromMap added in v1.0.0 

func (p *SectionImpl) GatherFieldsFromMap(
	m map[string]interface{}, onlyProvided bool,
	options ...fields.ParseOption,
) (*fields.FieldValues, error)

func (*SectionImpl) GetDefinitions added in v1.0.0 

func (p *SectionImpl) GetDefinitions() *fields.Definitions

GetDefinitions returns a map that maps all fields (flags and arguments) to their name. I'm not sure if this is worth caching, but if we hook this up like something like a lambda that might become more relevant.

func (*SectionImpl) GetDescription added in v1.0.0 

func (p *SectionImpl) GetDescription() string

func (*SectionImpl) GetName added in v1.0.0 

func (p *SectionImpl) GetName() string

func (*SectionImpl) GetPrefix added in v1.0.0 

func (p *SectionImpl) GetPrefix() string

func (*SectionImpl) GetSlug added in v1.0.0 

func (p *SectionImpl) GetSlug() string

func (*SectionImpl) InitializeDefaultsFromFields added in v1.0.0 

func (p *SectionImpl) InitializeDefaultsFromFields(
	ps map[string]interface{},
) error

InitializeDefaultsFromFields initializes the field definitions of the section from the given map of field values. The field definitions are updated in-place.

func (*SectionImpl) InitializeDefaultsFromStruct added in v1.0.0 

func (p *SectionImpl) InitializeDefaultsFromStruct(defaults interface{}) error

InitializeDefaultsFromStruct initializes the `Definition` of the section, which are often defined at compile time and loaded from a YAML file, with fresh ones from the struct. This is in some ways the opposite of `InitializeStructFromFieldDefaults`. The struct fields of `defaults` with a struct tag of `glazed` are used to initialize the `Definition` with a matching name. If no matching `Definition` is found, an error is returned.

func (*SectionImpl) InitializeStructFromFieldDefaults added in v1.0.0 

func (p *SectionImpl) InitializeStructFromFieldDefaults(s interface{}) error

func (*SectionImpl) LoadFromYAML added in v1.0.0 

func (p *SectionImpl) LoadFromYAML(s []byte) error

func (*SectionImpl) ParseSectionFromCobraCommand added in v1.0.0 

func (p *SectionImpl) ParseSectionFromCobraCommand(
	cmd *cobra.Command,
	options ...fields.ParseOption,
) (*values.SectionValues, error)

ParseSectionFromCobraCommand parses the flags of the section from the given Cobra command. If the section has a prefix, the flags are parsed with that prefix (meaning, the prefix is stripped from the flag names before they are added to the returned map).

This will return a map containing the value (or default value) of each flag of the section.

func (*SectionImpl) UnmarshalYAML added in v1.0.0 

func (p *SectionImpl) UnmarshalYAML(unmarshal func(interface{}) error) error

type SectionOption 

type SectionOption func(*SectionImpl) error

func WithArguments 

func WithArguments(arguments ...*fields.Definition) SectionOption

func WithDefaults 

func WithDefaults(s interface{}) SectionOption

func WithDescription 

func WithDescription(description string) SectionOption

func WithFields 

func WithFields(definitions ...*fields.Definition) SectionOption

func WithName 

func WithName(name string) SectionOption

func WithPrefix 

func WithPrefix(prefix string) SectionOption

type SerializableSchema added in v1.0.0 

type SerializableSchema struct {
	// Using orderedmap to maintain section order while having slug-based access.
	Sections *orderedmap.OrderedMap[string, *SerializableSection] `yaml:"sections" json:"sections"`
}

SerializableSchema represents a collection of sections in a format suitable for YAML/JSON serialization, maintaining the order of sections.

func SchemaToSerializable added in v1.0.0 

func SchemaToSerializable(schema *Schema) *SerializableSchema

SchemaToSerializable converts a Schema collection to its serializable representation.

func (*SerializableSchema) MarshalJSON added in v1.0.0 

func (sl *SerializableSchema) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for SerializableSchema.

func (*SerializableSchema) MarshalYAML added in v1.0.0 

func (sl *SerializableSchema) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler for SerializableSchema.

type SerializableSection added in v1.0.0 

type SerializableSection struct {
	Name        string              `yaml:"name" json:"name"`
	Slug        string              `yaml:"slug" json:"slug"`
	Description string              `yaml:"description" json:"description"`
	Prefix      string              `yaml:"prefix,omitempty" json:"prefix,omitempty"`
	Fields      *fields.Definitions `yaml:"fields" json:"fields"`
}

SerializableSection represents a schema section in a format suitable for YAML/JSON serialization.

func ToSerializable added in v1.0.0 

func ToSerializable(section Section) *SerializableSection

ToSerializable converts a Section to its serializable representation.

type WhitelistSection added in v1.0.0 

type WhitelistSection struct {
	Section
	WhitelistedFields map[string]interface{}
}

func NewWhitelistSection added in v1.0.0 

func NewWhitelistSection(section Section, whitelistedFields map[string]interface{}) *WhitelistSection

func (*WhitelistSection) GetDefinitions added in v1.0.0 

func (l *WhitelistSection) GetDefinitions() *fields.Definitions

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.