Documentation ¶
Overview ¶
Package docs provides useful functions for creating documentation from Benthos components
Index ¶
- Variables
- func BloblangFunctionsMarkdown() ([]byte, error)
- func BloblangMethodsMarkdown() ([]byte, error)
- func RegisterDocs(spec ComponentSpec)
- func SanitiseComponentConfig(componentType Type, raw interface{}, filter FieldFilter) error
- func SanitiseNode(cType Type, node *yaml.Node, conf SanitiseConfig) error
- func ValidateLabel(label string) error
- type AnnotatedExample
- type ComponentSpec
- type FieldFilter
- type FieldSpec
- func (f FieldSpec) Array() FieldSpec
- func (f FieldSpec) AtVersion(v string) FieldSpec
- func (f FieldSpec) HasAnnotatedOptions(options ...string) FieldSpec
- func (f FieldSpec) HasDefault(v interface{}) FieldSpec
- func (f FieldSpec) HasOptions(options ...string) FieldSpec
- func (f FieldSpec) HasType(t FieldType) FieldSpec
- func (f FieldSpec) IsInterpolated() FieldSpec
- func (f FieldSpec) Linter(fn LintFunc) FieldSpec
- func (f FieldSpec) Map() FieldSpec
- func (f FieldSpec) OmitWhen(fn func(field, parent interface{}) (string, bool)) FieldSpec
- func (f FieldSpec) SanitiseNode(node *yaml.Node, conf SanitiseConfig) error
- func (f FieldSpec) Unlinted() FieldSpec
- func (f FieldSpec) WithChildren(children ...FieldSpec) FieldSpec
- type FieldSpecs
- type FieldType
- type Lint
- func LintBloblangField(ctx LintContext, line, col int, v interface{}) []Lint
- func LintBloblangMapping(ctx LintContext, line, col int, v interface{}) []Lint
- func LintNode(ctx LintContext, cType Type, node *yaml.Node) []Lint
- func NewLintError(line int, msg string) Lint
- func NewLintWarning(line int, msg string) Lint
- type LintContext
- type LintFunc
- type LintLevel
- type SanitiseConfig
- type Status
- type Type
Constants ¶
This section is empty.
Variables ¶
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
BloblangFunctionsMarkdown returns a markdown document for all Bloblang functions.
func BloblangMethodsMarkdown ¶ added in v3.26.0
BloblangMethodsMarkdown returns a markdown document for all Bloblang methods.
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.
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
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 // 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
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 // contains filtered or unexported fields }
FieldSpec describes a component config field.
func FieldAdvanced ¶
FieldAdvanced returns a field spec for an advanced field.
func FieldCommon ¶
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 ¶
FieldDeprecated returns a field spec for a deprecated field.
func (FieldSpec) Array ¶ added in v3.43.0
Array determines that this field is an array of the field type.
func (FieldSpec) AtVersion ¶ added in v3.34.0
AtVersion specifies the version at which this fields behaviour was last modified.
func (FieldSpec) HasAnnotatedOptions ¶ added in v3.33.0
HasAnnotatedOptions returns a new FieldSpec that specifies a specific list of annotated options. Either
func (FieldSpec) HasDefault ¶ added in v3.28.0
HasDefault returns a new FieldSpec that specifies a default value.
func (FieldSpec) HasOptions ¶
HasOptions returns a new FieldSpec that specifies a specific list of options.
func (FieldSpec) IsInterpolated ¶ added in v3.43.0
IsInterpolated indicates that the field supports interpolation functions.
func (FieldSpec) Linter ¶ added in v3.43.0
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
Map determines that this field is a map of arbitrary keys to a field type.
func (FieldSpec) OmitWhen ¶ added in v3.43.0
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) Unlinted ¶ added in v3.43.0
Unlinted returns a field spec that will not be lint checked during a config parse.
func (FieldSpec) WithChildren ¶
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 (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) 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.
type FieldType ¶ added in v3.28.0
type FieldType string
FieldType represents a field type.
var ( FieldString FieldType = "string" FieldNumber FieldType = "number" 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
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
NewLintError returns an error lint.
func NewLintWarning ¶ added in v3.43.0
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.
type SanitiseConfig ¶ added in v3.43.0
type SanitiseConfig struct { RemoveTypeField bool RemoveDeprecated bool Filter FieldFilter }
SanitiseConfig contains fields describing the desired behaviour of the config sanitiser such as removing certain fields.
type Type ¶ added in v3.43.0
type Type string
Type of a component.