Skip to content

PPA Tools PPA Tools: Lists

Summary

This module contains actions used to process lists.

Actions

ppa_tools.lists.

append

Append an item to a list.

Minimum Plugin Version: 3.1.0

Input

  • items: the list to append the new value to

  • value: the value to append to items

Output

The updated list.

Example

Appending an integer to a list.

1
2
3
4
5
6
- ppa_tools.lists.append:
    items:
      - 1
      - 2
    value: 3
  save: numbers

The numbers variable will be:

1
2
3
- 1
- 2
- 3

ppa_tools.lists.

combine

Combine two lists into one.

Minimum Plugin Version: 3.5.0

Input

  • first: the first list

  • second: the second list

Output

A new list containing first & second.

Example

Combining two lists of numbers:

1
2
3
4
5
6
7
8
- ppa_tools.lists.combine:
    first:
      - 1
      - 2
    second:
      - 3
      - 4
  save: new_list

In this example the new_list variable will be:

1
2
3
4
- 1
- 2
- 3
- 4

ppa_tools.lists.

common

Compare two lists and get all items present in both.

Minimum Plugin Version: 3.5.0

Input

  • first: the first list

  • second: the second list

Output

A new list containing all items present in both first and second.

Example

Getting the common items from two lists of numbers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- ppa_tools.lists.common:
    first:
      - 1
      - 2
      - 3
      - 4
      - 5
    second:
      - 3
      - 4
      - 5
      - 6
      - 7
  save: new_list

In this example the new_list variable will be:

1
2
3
- 3
- 4
- 5

ppa_tools.lists.

count

Count how many times the supplied value exists in the supplied list.

Minimum Plugin Version: 8.8.0

Input

  • items: a list of values

  • value: the value to count

Output

A number.

Example

In this example the count variable will be 2.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- ppa_tools.lists.count:
    items:
      - 1
      - 2
      - 2
      - 3
      - 3
      - 4
      - 5
    value: 2
  save: count

ppa_tools.lists.

difference

Compare two lists and get all items only present in the first.

Minimum Plugin Version: 5.5.0

Input

  • first: the first list

  • second: the second list

  • key: optional key to use in comparison checks if both lists are dictionaries

Output

A new list containing all items from first that are not present in second.

Example 1 - Lists of Numbers

Getting the difference between two lists of numbers:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- ppa_tools.lists.difference:
    first:
      - 1
      - 2
      - 3
    second:
      - 3
      - 4
      - 5
  save: new_list

In this example the new_list variable will be:

- 1
- 2
Example 2 - Lists of Dictionaries

  • Getting the difference between two lists of Active Directory users

  • Each user's sAMAccountName is used to check for existence

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
- active_directory.groups.get_users:
    distinguishedName: CN=Remote Desktop Users,CN=Builtin,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: remote_desktop_users

- active_directory.groups.get_users:
    distinguishedName: CN=Backup Operators,CN=Builtin,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: backup_operators

- ppa_tools.lists.difference:
    key: sAMAccountName
  load:
    first: backup_operators
    second: remote_desktop_users
  save: backup_operators_only

ppa_tools.lists.

filter

Filter items from a list that match the supplied value.

Minimum Plugin Version: 6.3.0

Input

  • items: the list of values to filter

  • value: the value to filter from the list

Output

A new list with all occurrences of value removed.

Example

Filtering out null values from a list:

1
2
3
4
5
6
7
- ppa_tools.lists.filter:
    items:
      - null
      - 1
      - 2
    value: null
  save: filtered_list

In this example the filtered_list variable will be:

1
2
- 1
- 2

ppa_tools.lists.

flatten

Flattens a list of lists into a single list.

Minimum Plugin Version: 8.4.0

Input
  • items: a list of lists
Output

A single list containing all the values from each list in items.

Example
1
2
3
4
5
6
7
8
- ppa_tools.lists.get_items:
    items:
      - - Paris
      - - London
      - - Cardiff
      - - Berlin
      - - Brussels
  save: cities

