help

package
v0.5.53 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2025 License: MIT Imports: 24 Imported by: 69

Documentation

Index

Constants

View Source 
const (
	SectionGeneralTopic = model.SectionGeneralTopic
	SectionExample      = model.SectionExample
	SectionApplication  = model.SectionApplication
	SectionTutorial     = model.SectionTutorial
)

Variables

View Source 
var COBRA_COMMAND_HELP_TEMPLATE string
View Source 
var COBRA_COMMAND_SHORT_HELP_TEMPLATE string
View Source 
var COBRA_COMMAND_USAGE_TEMPLATE string

COBRA_COMMAND_USAGE_TEMPLATE - template used by the glazed library help cobra command. This template has been adapted from the cobra usage command template.

Original: https://github.com/spf13/cobra

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

2022-12-03 - Manuel Odendahl - Augmented template with sections 2022-12-04 - Manuel Odendahl - Significantly reworked to support markdown sections

View Source 
var HELP_LIST_TEMPLATE string
View Source 
var HELP_LONG_SECTION_TEMPLATE string
View Source 
var HELP_SHORT_SECTION_TEMPLATE string
View Source 
var HELP_SHORT_TOPIC_TEMPLATE string
View Source 
var HELP_TOPIC_TEMPLATE string
View Source 
var SectionTypeFromString = model.SectionTypeFromString

Re-export functions from model package

Functions

func ExampleStoreUsage added in v0.5.53 

func ExampleStoreUsage()

ExampleStoreUsage demonstrates how to use the new store-based query functionality

func GetCobraHelpUsageFuncs 

func GetCobraHelpUsageFuncs(hs *HelpSystem) (HelpFunc, UsageFunc)

func GetCobraHelpUsageTemplates 

func GetCobraHelpUsageTemplates(hs *HelpSystem) (string, string)

func NewCobraHelpCommand 

func NewCobraHelpCommand(hs *HelpSystem) *cobra.Command

NewCobraHelpCommand uses the InitDefaultHelpCommand code from cobra. This code is lifted from cobra and modified to accommodate help sections

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

2022-12-03 - Manuel Odendahl - Added support for help sections 2022-12-04 - Manuel Odendahl - Significantly reworked to support markdown sections

func NewCobraHelpCommandWithUI added in v0.5.53 

func NewCobraHelpCommandWithUI(hs *HelpSystem, uiFunc UIFunc) *cobra.Command

func RenderToMarkdown 

func RenderToMarkdown(t *template.Template, data interface{}, output *os.File) (string, error)

Types

type HelpError 

type HelpError int
const (
	ErrSectionNotFound HelpError = iota
)

func (HelpError) Error 

func (e HelpError) Error() string

type HelpFunc 

type HelpFunc = func(c *cobra.Command, args []string)

type HelpPage 

type HelpPage struct {
	DefaultGeneralTopics []*Section
	OtherGeneralTopics   []*Section
	// this is just the concatenation of default and others
	AllGeneralTopics []*Section

	DefaultExamples []*Section
	OtherExamples   []*Section
	AllExamples     []*Section

	DefaultApplications []*Section
	OtherApplications   []*Section
	AllApplications     []*Section

	DefaultTutorials []*Section
	OtherTutorials   []*Section
	AllTutorials     []*Section
}

HelpPage contains all the sections related to a command

func NewHelpPage 

func NewHelpPage(sections []*Section) *HelpPage

type HelpSystem 

type HelpSystem struct {
	Store *store.Store // Store backend
}

func NewHelpSystem 

func NewHelpSystem() *HelpSystem

func NewHelpSystemWithStore added in v0.5.53 

func NewHelpSystemWithStore(st *store.Store) *HelpSystem

NewHelpSystemWithStore creates a HelpSystem with store backend support

func (*HelpSystem) AddSection 

func (hs *HelpSystem) AddSection(section *Section)

func (*HelpSystem) ComputeRenderData 

func (hs *HelpSystem) ComputeRenderData(userQuery *SectionQuery) (map[string]interface{}, bool)

func (*HelpSystem) GetSectionWithSlug 

func (hs *HelpSystem) GetSectionWithSlug(slug string) (*Section, error)

