/ 
File-KDBX-0.800
River stage one • 1 direct dependent • 2 total dependents
/ File::KDBX::Group

NAME

File::KDBX::Group - A KDBX database group

VERSION

version 0.800

DESCRIPTION

A group in a KDBX database is a type of object that can contain entries and other groups.

There is also some metadata associated with a group. Each group in a database is identified uniquely by a UUID. An entry can also have an icon associated with it, and there are various timestamps. Take a look at the attributes to see what's available.

ATTRIBUTES

uuid

128-bit UUID identifying the group within the database.

name

The human-readable name of the group.

notes

Free form text string associated with the group.

tags

Text string with arbitrary tags which can be used to build a taxonomy.

icon_id

Integer representing a default icon. See ":icon" in File::KDBX::Constants for valid values.

custom_icon_uuid

128-bit UUID identifying a custom icon within the database.

is_expanded

Whether or not subgroups are visible when listed for user selection.

default_auto_type_sequence

The default auto-type keystroke sequence, inheritable by entries and subgroups.

enable_auto_type

Whether or not the entry is eligible to be matched for auto-typing, inheritable by entries and subgroups.

enable_searching

Whether or not entries within the group can show up in search results, inheritable by subgroups.

last_top_visible_entry

The UUID of the entry visible at the top of the list.

custom_data

A set of key-value pairs used to store arbitrary data, usually used by software to keep track of state rather than by end users (who typically work with the strings and binaries).

previous_parent_group

128-bit UUID identifying a group within the database.

entries

Array of entries contained within the group.

groups

Array of subgroups contained within the group.

last_modification_time

Date and time when the entry was last modified.

creation_time

Date and time when the entry was created.

last_access_time

Date and time when the entry was last accessed.

expiry_time

Date and time when the entry expired or will expire.

expires

Boolean value indicating whether or not an entry is expired.

usage_count

TODO

location_changed

Date and time when the entry was last moved to a different parent group.

METHODS

entries

\@entries = $group->entries;

Get an array of direct entries within a group.

entries_deeply

\&iterator = $kdbx->entries_deeply(%options);

Get an File::KDBX::Iterator over entries within a group. Supports the same options as "groups", plus some new ones:

  • auto_type - Only include entries with auto-type enabled (default: false, include all)

  • searching - Only include entries within groups with searching enabled (default: false, include all)

  • history - Also include historical entries (default: false, include only current entries)

add_entry

$entry = $group->add_entry($entry);
$entry = $group->add_entry(%entry_attributes);

Add an entry to a group. If $entry already has a parent group, it will be removed from that group before being added to $group.

remove_entry

$entry = $group->remove_entry($entry);
$entry = $group->remove_entry($entry_uuid);

Remove an entry from a group's array of entries. Returns the entry removed or undef if nothing removed.

groups

\@groups = $group->groups;

Get an array of direct subgroups within a group.

groups_deeply

\&iterator = $group->groups_deeply(%options);

Get an File::KDBX::Iterator over groups within a groups, deeply. Options:

  • inclusive - Include $group itself in the results (default: true)

  • algorithm - Search algorithm, one of ids, bfs or dfs (default: ids)

add_group

$new_group = $group->add_group($new_group);
$new_group = $group->add_group(%group_attributes);

Add a group to a group. If $new_group already has a parent group, it will be removed from that group before being added to $group.

remove_group

$removed_group = $group->remove_group($group);
$removed_group = $group->remove_group($group_uuid);

Remove a group from a group's array of subgroups. Returns the group removed or undef if nothing removed.

objects_deeply

\&iterator = $groups->objects_deeply(%options);

Get an File::KDBX::Iterator over objects within a group, deeply. Groups and entries are considered objects, so this is essentially a combination of "groups" and "entries". This won't often be useful, but it can be convenient for maintenance tasks. This method takes the same options as "groups" and "entries".

add_object

$new_entry = $group->add_object($new_entry);
$new_group = $group->add_object($new_group);

Add an object (either a File::KDBX::Entry or a File::KDBX::Group) to a group. This is the generic equivalent of the object forms of "add_entry" and "add_group".

remove_object

$group->remove_object($entry);
$group->remove_object($group);

Remove an object (either a File::KDBX::Entry or a File::KDBX::Group) from a group. This is the generic equivalent of the object forms of "remove_entry" and "remove_group".

effective_default_auto_type_sequence

$text = $group->effective_default_auto_type_sequence;

Get the value of "default_auto_type_sequence", if set, or get the inherited effective default auto-type sequence of the parent.

effective_enable_auto_type

$text = $group->effective_enable_auto_type;

Get the value of "enable_auto_type", if set, or get the inherited effective auto-type enabled value of the parent.

effective_enable_searching

$text = $group->effective_enable_searching;

Get the value of "enable_searching", if set, or get the inherited effective searching enabled value of the parent.

is_empty

$bool = $group->is_empty;

Get whether or not the group is empty (has no subgroups or entries).

is_root

$bool = $group->is_root;

Determine if a group is the root group of its connected database.

is_recycle_bin

$bool = $group->is_recycle_bin;

Get whether or not a group is the recycle bin of its connected database.

is_entry_templates

$bool = $group->is_entry_templates;

Get whether or not a group is the group containing entry template of its connected database.

is_last_selected

$bool = $group->is_last_selected;

Get whether or not a group is the prior selected group of its connected database.

is_last_top_visible

$bool = $group->is_last_top_visible;

Get whether or not a group is the latest top visible group of its connected database.

path

$string = $group->path;

Get a string representation of a group's lineage. This is used as the substitution value for the {GROUP_PATH} placeholder. See "Placeholders" in File::KDBX::Entry.

For a root group, the path is simply the name of the group. For deeper groups, the path is a period-separated sequence of group names between the root group and $group, including $group but not the root group. In other words, paths of deeper groups leave the root group name out.

Database
-> Root         # path is "Root"
   -> Foo       # path is "Foo"
      -> Bar    # path is "Foo.Bar"

Yeah, it doesn't make much sense to me, either, but this matches the behavior of KeePass.

size

$size = $group->size;

Get the size (in bytes) of a group, including the size of all subroups and entries, if any.

depth

$depth = $group->depth;

Get the depth of a group within a database. The root group is at depth 0, its direct children are at depth 1, etc. A group not in a database tree structure returns a depth of -1.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/chazmcgarvey/File-KDBX/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHOR

Charles McGarvey <ccm@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2022 by Charles McGarvey.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.