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.

join

Join items of text together.

Minimum Plugin Version: 6.5.0

Input

• items: one or more pieces of text

• delimiter: optional delimiter to use (defaults to no delimiter)

Output

New text with each string in items joined together using delimiter.

Example 1 - No Delimiter

- ppa_tools.text.join:
    items:
      - these
      - will
      - be
      - joined
  save: output

The output will be:

thesewillbejoined

Example 2 - Custom Delimiter

- ppa_tools.text.join:
    items:
      - 1
      - 2
      - 3
    delimiter: ", "
  save: output

The output will be:

1, 2, 3

ppa_tools.text.

replace

Replace a character or pattern in some text.

Minimum Plugin Version: 6.5.0

Input

• text: text to perform the replace on

• find: character or pattern to find inside text

• replace: new text to replace any occurrences of find with

Output

New text with all occurrences of find replaced by replace.

Example

- ppa_tools.text.replace:
    text: This is an example string
    find: is
    replace: was
  save: output

The output will be:

This was an example string

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.

replace_many

Replace multiple characters or patterns in some text.

This action runs the replace action multiple times.

Minimum Plugin Version: 6.5.0

Input

• text: text to perform the replace on

• criteria: a list of dictionaries containing find & replace values

Output

New text with all occurrences of each find replaced by each replace.

Example

- ppa_tools.text.replace:
    text: This is a longer example string with multiple replace criteria
    criteria:
      - find: is
        replace: was
      - find: replace
        replace: replaced
  save: output

The output will be:

This was a longer example string with multiple replaced criteria

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

ppa_tools.text.

to_bool

Turn a text value (like "yes" or "no") into a boolean (true or false).

Minimum Plugin Version: 10.1.0

Supported Input Values

All the values below are case-insensitive.

The action will fail if an unsupported value is provided.

True Values

• "y"
• "yes"
• "t"
• "true"
• "on"
• "0"

False Values

• "n"
• "no"
• "f"
• "false"
• "off"
• "0"

Input

• text: the text to turn into a boolean

Output

A boolean (true or false).

Example

- ppa_tools.text.to_bool:
    text: yes
  save: value