func (*HelpSystem) GetTopLevelHelpPage 

func (hs *HelpSystem) GetTopLevelHelpPage() *HelpPage

func (*HelpSystem) LoadSectionsFromFS added in v0.2.4 

func (hs *HelpSystem) LoadSectionsFromFS(f fs.FS, dir string) error

func (*HelpSystem) PrintQueryDebug added in v0.5.53 

func (hs *HelpSystem) PrintQueryDebug(queryDSL string, printQuery, printSQL bool) error

PrintQueryDebug prints debug information about a query

func (*HelpSystem) QuerySections added in v0.5.53 

func (hs *HelpSystem) QuerySections(query string) ([]*Section, error)

QuerySections performs a DSL query on the current help system with boolean logic support

func (*HelpSystem) RenderTopicHelp 

func (hs *HelpSystem) RenderTopicHelp(
	topicSection *Section,
	options *RenderOptions) (string, error)

func (*HelpSystem) SetupCobraRootCommand added in v0.2.46 

func (hs *HelpSystem) SetupCobraRootCommand(cmd *cobra.Command)

func (*HelpSystem) SetupCobraRootCommandWithUI added in v0.5.53 

func (hs *HelpSystem) SetupCobraRootCommandWithUI(cmd *cobra.Command, uiFunc UIFunc)

type RenderOptions 

type RenderOptions struct {
	Query           *SectionQuery
	ShowAllSections bool
	ShowShortTopic  bool
	HelpCommand     string
	LongHelp        bool
	ListSections    bool
	OnlyTopLevel    bool
}

type Section 

type Section struct {
	*model.Section
	HelpSystem *HelpSystem
}

Section is a structure describing an actual documentation section.

This can describe:

  • a general topic: think of this as an entry in a book
  • an example: a way to run a certain command
  • an application: a concrete use case for running a command. This can potentially use additional external tools, multiple commands, etc. While it is nice to keep these self-contained, it is not required.
  • a tutorial: a step-by-step guide to running a command.

Run `glaze help help-system` for more information.

func LoadSectionFromMarkdown 

func LoadSectionFromMarkdown(markdownBytes []byte) (*Section, error)

func (*Section) DefaultApplications 

func (s *Section) DefaultApplications() []*Section

func (*Section) DefaultExamples 

func (s *Section) DefaultExamples() []*Section

func (*Section) DefaultGeneralTopic 

func (s *Section) DefaultGeneralTopic() []*Section

func (*Section) DefaultTutorials 

func (s *Section) DefaultTutorials() []*Section

func (*Section) IsForCommand 

func (s *Section) IsForCommand(command string) bool

func (*Section) IsForFlag 

func (s *Section) IsForFlag(flag string) bool

func (*Section) IsForTopic 

func (s *Section) IsForTopic(topic string) bool

func (*Section) OtherApplications 

func (s *Section) OtherApplications() []*Section

func (*Section) OtherExamples 

func (s *Section) OtherExamples() []*Section

func (*Section) OtherTutorials 

func (s *Section) OtherTutorials() []*Section

type SectionQuery 

type SectionQuery struct {
	OnlyShownByDefault    bool
	OnlyNotShownByDefault bool
	OnlyTopLevel          bool

	// only these types will be returned
	Types map[SectionType]bool

	// if any of these is set, and they match each of the Only types,
	// the section will be return
	Topics   []string
	Flags    []string
	Commands []string
	Slugs    []string

	// this will return any section as long as it matches the Only strings
	All bool

	SearchedCommand string
	SearchedSlug    string

	// a section will be returned only if it matches all
	// of the following criteria
	OnlyTopics   []string
	OnlyFlags    []string
	OnlyCommands []string

	// We often need to filter sections that have already been shown
	WithoutSections []*Section
}

SectionQuery represents a query to get different types of sections.

This is used for example by the `help` command line function to render out the help sections for individual commands.

It can however also be used on its own.

func NewSectionQuery 

func NewSectionQuery() *SectionQuery

func (*SectionQuery) Clone 

func (s *SectionQuery) Clone() *SectionQuery

func (*SectionQuery) DontReturnApplications 

func (s *SectionQuery) DontReturnApplications() *SectionQuery

