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.
Install Now
PNG Icons
Emojis