From 29eed25df71d98e6a2c31f5018432e8c523986e8 Mon Sep 17 00:00:00 2001 From: urso Date: Wed, 5 Feb 2020 19:07:10 +0100 Subject: [PATCH] re-export symbols and add godoc --- libbeat/outputs/outil/select.go | 74 +++++++++++++++++++++------------ 1 file changed, 47 insertions(+), 27 deletions(-) diff --git a/libbeat/outputs/outil/select.go b/libbeat/outputs/outil/select.go index 6ad0ef515dd9..d06ee4e32091 100644 --- a/libbeat/outputs/outil/select.go +++ b/libbeat/outputs/outil/select.go @@ -27,10 +27,14 @@ import ( "github.com/elastic/beats/libbeat/conditions" ) +// Selector is used to produce a string based on the contents of a Beats event. +// A selector supports multiple rules that need to be configured. type Selector struct { - sel selectorExpr + sel SelectorExpr } +// Settings configures how BuildSelectorFromConfig creates a Selector from +// a given configuration object. type Settings struct { // single selector key and default option keyword Key string @@ -45,18 +49,20 @@ type Settings struct { FailEmpty bool } -type selectorExpr interface { +// SelectorExpr represents an expression object that can be composed with other +// expressions in order to build a Selector. +type SelectorExpr interface { sel(evt *beat.Event) (string, error) } type emptySelector struct{} type listSelector struct { - selectors []selectorExpr + selectors []SelectorExpr } type condSelector struct { - s selectorExpr + s SelectorExpr cond conditions.Condition } @@ -70,21 +76,22 @@ type fmtSelector struct { } type mapSelector struct { - from selectorExpr + from SelectorExpr otherwise string to map[string]string } -var nilSelector selectorExpr = &emptySelector{} +var nilSelector SelectorExpr = &emptySelector{} -func MakeSelector(es ...selectorExpr) Selector { +// MakeSelector creates a selector from a set of selector expressions. +func MakeSelector(es ...SelectorExpr) Selector { switch len(es) { case 0: return Selector{nilSelector} case 1: return Selector{es[0]} default: - return Selector{concatSelectorExpr(es...)} + return Selector{ConcatSelectorExpr(es...)} } } @@ -96,10 +103,12 @@ func (s Selector) Select(evt *beat.Event) (string, error) { return s.sel.sel(evt) } +// IsEmpty checks if the selector is not configured and will always return an empty string. func (s Selector) IsEmpty() bool { return s.sel == nilSelector || s.sel == nil } +// IsConst checks if the selector will always return the same string. func (s Selector) IsConst() bool { if s.sel == nilSelector { return true @@ -109,11 +118,12 @@ func (s Selector) IsConst() bool { return ok } +// BuildSelectorFromConfig creates a selector from a configuration object. func BuildSelectorFromConfig( cfg *common.Config, settings Settings, ) (Selector, error) { - var sel []selectorExpr + var sel []SelectorExpr key := settings.Key multiKey := settings.MultiKey @@ -157,7 +167,7 @@ func BuildSelectorFromConfig( return Selector{}, fmt.Errorf("%v in %v", err, cfg.PathOf(key)) } - fmtsel, err := fmtSelectorExpr(fmtstr, "") + fmtsel, err := FmtSelectorExpr(fmtstr, "") if err != nil { return Selector{}, fmt.Errorf("%v in %v", err, cfg.PathOf(key)) } @@ -180,18 +190,22 @@ func BuildSelectorFromConfig( return MakeSelector(sel...), nil } -func emptySelectorExpr() selectorExpr { +// EmptySelectorExpr create a selector expression that returns an empty string. +func EmptySelectorExpr() SelectorExpr { return nilSelector } -func constSelectorExpr(s string) selectorExpr { +// ConstSelectorExpr creates a selector expression that always returns the configured string. +func ConstSelectorExpr(s string) SelectorExpr { if s == "" { - return emptySelectorExpr() + return EmptySelectorExpr() } return &constSelector{strings.ToLower(s)} } -func fmtSelectorExpr(fmt *fmtstr.EventFormatString, fallback string) (selectorExpr, error) { +// FmtSelectorExpr creates a selector expression using a format string. If the +// event can not be applied the default fallback constant string will be returned. +func FmtSelectorExpr(fmt *fmtstr.EventFormatString, fallback string) (SelectorExpr, error) { if fmt.IsConst() { str, err := fmt.Run(nil) if err != nil { @@ -200,28 +214,34 @@ func fmtSelectorExpr(fmt *fmtstr.EventFormatString, fallback string) (selectorEx if str == "" { str = fallback } - return constSelectorExpr(str), nil + return ConstSelectorExpr(str), nil } return &fmtSelector{*fmt, strings.ToLower(fallback)}, nil } -func concatSelectorExpr(s ...selectorExpr) selectorExpr { +// ConcatSelectorExpr combines multiple expressions that are run one after the other. +// The first expression that returns a string wins. +func ConcatSelectorExpr(s ...SelectorExpr) SelectorExpr { return &listSelector{s} } -func conditionalSelectorExpr( - s selectorExpr, +// ConditionalSelectorExpr executes the given expression only if the event +// matches the given condition. +func ConditionalSelectorExpr( + s SelectorExpr, cond conditions.Condition, -) selectorExpr { +) SelectorExpr { return &condSelector{s, cond} } -func lookupSelectorExpr( +// LookupSelectorExpr replaces the produced string with an table entry. +// If there is no entry in the table the default fallback string will be reported. +func LookupSelectorExpr( evtfmt *fmtstr.EventFormatString, table map[string]string, fallback string, -) (selectorExpr, error) { +) (SelectorExpr, error) { if evtfmt.IsConst() { str, err := evtfmt.Run(nil) if err != nil { @@ -232,7 +252,7 @@ func lookupSelectorExpr( if str == "" { str = fallback } - return constSelectorExpr(str), nil + return ConstSelectorExpr(str), nil } return &mapSelector{ @@ -250,7 +270,7 @@ func lowercaseTable(table map[string]string) map[string]string { return tmp } -func buildSingle(cfg *common.Config, key string) (selectorExpr, error) { +func buildSingle(cfg *common.Config, key string) (SelectorExpr, error) { // TODO: check for unknown fields // 1. extract required key-word handler @@ -310,18 +330,18 @@ func buildSingle(cfg *common.Config, key string) (selectorExpr, error) { } // 5. build selector from available fields - var sel selectorExpr + var sel SelectorExpr if len(mapping.Table) > 0 { - sel, err = lookupSelectorExpr(evtfmt, lowercaseTable(mapping.Table), otherwise) + sel, err = LookupSelectorExpr(evtfmt, lowercaseTable(mapping.Table), otherwise) } else { - sel, err = fmtSelectorExpr(evtfmt, otherwise) + sel, err = FmtSelectorExpr(evtfmt, otherwise) } if err != nil { return nil, err } if cond != nil && sel != nilSelector { - sel = conditionalSelectorExpr(sel, cond) + sel = ConditionalSelectorExpr(sel, cond) } return sel, nil