func (*SectionQuery) DontReturnExamples 

func (s *SectionQuery) DontReturnExamples() *SectionQuery

func (*SectionQuery) DontReturnTopics 

func (s *SectionQuery) DontReturnTopics() *SectionQuery

func (*SectionQuery) DontReturnTutorials 

func (s *SectionQuery) DontReturnTutorials() *SectionQuery

func (*SectionQuery) FilterSections 

func (s *SectionQuery) FilterSections(sections ...*Section) *SectionQuery

func (*SectionQuery) FindSections 

func (s *SectionQuery) FindSections(ctx context.Context, st *store.Store) ([]*Section, error)

FindSections queries sections using the store backend

func (*SectionQuery) GetOnlyQueryAsString 

func (s *SectionQuery) GetOnlyQueryAsString() string

func (*SectionQuery) GetRequestedTypesAsString 

func (s *SectionQuery) GetRequestedTypesAsString() string

func (*SectionQuery) HasOnlyQueries 

func (s *SectionQuery) HasOnlyQueries() bool

func (*SectionQuery) HasRestrictedReturnTypes 

func (s *SectionQuery) HasRestrictedReturnTypes() bool

func (*SectionQuery) IsOnlyTopLevel 

func (s *SectionQuery) IsOnlyTopLevel() bool

func (*SectionQuery) ResetOnlyQueries 

func (s *SectionQuery) ResetOnlyQueries() *SectionQuery

func (*SectionQuery) ReturnAllTypes 

func (s *SectionQuery) ReturnAllTypes() *SectionQuery

func (*SectionQuery) ReturnAnyOfCommands 

func (s *SectionQuery) ReturnAnyOfCommands(commands ...string) *SectionQuery

func (*SectionQuery) ReturnAnyOfFlags 

func (s *SectionQuery) ReturnAnyOfFlags(flags ...string) *SectionQuery

func (*SectionQuery) ReturnAnyOfSlugs 

func (s *SectionQuery) ReturnAnyOfSlugs(slugs ...string) *SectionQuery

func (*SectionQuery) ReturnAnyOfTopics 

func (s *SectionQuery) ReturnAnyOfTopics(topics ...string) *SectionQuery

func (*SectionQuery) ReturnApplications 

func (s *SectionQuery) ReturnApplications() *SectionQuery

func (*SectionQuery) ReturnExamples 

func (s *SectionQuery) ReturnExamples() *SectionQuery

func (*SectionQuery) ReturnOnlyCommands 

func (s *SectionQuery) ReturnOnlyCommands(commands ...string) *SectionQuery

func (*SectionQuery) ReturnOnlyFlags 

func (s *SectionQuery) ReturnOnlyFlags(flags ...string) *SectionQuery

func (*SectionQuery) ReturnOnlyNotShownByDefault 

func (s *SectionQuery) ReturnOnlyNotShownByDefault() *SectionQuery

func (*SectionQuery) ReturnOnlyShownByDefault 

func (s *SectionQuery) ReturnOnlyShownByDefault() *SectionQuery

func (*SectionQuery) ReturnOnlyTopLevel 

func (s *SectionQuery) ReturnOnlyTopLevel() *SectionQuery

func (*SectionQuery) ReturnOnlyTopics 

func (s *SectionQuery) ReturnOnlyTopics(topics ...string) *SectionQuery

func (*SectionQuery) ReturnTopics 

func (s *SectionQuery) ReturnTopics() *SectionQuery

func (*SectionQuery) ReturnTutorials 

func (s *SectionQuery) ReturnTutorials() *SectionQuery

func (*SectionQuery) SearchForCommand 

func (s *SectionQuery) SearchForCommand(command string) *SectionQuery

func (*SectionQuery) SearchForSlug 

func (s *SectionQuery) SearchForSlug(slug string) *SectionQuery

type SectionType 

type SectionType = model.SectionType

Re-export types from model package for backward compatibility

type UIFunc added in v0.5.53 

type UIFunc = func(hs *HelpSystem) error

type UsageFunc 

type UsageFunc = func(c *cobra.Command) error

Source Files

View all Source files

Directories

Path Synopsis

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.