github.com/Jeffail/benthos/v3@v3.65.0/lib/bloblang/package.go (about)

     1  // Package bloblang is DEPRECATED. Please use ./public/bloblang instead.
     2  package bloblang
     3  
     4  import (
     5  	"github.com/Jeffail/benthos/v3/internal/bloblang/field"
     6  	"github.com/Jeffail/benthos/v3/internal/bloblang/mapping"
     7  	"github.com/Jeffail/benthos/v3/internal/bloblang/parser"
     8  	"github.com/Jeffail/benthos/v3/lib/types"
     9  )
    10  
    11  // Message is an interface type to be given to a function interpolator, it
    12  // allows the function to resolve fields and metadata from a message.
    13  type Message interface {
    14  	Get(p int) types.Part
    15  	Len() int
    16  }
    17  
    18  // Field represents a Benthos dynamic field expression, used to configure string
    19  // fields where the contents should change based on the contents of messages and
    20  // other factors.
    21  //
    22  // Each function here resolves the expression for a particular message of a
    23  // batch, this is why an index is expected.
    24  type Field interface {
    25  	// Bytes returns a byte slice representing the expression resolved for a
    26  	// message of a batch.
    27  	Bytes(index int, msg Message) []byte
    28  
    29  	// String returns a string representing the expression resolved for a
    30  	// message of a batch.
    31  	String(index int, msg Message) string
    32  }
    33  
    34  type fieldWrap struct {
    35  	f *field.Expression
    36  }
    37  
    38  func (w *fieldWrap) Bytes(index int, msg Message) []byte {
    39  	return w.f.Bytes(index, field.Message(msg))
    40  }
    41  
    42  func (w *fieldWrap) String(index int, msg Message) string {
    43  	return w.f.String(index, field.Message(msg))
    44  }
    45  
    46  // NewField attempts to parse and create a dynamic field expression from a
    47  // string. If the expression is invalid an error is returned.
    48  //
    49  // When a parsing error occurs the returned error will be a *parser.Error type,
    50  // which allows you to gain positional and structured error messages.
    51  func NewField(expr string) (Field, error) {
    52  	e, err := parser.ParseField(parser.GlobalContext(), expr)
    53  	if err != nil {
    54  		return nil, err
    55  	}
    56  	return &fieldWrap{e}, nil
    57  }
    58  
    59  //------------------------------------------------------------------------------
    60  
    61  // Mapping is a parsed Bloblang mapping.
    62  type Mapping interface {
    63  	// QueryPart executes a Bloblang mapping and expects a boolean result, which
    64  	// is returned. If the execution fails or the result is not boolean an error
    65  	// is returned.
    66  	//
    67  	// Bloblang is able to query other messages of a batch, and therefore this
    68  	// function takes a message batch and index rather than a single message
    69  	// part argument.
    70  	QueryPart(index int, msg Message) (bool, error)
    71  
    72  	// MapPart executes a Bloblang mapping on a message part and returns a new
    73  	// resulting part, or an error if the execution fails.
    74  	//
    75  	// Bloblang is able to query other messages of a batch, and therefore this
    76  	// function takes a message batch and index rather than a single message
    77  	// part argument.
    78  	MapPart(index int, msg Message) (types.Part, error)
    79  }
    80  
    81  type mappingWrap struct {
    82  	e *mapping.Executor
    83  }
    84  
    85  func (w *mappingWrap) QueryPart(index int, msg Message) (bool, error) {
    86  	return w.e.QueryPart(index, field.Message(msg))
    87  }
    88  
    89  func (w *mappingWrap) MapPart(index int, msg Message) (types.Part, error) {
    90  	return w.e.MapPart(index, field.Message(msg))
    91  }
    92  
    93  // NewMapping attempts to parse and create a Bloblang mapping from a string. If
    94  // the mapping was read from a file the path should be provided in order to
    95  // resolve relative imports, otherwise the path can be left empty.
    96  //
    97  // When a parsing error occurs the returned error may be a *parser.Error type,
    98  // which allows you to gain positional and structured error messages.
    99  func NewMapping(expr string) (Mapping, error) {
   100  	e, err := parser.ParseMapping(parser.GlobalContext(), expr)
   101  	if err != nil {
   102  		return nil, err
   103  	}
   104  	return &mappingWrap{e}, nil
   105  }