Provided by: libfile-kdbx-perl_0.906-2_all 
NAME
File::KDBX::Object - A KDBX database object
VERSION
version 0.906
DESCRIPTION
KDBX is an object database. This abstract class represents an object. You should not use
this class directly but instead use its subclasses:
• File::KDBX::Entry
• File::KDBX::Group
There is some functionality shared by both types of objects, and that's what this class
provides.
Each object can be connected with a File::KDBX database or be disconnected. A disconnected
object exists in memory but will not be persisted when dumping a database. It is also
possible for an object to be connected with a database but not be part of the object tree
(i.e. is not the root group or any subroup or entry). A disconnected object or an object
not part of the object tree of a database can be added to a database using one of:
• "add_entry" in File::KDBX
• "add_group" in File::KDBX
• "add_entry" in File::KDBX::Group
• "add_group" in File::KDBX::Group
• "add_historical_entry" in File::KDBX::Entry
It is possible to copy or move objects between databases, but DO NOT include the same
object in more than one database at once or there could be some strange aliasing effects
(i.e. changes in one database might effect another in unexpected ways). This could lead to
difficult-to-debug problems. It is similarly not safe or valid to add the same object
multiple times to the same database. For example:
my $entry = File::KDBX::Entry->(title => 'Whatever');
# DO NOT DO THIS:
$kdbx->add_entry($entry);
$another_kdbx->add_entry($entry);
# DO NOT DO THIS:
$kdbx->add_entry($entry);
$kdbx->add_entry($entry); # again
Instead, do this:
# Copy an entry to multiple databases:
$kdbx->add_entry($entry);
$another_kdbx->add_entry($entry->clone);
# OR move an existing entry from one database to another:
$another_kdbx->add_entry($entry->remove);
ATTRIBUTES
kdbx
$kdbx = $object->kdbx;
$object->kdbx($kdbx);
Get or set the File::KDBX instance connected with this object. Throws if the object is
disconnected. Other object methods might only work if the object is connected to a
database and so they might also throw if the object is disconnected. If you're not sure if
an object is connected, try "is_connected".
uuid
128-bit UUID identifying the object within the connected database.
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 connected database.
tags
Text string with arbitrary tags which can be used to build a taxonomy.
previous_parent_group
128-bit UUID identifying a group within the connected database the previously contained
the object.
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
The number of times an entry has been used, which typically means how many times the
Password string has been accessed.
location_changed
Date and time when the entry was last moved to a different parent group.
METHODS
new
$object = File::KDBX::Object->new;
$object = File::KDBX::Object->new(%attributes);
$object = File::KDBX::Object->new(\%data);
$object = File::KDBX::Object->new(\%data, $kdbx);
Construct a new KDBX object.
There is a subtlety to take note of. There is a significant difference between:
File::KDBX::Entry->new(username => 'iambatman');
and:
File::KDBX::Entry->new({username => 'iambatman'}); # WRONG
In the first, an empty object is first created and then initialized with whatever
attributes are given. In the second, a hashref is blessed and essentially becomes the
object. The significance is that the hashref key-value pairs will remain as-is so the
structure is expected to adhere to the shape of a raw Object (which varies based on the
type of object), whereas with the first the attributes will set the structure in the
correct way (just like using the object accessors / getters / setters).
The second example isn't generally wrong -- this type of construction is supported for a
reason, to allow for working with KDBX objects at a low level -- but it is wrong in this
specific case only because "{username => $str}" isn't a valid raw KDBX entry object. The
"username" attribute is really a proxy for the "UserName" string, so the equivalent raw
entry object should be "{strings => {UserName => {value => $str}}}". These are roughly
equivalent:
File::KDBX::Entry->new(username => 'iambatman');
File::KDBX::Entry->new({strings => {UserName => {value => 'iambatman'}}});
If this explanation went over your head, that's fine. Just stick with the attributes since
they are typically easier to use correctly and provide the most convenience. If in the
future you think of some kind of KDBX object manipulation you want to do that isn't
supported by the accessors and methods, just know you can access an object's data
directly.
init
$object = $object->init(%attributes);
Called by the constructor to set attributes. You normally should not call this.
wrap
$object = File::KDBX::Object->wrap($object);
Ensure that a KDBX object is blessed.
label
$label = $object->label;
$object->label($label);
Get or set the object's label, a text string that can act as a non-unique identifier. For
an entry, the label is its title string. For a group, the label is its name.
clone
$object_copy = $object->clone(%options);
$object_copy = File::KDBX::Object->new($object);
Make a clone of an object. By default the clone is indeed an exact copy that is connected
to the same database but not actually included in the object tree (i.e. it has no parent
group). Some options are allowed to get different effects:
• "new_uuid" - If set, generate a new UUID for the copy (default: false)
• "parent" - If set, add the copy to the same parent group, if any (default: false)
• "relabel" - If set, append " - Copy" to the object's title or name (default: false)
• "entries" - If set, copy child entries, if any (default: true)
• "groups" - If set, copy child groups, if any (default: true)
• "history" - If set, copy entry history, if any (default: true)
• "reference_password" - Toggle whether or not cloned entry's Password string should be
set as a field reference to the original entry's Password string (default: false)
• "reference_username" - Toggle whether or not cloned entry's UserName string should be
set as a field reference to the original entry's UserName string (default: false)
is_connected
$bool = $object->is_connected;
Determine whether or not an object is connected to a database.
id
$string_uuid = $object->id;
$string_uuid = $object->id($delimiter);
Get the unique identifier for this object as a formatted UUID string, typically for
display purposes. You could use this to compare with other identifiers formatted with the
same delimiter, but it is more efficient to use the raw UUID for that purpose (see
"uuid").
A delimiter can optionally be provided to break up the UUID string visually. See
"format_uuid" in File::KDBX::Util.
group
$parent_group = $object->group;
$object->group($parent_group);
Get or set the parent group to which an object belongs or "undef" if it belongs to no
group.
lineage
\@lineage = $object->lineage;
\@lineage = $object->lineage($base_group);
Get the direct line of ancestors from $base_group (default: the root group) to an object.
The lineage includes the base group but not the target object. Returns "undef" if the
target is not in the database structure. Returns an empty arrayref is the object itself is
a root group.
remove
$object = $object->remove(%options);
Remove an object from its parent. If the object is a group, all contained objects stay
with the object and so are removed as well, just like cutting off a branch takes the leafs
as well. Options:
• "signal" Whether or not to signal the removal to the connected database (default:
true)
recycle
$object = $object->recycle;
Remove an object from its parent and add it to the connected database's recycle bin group.
recycle_or_remove
$object = $object->recycle_or_remove;
Recycle or remove an object, depending on the connected database's "recycle_bin_enabled"
in File::KDBX. If the object is not connected to a database or is already in the recycle
bin, remove it.
is_recycled
$bool = $object->is_recycled;
Get whether or not an object is in a recycle bin.
tag_list
@tags = $entry->tag_list;
Get a list of tags, split from "tag" using delimiters ",", ".", ":", ";" and whitespace.
custom_icon
$image_data = $object->custom_icon;
$image_data = $object->custom_icon($image_data, %attributes);
Get or set an icon image. Returns "undef" if there is no custom icon set. Setting a custom
icon will change the "custom_icon_uuid" attribute.
Custom icon attributes (supported in KDBX4.1 and greater):
• "name" - Name of the icon (text)
• "last_modification_time" - Just what it says (datetime)
custom_data
\%all_data = $object->custom_data;
$object->custom_data(\%all_data);
\%data = $object->custom_data($key);
$object->custom_data($key => \%data);
$object->custom_data(%data);
$object->custom_data(key => $value, %data);
Get and set custom data. Custom data is metadata associated with an object. It is a set of
key-value pairs used to store arbitrary data, usually used by software like plug-ins to
keep track of state rather than by end users.
Each data item can have a few attributes associated with it.
• "key" - A unique text string identifier used to look up the data item (required)
• "value" - A text string value (required)
• "last_modification_time" (optional, KDBX4.1+)
custom_data_value
$value = $object->custom_data_value($key);
Exactly the same as "custom_data" except returns just the custom data's value rather than
a structure of attributes. This is a shortcut for:
my $data = $object->custom_data($key);
my $value = defined $data ? $data->{value} : undef;
begin_work
$txn = $object->begin_work(%options);
$object->begin_work(%options);
Begin a new transaction. Returns a File::KDBX::Transaction object that can be scoped to
ensure a rollback occurs if exceptions are thrown. Alternatively, if called in void
context, there will be no File::KDBX::Transaction and it is instead your responsibility to
call "commit" or "rollback" as appropriate. It is undefined behavior to call these if a
File::KDBX::Transaction exists. Recursive transactions are allowed.
Signals created during a transaction are delayed until all transactions are resolved. If
the outermost transaction is committed, then the signals are de-duplicated and delivered.
Otherwise the signals are dropped. This means that the KDBX database will not fix broken
references or mark itself dirty until after the transaction is committed.
How it works: With the beginning of a transaction, a snapshot of the object is created. In
the event of a rollback, the object's data is replaced with data from the snapshot.
By default, the snapshot is shallow (i.e. does not include subroups, entries or historical
entries). This means that only modifications to the object itself (its data, fields,
strings, etc.) are atomic; modifications to subroups etc., including adding or removing
items, are auto-committed instantly and will persist regardless of the result of the
pending transaction. You can override this for groups, entries and history independently
using options:
• "entries" - If set, snapshot entries within a group, deeply (default: false)
• "groups" - If set, snapshot subroups within a group, deeply (default: false)
• "history" - If set, snapshot historical entries within an entry (default: false)
For example, if you begin a transaction on a group object using the "entries" option, like
this:
$group->begin_work(entries => 1);
Then if you modify any of the group's entries OR add new entries OR delete entries, all of
that will be undone if the transaction is rolled back. With a default-configured
transaction, however, changes to entries are kept even if the transaction is rolled back.
commit
$object->commit;
Commit a transaction, making updates to $object permanent. Returns itself to allow method
chaining.
rollback
$object->rollback;
Roll back the most recent transaction, throwing away any updates to the "object" made
since the transaction began. Returns itself to allow method chaining.
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.