yagfuncdata

README

yagfuncdata

Automatically up-to-date list of YAGPDB template functions.

Usage

$ lytfs
# outputs a newline-delimited list of YAGPDB template functions

Installation

Assuming that Go is installed, run the following on the command-line:

$ go install github.com/jo3-l/yagfuncdata/cmd/lytfs@latest

Why use yagfuncdata?

yagfuncdata aims to simplify workflows of projects that require a list of YAGPDB template functions, such as language support extensions for editors. For example, one could imagine setting up a cronjob in CI to run yagfuncdata regularly to check for updates and regenerate an asset file when changes are detected.

Note, however, that it is not recommended to run yagfuncdata directly in an application as the command is not infallible. Changes to the structure of relevant files defining template functions may cause the generated list to be incomplete, or, worse, cause the command to fail entirely. Thus, yagfuncdata's output should be manually vetted by a human against a trusted baseline. Hence, the CI cronjob suggested above should ideally generate a PR with its changes (which can then be reviewed and approved), as opposed to committing directly to the repository.

How does it work?

Instead of hardcoding relevant data (which requires manual updates when upstream sources change), yagfuncdata instead automatically generates it on-demand based on the content of files in the YAGPDB project that define template functions. As such, as long as the structure of said files does not change, upstream modifications to the set of available functions are reflected immediately.

For instance, the StandardFuncMap in common/templates/context.go defines the base set of standard functions. It is structured like such:

var (
	StandardFuncMap = map[string]interface{}{
		"name1": func1,
		"name2": func2,
		[...]
	}
)

Observe that each key in the map literal corresponds to a function name. Thus, to generate a list of standard functions, it suffices to parse the content of common/templates/context.go, look up the declaration of StandardFuncMap, and find all keys present in the map literal. This is precisely the approach that yagfuncdata takes in BaseContextFuncSource.collectStandardContextFuncs.

License

yagfuncdata is made available under the MIT license.

Documentation

Overview

Package yagfuncdata provides up-to-date information regarding the set of functions available in YAGPDB templates.

Index

• Variables
• func Fetch(ctx context.Context, sources []Source) (funcs []string, err error)
• type BaseContextFuncSource
  • func NewBaseContextFuncSource(fcp FileContentProvider) *BaseContextFuncSource
  • func (c *BaseContextFuncSource) Fetch(ctx context.Context) ([]string, error)
• type BuiltinFuncSource
  • func NewBuiltinFuncSource(fcp FileContentProvider) *BuiltinFuncSource
  • func (b *BuiltinFuncSource) Fetch(ctx context.Context) ([]string, error)
• type FileContentProvider
• type GitHubFileProvider
  • func NewGitHubFileProvider(client *github.Client, repoOwner, repoName, ref string) *GitHubFileProvider
  • func (g *GitHubFileProvider) Get(ctx context.Context, path string) (string, error)
• type InteractionContextFuncSource
  • func NewInteractionContextFuncSource(fcp FileContentProvider) *InteractionContextFuncSource
  • func (i *InteractionContextFuncSource) Fetch(ctx context.Context) ([]string, error)
• type PluginExtensionFuncSource
  • func NewCommandsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource
  • func NewCustomCommandsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource
  • func NewLogsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource
  • func NewTicketsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource
  • func (p *PluginExtensionFuncSource) Fetch(ctx context.Context) ([]string, error)
• type Source
  • func DefaultSources(fcp FileContentProvider) []Source
• type StaticFileProvider
  • func NewStaticFileProvider(files map[string]string) *StaticFileProvider
  • func (s *StaticFileProvider) Get(_ context.Context, path string) (string, error)

Variables

var DefaultFileContentProvider = NewGitHubFileProvider(github.NewClient(nil), "botlabs-gg", "yagpdb", "master")

DefaultFileContentProvider is a FileContentProvider that accesses files on the master branch of the YAGPDB repository using an unauthenticated GitHub client.

Functions

func Fetch

func Fetch(ctx context.Context, sources []Source) (funcs []string, err error)

Fetch retrieves the names of functions available in YAGPDB templates from the sources given. For fine-grained control over how sources are queried, use the Source.Fetch method directly.

Types

type BaseContextFuncSource

type BaseContextFuncSource struct {
	// contains filtered or unexported fields
}

