KvOperator (Punch Punch Language Runtime Library 6.4.5 API)

java.lang.Object
- org.thales.punch.libraries.punchlang.operator.KvOperator

```
public class KvOperator
extends Object
```
Overview

The kv (key value) operator extracts key value sequences from a String. By default it uses the '=' to split keys from values, and spaces to delimit the key value pairs form each other.
In short it will work by default with input string likes this:
"name=bob age=22"
Here is an example of using the kv operator:
```
 kv().on("name=bob age=22").into([result]);
 
```
produces :
```
 
 "result": {
   "name": "bob",
   "age": "22"
  }
 
 
```
This operator is subtle and can accommodate complex patterns. In particular if you give something like
```
 
 "city=New Delhi country=India"
 
 
```
You will get:
```
 
 "result": {
   "country": "India",
   "city": "New Delhi"
 },
 
 
```
That is, the match of values does not stop after the first delimiter encountered, but at the last before the next key. You can change that using the left() method.
```
 kv().left().on("city=New Delhi country=India").into([result]);
 
```
```
 "result": {
   "country": "India",
   "city": "New"
 }
 
```
Also, '"' and ''' are taken care of.
```
 
 kv().on("city="New Dehli" message="this is a tricky message with = inside").into([result]);
 
 
```
```
 
 "result" : {
        "city" : "New Dehli" ,
        "message" : "this is a tricky message with = inside"
 }
 
 
```
Advanced Options

Make sure you are aware of the escapeJson(), inferTypes(), multiKeys() methods. Each provides a few advanced but useful capabilities.
Escaping
Consider the following three logs:
```
 name="hello" value=3"
 name="hello\" value=3"
 name="hello value=3
 
```
The second log is ambiguous: the second quote looks like it is escaped. But if it is, there is a missing quote and the kv operator should fail. The third log is clearly not correct. The kv strategy consists of accepting the second logs as long as there is a way to isolate each part. Internally a reverse scan is performed to automatically detect valid escaped regions.
That is the parsing of the second log will yield to
```
 
 "result" : {
        "name" : "hello\" ,
        "value" : 3
 }
 
 
```
Evaluate mode

Instead of performing a kv scan and store the result where you need it, you can use the kv operator to simply check that a string has some key value structure. That is useful for dynamically discovering log types.
The match(), combined with the hasKey(String) or hasKeyWithValue(String, String...) methods. lets you do that.
Here is an example:
```
 if (kv()
     .on([message])
     .hasKeyWithValue(\"vendor\", \"cisco\")
     .match()) {
         // this is a cisco log
 }
 
```

Field Summary

Fields
Modifier and Type Field and Description

protected static String REPLACEMENT
A replacement pattern to be used when escaping.

Fields
Modifier and Type	Field and Description
`protected static String`	`REPLACEMENT` A replacement pattern to be used when escaping.

Constructor Summary

Constructors
Constructor and Description
`KvOperator()` you can create a KvOperator on the fly, but it is less efficient than creating one at punchlet activation.
`KvOperator(String valueSplit, String fieldSplit)` you can create a Kv operator on the fly, but it is less efficient than creating one at punchlet activation.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`KvOperator`	`debug()` Make the operator print to standard output how the input string is processed.
`KvOperator`	`disableEscaping()` Disable the escaping that is performed as part of the key value conversion.
`KvOperator`	`enclosingDelim(String enclosing)` Change the enclosing character.
`KvOperator`	`escapeCharacter(char escapeCharacter)` Allows to escape enclosing delimiters.
`KvOperator`	`escapeJson()` Enable the escaping of json objects and arrays
`KvOperator`	`fieldSplit(String delimiter)` Reset the regex used to delimit key values from each others.
`KvOperator`	`hasKey(String key)` Make the operator work in evaluation mode.
`KvOperator`	`hasKeyWithValue(String key, String... value)` Make the operator work in evaluation mode.
`KvOperator`	`ignoreEmpty()` Keys with an empty value will not be put into the final Tuple.
`KvOperator`	`inferTypes()` Activate type inference.
`boolean`	`into(Tuple tuple)` Registers a tuple to hold the operator results.
`KvOperator`	`left()` Activate the left search behavior
`boolean`	`match()` This method evaluates many substrings before it gives up.
`KvOperator`	`multiKeys()` Enable a treatment with multiple keys by stacking them in an array
`KvOperator`	`on(String input)` Set the input data for running this operator.
`KvOperator`	`on(Tuple input)` Set the input data for running this operator.
`KvOperator`	`replaceAllKeys(String regex, String replacement)` Apply a replacement to all generated keys matching substrings.
`KvOperator`	`replaceAllKeyValues(String regex, String replacement)` Combines replaceAllValues(java.lang.String, java.lang.String) and replaceAllKeys(java.lang.String, java.lang.String).
`KvOperator`	`replaceAllValues(String regex, String replacement)` Apply a replacement to all generated keys matching substrings.
`static String`	`restore(String value, List<KvPortion> portions)` Input strings like "a=\"hello\" b=2" are transformed into "a=@PUNCH@ b=2 in the first escaping step.
`KvOperator`	`sanitize(String regex)` Sanitize the input string before being submitted to the operator.
`KvOperator`	`trim()` Trim the values, removing starting and trailing '"'
`KvOperator`	`valueSplit(String delimiter)` Reset the regex used to delimit key from values.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - REPLACEMENT
```
protected static final String REPLACEMENT
```
    A replacement pattern to be used when escaping.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - KvOperator
```
public KvOperator()
```
    you can create a KvOperator on the fly, but it is less efficient than creating one at punchlet activation. Prefer the other constructor.
  - KvOperator
```
public KvOperator(String valueSplit,
                  String fieldSplit)
```
    you can create a Kv operator on the fly, but it is less efficient than creating one at punchlet activation. Prefer the other constructor.
    
    Parameters:
    
    valueSplit - the regex used to delimit key from values
    
    fieldSplit - the regex used to delimit key value pairs from each other.
- Method Detail
  - debug
```
public KvOperator debug()
```
    Make the operator print to standard output how the input string is processed. Of course, do not use this in production.
    
    Returns:
    
    this operator
  - left
```
public KvOperator left()
```
    Activate the left search behavior
    
    Returns:
    
    this operator
  - disableEscaping
```
public KvOperator disableEscaping()
```
    Disable the escaping that is performed as part of the key value conversion.
    
    Returns:
    
    this operator
  - escapeJson
```
public KvOperator escapeJson()
```
    Enable the escaping of json objects and arrays
    
    Returns:
    
    this operator
  - ignoreEmpty
```
public KvOperator ignoreEmpty()
```
    Keys with an empty value will not be put into the final Tuple. For example, this input :
```
 a=b c= d=e
 
```
    will be returned as (without "c" key):
```
 { "a": "b", "d": "e" }
 
```
    Returns:
    
    this operator
  - multiKeys
```
public KvOperator multiKeys()
```
    Enable a treatment with multiple keys by stacking them in an array
```
 
   a="hello" a=2 b="world !" a=false
 
 will be converted to
 
   { "a": ["hello", 2, false], "b": "world !" }
 
 
```
    Returns:
    
    this operator
  - inferTypes
```
public KvOperator inferTypes()
```
    Activate type inference. Instead of generating Strings for all matches, the generated values will be booleans, longs, doubles or Strings.
    
    Returns:
    
    this operator
  - replaceAllKeys
```
public KvOperator replaceAllKeys(String regex,
                                 String replacement)
```
    Apply a replacement to all generated keys matching substrings.
    For example if you have
```
 
        Tuple result;
        kv().replaceAllKeys(" ", "").on("a b"=3 "a c"="hello world").into(result);
  
 
```
    You will get result as follows
```
 
    { "ab"=3, "ac"="hello world" }
  
 
```
    Parameters:
    
    regex - the regex for matching substrings
    
    replacement - the replacement string
    
    Returns:
    
    this operator
  - replaceAllValues
```
public KvOperator replaceAllValues(String regex,
                                   String replacement)
```
    Apply a replacement to all generated keys matching substrings.
    For example if you have
```
 
        Tuple result;
        kv().replaceAllValues(" ", "").on("a b"=3 "a c"="hello world").into(result);
  
 
```
    You will get result as follows
```
 
    { "a b"=3, "a c"="hello world" }
  
 
```
    Parameters:
    
    regex - the regex to match key substrings to replace
    
    replacement - the replacement string
    
    Returns:
    
    this operator
  - replaceAllKeyValues
```
public KvOperator replaceAllKeyValues(String regex,
                                      String replacement)
```
    Combines replaceAllValues(java.lang.String, java.lang.String) and replaceAllKeys(java.lang.String, java.lang.String).
    
    Parameters:
    
    regex - the regex for matching substrings
    
    replacement - the replacement string
    
    Returns:
    
    this operator
  - valueSplit
```
public KvOperator valueSplit(String delimiter)
```
    Reset the regex used to delimit key from values. A string of characters to use as delimiters for identifying key-value relations.
    I.e. if you have "a==10 b==11', you should use. Remember punch uses java syntax, you must escape your special characters. I.e "\\s" instead of "\s".
```
        kv().valueSplit("==")...
 
```
    Parameters:
    
    delimiter - the new delimiter, it must be a valid regex.
    
    Returns:
    
    this operator
  - sanitize
```
public KvOperator sanitize(String regex)
```
    Sanitize the input string before being submitted to the operator. This method prepare the data in order to be correctly separated into key value. The regex passed as argument is used to consider all characters surrounded by that regex un-splittable. For example:
```
 
 kv().on("a='1 b=2'").sanitize("'").into([kv]);
 // kv is { "a" : "1 b=2" }
 
 
```
    By default, only double quote are considered. That is, the two following statement :
```
 
 kv().on([message]).sanitize("\"").into([kv]);
 
 
```
    is equivalent to :
```
 
 kv().on([message]).into([kv]);
 
 
```
    Parameters:
    
    regex - the regex used to match delimiter
    
    Returns:
    
    this operator
  - trim
```
public KvOperator trim()
```
    Trim the values, removing starting and trailing '"'
    
    Returns:
    
    this operator
  - fieldSplit
```
public KvOperator fieldSplit(String delimiter)
```
    Reset the regex used to delimit key values from each others.
    I.e. if you have "a=10;b=11', you should use.
```
 
        kv().fieldSplit(";")...
 
 
```
    Remember punch uses java syntax, you must escape your special characters. I.e "\\s" instead of "\s".
    Parameters:
    
    delimiter - the new delimiter, it must be a valid regex.
    
    Returns:
    
    this operator
  - enclosingDelim
```
public KvOperator enclosingDelim(String enclosing)
```
    Change the enclosing character. By default, '"'. This character is used to unescape the value should they contain the delimiter. For example :
```
 
   a="hello" b="world !"
 
 
```
    Parameters:
    
    enclosing - the new enclosing character
    
    Returns:
    
    this operator
  - escapeCharacter
```
public KvOperator escapeCharacter(char escapeCharacter)
```
    Allows to escape enclosing delimiters. If an enclosing delimiter is preceded by this escapeCharacter, no quote is created or closed.
    
    Parameters:
    
    escapeCharacter - Character to use.
    
    Returns:
    
    this operator
  - on
```
public KvOperator on(String input)
```
    Set the input data for running this operator.
    
    Parameters:
    
    input - the data as a String.
    
    Returns:
    
    this operator.
  - on
```
public KvOperator on(Tuple input)
```
    Set the input data for running this operator.
    
    Parameters:
    
    input - the data as a Tuple.
    
    Returns:
    
    this operator.
  - hasKeyWithValue
```
public KvOperator hasKeyWithValue(String key,
                                  String... value)
```
    Make the operator work in evaluation mode. This is slow but useful to check if a log is a kv log and has a key that match one or several values.
    
    Parameters:
    
    key - the key you look for
    
    value - the value(s) you want to match.
    
    Returns:
    
    this operator
  - hasKey
```
public KvOperator hasKey(String key)
```
    Make the operator work in evaluation mode. This is slow but useful to check if a log is a kv log and has a given key.
    
    Parameters:
    
    key - the key you look for
    
    Returns:
    
    this operator
  - match
```
public boolean match()
```
    This method evaluates many substrings before it gives up. Never runs in production or only once combined with a sticky strategy.
    Use in conjunction with hasKey(String) or hasKeyWithValue(String, String...) methods.
    
    Returns:
    
    true if one of your criterion matched
  - into
```
public boolean into(Tuple tuple)
```
    Registers a tuple to hold the operator results.
    
    Parameters:
    
    tuple - the tuple for holding result
    
    Returns:
    
    true if the operator succeeded to extract some key-value pair(s)
  - restore
```
public static String restore(String value,
                             List<KvPortion> portions)
```
    Input strings like "a=\"hello\" b=2" are transformed into "a=@PUNCH@ b=2 in the first escaping step. That makes it easier to detect all key=value pair without be fooled by inner '=' character that would occur in values.
    Now it is time to restore the original value from the provided portions.
    
    Parameters:
    
    value - the provided value, possibly equal to or containing the "@PUNCH@" replacement string.
    
    portions - the list of portions computed in the previous step.
    
    Returns:
    
    the restored String value

Class KvOperator

Overview

Advanced Options

Escaping

Evaluate mode

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

REPLACEMENT

Constructor Detail

KvOperator

KvOperator

Method Detail

debug

left

disableEscaping

escapeJson

ignoreEmpty

multiKeys

inferTypes

replaceAllKeys

replaceAllValues

replaceAllKeyValues

valueSplit

sanitize

trim

fieldSplit

enclosingDelim

escapeCharacter

on

on

hasKeyWithValue

hasKey

match

into

restore