docs

package
v3.47.0 Latest Latest
Warning

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

 Go to latest Published: Jun 16, 2021 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package docs provides useful functions for creating documentation from Benthos components

Index

Constants

This section is empty.

Variables

View Source 
var (

	// ErrBadLabel is returned when creating a component with a bad label.
	ErrBadLabel = fmt.Errorf("should match the regular expression /%v/ and must not start with an underscore", labelExpression)
)

Functions

func BloblangFunctionsMarkdown added in v3.26.0 

func BloblangFunctionsMarkdown() ([]byte, error)

BloblangFunctionsMarkdown returns a markdown document for all Bloblang functions.

func BloblangMethodsMarkdown added in v3.26.0 

func BloblangMethodsMarkdown() ([]byte, error)

BloblangMethodsMarkdown returns a markdown document for all Bloblang methods.

func GetPluginConfigNode added in v3.47.0 

func GetPluginConfigNode(name string, value *yaml.Node) (yaml.Node, error)

GetPluginConfigNode extracts a plugin configuration node from a component config. This exists because there are two styles of plugin config, the old style (within `plugin`):

type: foo plugin: 

bar: baz

And the new style:

foo: 

bar: baz

func RegisterDocs added in v3.43.0 

func RegisterDocs(spec ComponentSpec)

RegisterDocs stores the documentation spec for a component.

func SanitiseComponentConfig added in v3.43.0 

func SanitiseComponentConfig(componentType Type, raw interface{}, filter FieldFilter) error

SanitiseComponentConfig reduces a raw component configuration into only the fields for the component name configured.

TODO: V4 Remove this

func SanitiseNode added in v3.43.0 

func SanitiseNode(cType Type, node *yaml.Node, conf SanitiseConfig) error

SanitiseNode takes a yaml.Node and a config spec and sorts the fields of the node according to the spec. Also optionally removes the `type` field from this and all nested components.

func ValidateLabel added in v3.43.0 

func ValidateLabel(label string) error

ValidateLabel attempts to validate the contents of a component label.

Types

type AnnotatedExample added in v3.25.0 

type AnnotatedExample struct {
	// A title for the example.
	Title string

	// Summary of the example.
	Summary string

	// A config snippet to show.
	Config string
}

AnnotatedExample is an isolated example for a component.

type ComponentSpec 

type ComponentSpec struct {
	// Name of the component
	Name string

	// Type of the component (input, output, etc)
	Type Type

	// The status of the component.
	Status Status

	// Plugin is true for all plugin components.
	Plugin bool

	// Summary of the component (in markdown, must be short).
	Summary string

	// Description of the component (in markdown).
	Description string

	// Categories that describe the purpose of the component.
	Categories []string

	// Footnotes of the component (in markdown).
	Footnotes string

	// Examples demonstrating use cases for the component.
	Examples []AnnotatedExample

	// A summary of each field in the component configuration.
	Config FieldSpec

	// Version is the Benthos version this component was introduced.
	Version string
}

ComponentSpec describes a Benthos component.

func GetDocs added in v3.43.0 

func GetDocs(name string, ctype Type) (ComponentSpec, bool)

GetDocs attempts to locate a documentation spec for a component identified by a unique name and type combination.

func GetInferenceCandidate added in v3.43.0 

func GetInferenceCandidate(t Type, defaultType string, raw interface{}) (string, ComponentSpec, error)

GetInferenceCandidate checks a generic config structure for a component and returns either the inferred type name or an error if one cannot be inferred.

func GetInferenceCandidateFromNode added in v3.43.0 

func GetInferenceCandidateFromNode(t Type, defaultType string, node *yaml.Node) (string, ComponentSpec, error)

GetInferenceCandidateFromNode checks a yaml node config structure for a component and returns either the inferred type name or an error if one cannot be inferred.

func (*ComponentSpec) AsMarkdown 

func (c *ComponentSpec) AsMarkdown(nest bool, fullConfigExample interface{}) ([]byte, error)