func NewBaseContextFuncSource

func NewBaseContextFuncSource(fcp FileContentProvider) *BaseContextFuncSource

NewBaseContextFuncSource creates a new Source that provides information regarding functions defined in common/templates/context.go, which include base context and standard functions.

func (*BaseContextFuncSource) Fetch

func (c *BaseContextFuncSource) Fetch(ctx context.Context) ([]string, error)

type BuiltinFuncSource

type BuiltinFuncSource struct {
	// contains filtered or unexported fields
}

func NewBuiltinFuncSource

func NewBuiltinFuncSource(fcp FileContentProvider) *BuiltinFuncSource

NewBuiltinFuncSource creates a new Source that provides information regarding builtin template functions defined in lib/template/funcs.go.

func (*BuiltinFuncSource) Fetch

func (b *BuiltinFuncSource) Fetch(ctx context.Context) ([]string, error)

type FileContentProvider

type FileContentProvider interface {
	Get(ctx context.Context, path string) (content string, err error)
}

A FileContentProvider provides access to file content.

type GitHubFileProvider

type GitHubFileProvider struct {
	// contains filtered or unexported fields
}

func NewGitHubFileProvider

func NewGitHubFileProvider(client *github.Client, repoOwner, repoName, ref string) *GitHubFileProvider

NewGitHubFileProvider creates a new FileContentProvider that accesses files from a GitHub repository at a specific Git reference using the client provided.

func (*GitHubFileProvider) Get

func (g *GitHubFileProvider) Get(ctx context.Context, path string) (string, error)

type InteractionContextFuncSource

type InteractionContextFuncSource struct {
	// contains filtered or unexported fields
}

func NewInteractionContextFuncSource

func NewInteractionContextFuncSource(fcp FileContentProvider) *InteractionContextFuncSource

NewInteractionContextFuncSource creates a new Source that provides information regarding interaction context functions defined in lib/template/context_interactions.go.

func (*InteractionContextFuncSource) Fetch

func (i *InteractionContextFuncSource) Fetch(ctx context.Context) ([]string, error)

type PluginExtensionFuncSource

type PluginExtensionFuncSource struct {
	// contains filtered or unexported fields
}

A PluginExtensionFuncSource provides information regarding template functions added by a plugin. For example, the logs plugin registers pastUsernames and pastNicknames in logs/template_extensions.go.

func NewCommandsPluginExtensionFuncSource

func NewCommandsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource

NewCommandsPluginExtensionFuncSource creates a new Source that provides information regarding extension template functions registered by the command plugin in commands/tmplexec.go.

func NewCustomCommandsPluginExtensionFuncSource

func NewCustomCommandsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource

NewCustomCommandsPluginExtensionFuncSource creates a new Source that provides information regarding extension template functions registered by the custom commands plugin in customcommands/tmplextensions.go

func NewLogsPluginExtensionFuncSource

func NewLogsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource

NewLogsPluginExtensionFuncSource creates a new Source that provides information regarding extension template functions registered by the logs plugin in logs/template_extensions.go.

func NewTicketsPluginExtensionFuncSource

func NewTicketsPluginExtensionFuncSource(fcp FileContentProvider) *PluginExtensionFuncSource

NewTicketsPluginExtensionFuncSource creates a new Source that provides information regarding extension template functions registered by the tickets plugin in tickets/tmplextensions.go.

func (*PluginExtensionFuncSource) Fetch

func (p *PluginExtensionFuncSource) Fetch(ctx context.Context) ([]string, error)

type Source

type Source interface {
	Fetch(ctx context.Context) (funcs []string, err error)
}

A Source is a source of YAGPDB template function information.

func DefaultSources

func DefaultSources(fcp FileContentProvider) []Source

DefaultSources returns a set of builtin sources that use the given FileContentProvider.

type StaticFileProvider

type StaticFileProvider struct {
	// contains filtered or unexported fields
}

func NewStaticFileProvider

func NewStaticFileProvider(files map[string]string) *StaticFileProvider

NewStaticFileProvider creates a new FileContentProvider based on the contents of the provided map. For every path such that files[path] == content, Get(ctx, path) will return content.

func (*StaticFileProvider) Get

func (s *StaticFileProvider) Get(_ context.Context, path string) (string, error)