The cities variable will be a list containing:

- Paris
- London
- Cardiff
- Berlin
- Brussels

ppa_tools.lists.

get_first_item

Get the first item from a list.

Minimum Plugin Version: 3.0.0

Input
  • items: a list of values
Output

The value at position 0 in the items list.

Example

Getting the first item from a list of cities.

1
2
3
4
5
6
7
8
- ppa_tools.lists.get_first_item:
    items:
      - Paris
      - London
      - Cardiff
      - Berlin
      - Brussels
  save: first_city

The first_city variable will be a string containing "Paris".

ppa_tools.lists.

get_item

Get an item from a list using an index.

Minimum Plugin Version: 3.0.0

List Indexing

Values from a list are accessed using their position in the list (index).

PPA lists are zero-indexed, meaning the first item is always at position 0.

Input

  • items: a list of values

  • index: the index of the item to get

Output

The value at position index in the items list.

Example

Getting the first item from a list of cities.

1
2
3
4
5
6
7
8
9
- ppa_tools.lists.get_item:
    items:
      - Paris
      - London
      - Cardiff
      - Berlin
      - Brussels
    index: 0
  save: selected_city

The selected_city variable will be a string containing "Paris".

ppa_tools.lists.

get_items

Get items from a list using a list of indices.

Minimum Plugin Version: 3.0.0

List Indexing

Values from a list are accessed using their position in the list (index).

PPA lists are zero-indexed, meaning the first item is always at position 0.

Input

  • items: a list of values

  • indices: a list of indices for the items to get

Output

A list of items taken from items at the positions supplied in indices.

Example

Getting indices 1 & 3 from a list of cities.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- ppa_tools.lists.get_items:
    items:
      - Paris
      - London
      - Cardiff
      - Berlin
      - Brussels
    indices:
      - 1
      - 3
  save: selected_cities

The selected_cities variable will be a list containing:

- London
- Berlin

ppa_tools.lists.

slice

Get a portion of the supplied list using start & end indices.

Minimum Plugin Version: 8.7.0

Input

  • items: a list of values

  • start: the start index

  • end: the end index

List indices start at 0!
The values at start & end will be included in the outputted list.
Output

A new list with the values from items between the start & end indices.

If end is higher then the length of list, no end index will be applied.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- ppa_tools.lists.slice:
    items:
      - Paris
      - London  # Index 1 (included)
      - Cardiff
      - Berlin  # Index 3 (included)
      - Brussels
    start: 1
    end: 3
  save: cities

The cities variable will be a list containing:

- London
- Cardiff
- Berlin

ppa_tools.lists.

sort

Sort a list alphanumerically.

Minimum Plugin Version: 3.7.0

Input

  • items: the list to sort

  • reverse: set to true to sort in reverse (defaults to false)

Value Types

In order to sort a list, all the items must be of the same type.

Lists that contain null values cannot be sorted.

Output

A new sorted list.

Example

Sorting a list of numbers:

1
2
3
4
5
6
7
8
- ppa_tools.lists.sort:
    items:
      - 5
      - 4
      - 3
      - 2
      - 1
  save: sorted_list

In this example the sorted_list variable will be:

1
2
3
4
5
- 1
- 2
- 3
- 4
- 5

ppa_tools.lists.

unique

Get a list of unique values from the supplied list.

This action can be used to remove duplicate values from a list.

Minimum Plugin Version: 3.5.0

Input
  • items: a list of values
Supported Values

This action will fail if the list contains a dictionary value.

Output

A new list containing all unique values from items.

Example
1
2
3
4
5
6
7
8
9
- ppa_tools.lists.unique:
    items:
      - 1
      - 1
      - 2
      - 3
      - 3
      - 3
  save: unique_values

In this example the unique_values variable will be:

1
2
3
- 1
- 2
- 3