NAME

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

VERSION

version 0.906

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.

A File::KDBX::Group is a subclass of File::KDBX::Object. View its documentation to see other attributes and methods available on groups.

ATTRIBUTES

name

The human-readable name of the group.

notes

Free form text string associated with the group.

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.

entries

Array of entries contained within the group.

groups

Array of subgroups contained within the group.

METHODS

entries

    \@entries = $group->entries;

Get an array of direct child entries within a group.

all_entries

    \&iterator = $kdbx->all_entries(%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.

all_groups

    \&iterator = $group->all_groups(%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.

all_objects

    \&iterator = $groups->all_objects(%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 in 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.

cpanm File::KDBX

perl -MCPAN -e shell
install File::KDBX