help

package
v0.4.23 Latest Latest
Warning

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

 Go to latest Published: Oct 25, 2023 License: MIT Imports: 19 Imported by: 44

Documentation

Index

Constants

This section is empty.

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

Functions

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 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 {
	Sections []*Section
}

func NewHelpSystem 

func NewHelpSystem() *HelpSystem

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) 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)

type RenderOptions 

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

type Section 

type Section struct {
	Slug        string
	SectionType SectionType

	Title    string
	SubTitle string
	Short    string
	Content  string

	// metadata used to search and select sections to be shown
	Topics   []string
	Flags    []string
	Commands []string

	// Show this section in the toplevel help
	IsTopLevel bool

	IsTemplate bool

	// show this template as a default example
	ShowPerDefault bool

	// Used to give some rough sense of order, not sure how useful this is going to be
	Order int

	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(sections []*Section) []*Section

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 int
const (
	SectionGeneralTopic SectionType = iota
	SectionExample
	SectionApplication
	SectionTutorial
)

func SectionTypeFromString 

func SectionTypeFromString(s string) (SectionType, error)

func (SectionType) String 

func (s SectionType) String() string

type UsageFunc 

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

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.