PPA Tools: Text

Summary

This module contains actions used to process & search text.

Actions

ppa_tools.text.

append

Append one piece of text to the end of another.

Minimum Plugin Version: 5.9.0

Input

• base: the base text to append to

• new: the new text to append

Output

Text containing base with new appended to the end.

Example

- ppa_tools.text.append:
    base: London
    new: Paris
  save: new_copy

The output will be:

London
Paris

ppa_tools.text.

extract_lines

Extract a number of lines from some text.

Minimum Plugin Version: 5.9.0

Input

• text: the text to look in

• start_line: optional line number to start at (defaults to the first line)

• end_line: optional line number to finish on (defaults to extracting all text after start_line)

Line Numbers start at 0

Output

The text found between the start_line & end_line.

Example

- ppa_tools.text.extract_lines:
    text: >
      Line one
      Line two
      Line three
    start_line: 1
  save: extracted_lines

The output will be:

Line two
Line three

ppa_tools.text.

extract_values

Find & extract one or more named values from some text using regular expressions.

This action supports both single & multiple lines of text.

Minimum Plugin Version: 1.3.0

Regular Expressions

The following regex cheat-sheet & visualiser can help you get started with expressions.

Input

• values: a single or list of NamedGroup dictionaries

• text: the text to find & extract values from

Output

A list of dictionaries containing any matches found in the text.

Each dictionary's key is the name of the NamedGroup, & its value is the matching text.

Example

Finding all usernames from a failed SSH logon message & saving the matches as usernames.

- ppa_tools.text.extract_values:
    values:
      name: username
      expression: password for (.*) from
    text: >
      2020-08-11T08:19:40.463248+00:00 machine-name sshd[10349]: Failed password for user_1 from 1.2.3.4 port 58041 ssh2
      2020-08-12T13:24:07.463248+00:00 machine-name sshd[10349]: Failed password for user_2 from 2.3.4.5 port 58041 ssh2
  save: usernames

The contents of the new usernames variable will be:

- username: user_1
  username: user_2

ppa_tools.text.

get_line_number

Get the line number of the supplied line from some text.

Minimum Plugin Version: 5.9.0

Input

• text: the text to look in

• line: the line to look for

Line Numbers start at 0

Output

The line number (zero-based).

Example

Splitting on one or more new line characters:

- ppa_tools.text.get_line_number:
    text: >
      Line one
      Line two
      Line three
    line: Line two
  save: line_number

The output will be:

1

ppa_tools.text.

replace_lines

Replace a number of lines inside some text.

Minimum Plugin Version: 5.9.0

Input

• base: the text to perform the replacement on

• insert: some text to insert

• start_line: optional line number to start at (defaults to the first line)

• end_line: optional line number to finish on (defaults to extracting all text after start_line)

Line Numbers start at 0

Output

The text found between the start_line & end_line.

Example

- ppa_tools.text.replace_lines:
    base: |
      London
      Paris
      New York
      Brussels
      Manchester
    insert: |
      Bruges
      San Francisco
    start_line: 1
    end_line: 3
  save: replaced_text

The output will be:

London
Bruges
San Francisco
Brussels
Manchester

ppa_tools.text.

split_lines

Split a string into a list of strings based on new lines.

Minimum Plugin Version: 6.4.0

Input

• text: the string to split

• filter_empty: set to true to remove empty lines from the outputted list

Output

A list of strings.

Example

Splitting on one or more new line characters:

- ppa_tools.text.split_lines:
    text: >
      London
      Paris
      New York
save: split_output

The output will be:

- London
- Paris
- New York