AsMarkdown renders the spec of a component, along with a full configuration example, into a markdown document.

type FieldFilter added in v3.43.0 

type FieldFilter func(spec FieldSpec) bool

FieldFilter defines a filter closure that returns a boolean for a component field indicating whether the field should be kept within a generated config.

func ShouldDropDeprecated added in v3.43.0 

func ShouldDropDeprecated(b bool) FieldFilter

ShouldDropDeprecated returns a field filter that removes all deprecated fields when the boolean argument is true.

type FieldSpec 

type FieldSpec struct {
	// Name of the field (as it appears in config).
	Name string

	// Description of the field purpose (in markdown).
	Description string

	// Advanced is true for optional fields that will not be present in most
	// configs.
	Advanced bool

	// Deprecated is true for fields that are deprecated and only exist for
	// backwards compatibility reasons.
	Deprecated bool

	// Default value of the field. If left nil the docs generator will attempt
	// to infer the default value from an example config.
	Default *interface{}

	// Type of the field. This is optional and doesn't prevent documentation for
	// a field.
	Type FieldType

	// IsArray indicates whether this field is an array of the FieldType.
	IsArray bool

	// IsMap indicates whether this field is a map of keys to the FieldType.
	IsMap bool

	// Interpolation indicates that the field supports interpolation functions.
	Interpolated bool

	// Examples is a slice of optional example values for a field.
	Examples []interface{}

	// AnnotatedOptions for this field. Each option should have a summary.
	AnnotatedOptions [][2]string

	// Options for this field.
	Options []string

	// Children fields of this field (it must be an object).
	Children FieldSpecs

	// Version lists an explicit Benthos release where this fields behaviour was last modified.
	Version string

	// ExamplesMarshalled is a list of examples marshalled into YAML format.
	ExamplesMarshalled []string
	// contains filtered or unexported fields
}

FieldSpec describes a component config field.

func FieldAdvanced 

func FieldAdvanced(name, description string, examples ...interface{}) FieldSpec

FieldAdvanced returns a field spec for an advanced field.

func FieldCommon 

func FieldCommon(name, description string, examples ...interface{}) FieldSpec

FieldCommon returns a field spec for a common field.

func FieldComponent added in v3.43.0 

func FieldComponent() FieldSpec

FieldComponent returns a field spec for a component.

func FieldDeprecated 

func FieldDeprecated(name string, description ...string) FieldSpec

FieldDeprecated returns a field spec for a deprecated field.

func (FieldSpec) Array added in v3.43.0 

func (f FieldSpec) Array() FieldSpec

Array determines that this field is an array of the field type.

func (FieldSpec) AtVersion added in v3.34.0 

func (f FieldSpec) AtVersion(v string) FieldSpec

AtVersion specifies the version at which this fields behaviour was last modified.

func (FieldSpec) FlattenChildrenForDocs added in v3.47.0 

func (f FieldSpec) FlattenChildrenForDocs() FieldSpecs

FlattenChildrenForDocs converts the children of a field into a flat list, where the names contain hints as to their position in a structured hierarchy. This makes it easier to list the fields in documentation.

func (FieldSpec) HasAnnotatedOptions added in v3.33.0 

func (f FieldSpec) HasAnnotatedOptions(options ...string) FieldSpec

HasAnnotatedOptions returns a new FieldSpec that specifies a specific list of annotated options. Either

func (FieldSpec) HasDefault added in v3.28.0 

func (f FieldSpec) HasDefault(v interface{}) FieldSpec

HasDefault returns a new FieldSpec that specifies a default value.

func (FieldSpec) HasOptions 

func (f FieldSpec) HasOptions(options ...string) FieldSpec

HasOptions returns a new FieldSpec that specifies a specific list of options.

func (FieldSpec) HasType 

func (f FieldSpec) HasType(t FieldType) FieldSpec

HasType returns a new FieldSpec that specifies a specific type.

func (FieldSpec) IsInterpolated added in v3.43.0 

func (f FieldSpec) IsInterpolated() FieldSpec

IsInterpolated indicates that the field supports interpolation functions.

func (FieldSpec) LintOptions added in v3.47.0 

func (f FieldSpec) LintOptions() FieldSpec

LintOptions enforces that a field value matches one of the provided options and returns a linting error if that is not the case. This is currently opt-in because some fields express options that are only a subset due to deprecated functionality.

TODO: V4 Switch this to opt-out.

func (FieldSpec) Linter added in v3.43.0 

func (f FieldSpec) Linter(fn LintFunc) FieldSpec

Linter adds a linting function to a field. When linting is performed on a config the provided function will be called with a boxed variant of the field value, allowing it to perform linting on that value.

func (FieldSpec) Map added in v3.43.0 

func (f FieldSpec) Map() FieldSpec

Map determines that this field is a map of arbitrary keys to a field type.

func (FieldSpec) NodeToValue added in v3.47.0 

func (f FieldSpec) NodeToValue(node *yaml.Node) (interface{}, error)

NodeToValue converts a yaml node into a generic value by referencing the expected type.

func (FieldSpec) OmitWhen added in v3.43.0 

func (f FieldSpec) OmitWhen(fn func(field, parent interface{}) (string, bool)) FieldSpec

OmitWhen specifies a custom func that, when provided a generic config struct, returns a boolean indicating when the field can be safely omitted from a config.

func (FieldSpec) SanitiseNode added in v3.43.0 

func (f FieldSpec) SanitiseNode(node *yaml.Node, conf SanitiseConfig) error

SanitiseNode attempts to reduce a parsed config (as a *yaml.Node) down into a minimal representation without changing the behaviour of the config. The fields of the result will also be sorted according to the field spec.

func (FieldSpec) ToNode added in v3.47.0 

func (f FieldSpec) ToNode(recurse bool) (*yaml.Node, error)

ToNode creates a YAML node from a field spec. If a default value has been specified then it is used. Otherwise, a zero value is generated. If recurse is enabled and the field has children then all children will also have values generated.

func (FieldSpec) Unlinted added in v3.43.0 

func (f FieldSpec) Unlinted() FieldSpec

Unlinted returns a field spec that will not be lint checked during a config parse.

func (FieldSpec) WithChildren 

func (f FieldSpec) WithChildren(children ...FieldSpec) FieldSpec

WithChildren returns a new FieldSpec that has child fields.

type FieldSpecs 

type FieldSpecs []FieldSpec

FieldSpecs is a slice of field specs for a component.

func FieldsFromNode added in v3.47.0 

func FieldsFromNode(node *yaml.Node) FieldSpecs

FieldsFromNode walks the children of a YAML node and returns a list of fields extracted from it. This can be used in order to infer a field spec for a parsed component.

func (FieldSpecs) Add 

func (f FieldSpecs) Add(specs ...FieldSpec) FieldSpecs

Add more field specs.

func (FieldSpecs) LintNode added in v3.43.0 

func (f FieldSpecs) LintNode(ctx LintContext, node *yaml.Node) []Lint

LintNode walks a yaml node and returns a list of linting errors found.

func (FieldSpecs) Merge 

func (f FieldSpecs) Merge(specs FieldSpecs) FieldSpecs

Merge with another set of FieldSpecs.

func (FieldSpecs) NodeToMap added in v3.47.0 

func (f FieldSpecs) NodeToMap(node *yaml.Node) (map[string]interface{}, error)

NodeToMap converts a yaml node into a generic map structure by referencing expected fields, adding default values to the map when the node does not contain them.

func (FieldSpecs) SanitiseNode added in v3.43.0 

func (f FieldSpecs) SanitiseNode(node *yaml.Node, conf SanitiseConfig) error

SanitiseNode attempts to reduce a parsed config (as a *yaml.Node) down into a minimal representation without changing the behaviour of the config. The fields of the result will also be sorted according to the field spec.

func (FieldSpecs) ToNode added in v3.47.0 

func (f FieldSpecs) ToNode() (*yaml.Node, error)

ToNode creates a YAML node from a list of field specs. If a default value has been specified for a given field then it is used. Otherwise, a zero value is generated.

type FieldType added in v3.28.0 

type FieldType string

FieldType represents a field type. 

var (
	FieldString  FieldType = "string"
	FieldInt     FieldType = "int"
	FieldFloat   FieldType = "float"
	FieldBool    FieldType = "bool"
	FieldObject  FieldType = "object"
	FieldUnknown FieldType = "unknown"

	// Core component types, only components that can be a child of another
	// component config are listed here.
	FieldInput     FieldType = "input"
	FieldBuffer    FieldType = "buffer"
	FieldCache     FieldType = "cache"
	FieldCondition FieldType = "condition"
	FieldProcessor FieldType = "processor"
	FieldRateLimit FieldType = "rate_limit"
	FieldOutput    FieldType = "output"
	FieldMetrics   FieldType = "metrics"
	FieldTracer    FieldType = "tracer"
)

ValueType variants.

func (FieldType) IsCoreComponent added in v3.43.0 

func (t FieldType) IsCoreComponent() (Type, bool)

IsCoreComponent returns the core component type of a field if applicable.

type Lint added in v3.43.0 

type Lint struct {
	Line   int
	Column int // Optional, omitted from lint report unless >= 1
	Level  LintLevel
	What   string
}

Lint describes a single linting issue found with a Benthos config.

func LintBloblangField added in v3.43.0 

func LintBloblangField(ctx LintContext, line, col int, v interface{}) []Lint

LintBloblangField is function for linting a config field expected to be an interpolation string.

func LintBloblangMapping added in v3.43.0 

func LintBloblangMapping(ctx LintContext, line, col int, v interface{}) []Lint

LintBloblangMapping is function for linting a config field expected to be a bloblang mapping.

func LintNode added in v3.43.0 

func LintNode(ctx LintContext, cType Type, node *yaml.Node) []Lint

LintNode takes a yaml.Node and a config spec and returns a list of linting errors found in the config.

func NewLintError added in v3.43.0 

func NewLintError(line int, msg string) Lint

NewLintError returns an error lint.

func NewLintWarning added in v3.43.0 

func NewLintWarning(line int, msg string) Lint

NewLintWarning returns a warning lint.

type LintContext added in v3.43.0 

type LintContext struct {
	// A map of label names to the line they were defined at.
	Labels map[string]int
}

LintContext is provided to linting functions, and provides context about the wider configuration.

func NewLintContext added in v3.43.0 

func NewLintContext() LintContext

NewLintContext creates a new linting context.

type LintFunc added in v3.43.0 

type LintFunc func(ctx LintContext, line, col int, value interface{}) []Lint

LintFunc is a common linting function for field values.

type LintLevel added in v3.43.0 

type LintLevel int

LintLevel describes the severity level of a linting error. 

const (
	LintError   LintLevel = iota
	LintWarning LintLevel = iota
)

Lint levels

type SanitiseConfig added in v3.43.0 

type SanitiseConfig struct {
	RemoveTypeField  bool
	RemoveDeprecated bool
	ForExample       bool
	Filter           FieldFilter
}

SanitiseConfig contains fields describing the desired behaviour of the config sanitiser such as removing certain fields.

type Status added in v3.32.0 

type Status string

Status of a component. 

var (
	StatusStable       Status = "stable"
	StatusBeta         Status = "beta"
	StatusExperimental Status = "experimental"
	StatusDeprecated   Status = "deprecated"
)

Component statuses.

type Type added in v3.43.0 

type Type string

Type of a component. 

var (
	TypeBuffer    Type = "buffer"
	TypeCache     Type = "cache"
	TypeInput     Type = "input"
	TypeMetrics   Type = "metrics"
	TypeOutput    Type = "output"
	TypeProcessor Type = "processor"
	TypeRateLimit Type = "rate_limit"
	TypeTracer    Type = "tracer"
)

Component types.

func Types added in v3.43.0 

func Types() []Type

Types returns a slice containing all component types.

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.