1File::KDBX::Object(3) User Contributed Perl DocumentationFile::KDBX::Object(3)
2
6 File::KDBX::Object - A KDBX database object
7
9 version 0.906
10
12 KDBX is an object database. This abstract class represents an object.
13 You should not use this class directly but instead use its subclasses:
14 • File::KDBX::Entry
16 • File::KDBX::Group
18 There is some functionality shared by both types of objects, and that's
20 what this class provides.
21 Each object can be connected with a File::KDBX database or be
23 disconnected. A disconnected object exists in memory but will not be
24 persisted when dumping a database. It is also possible for an object to
25 be connected with a database but not be part of the object tree (i.e.
26 is not the root group or any subroup or entry). A disconnected object
27 or an object not part of the object tree of a database can be added to
28 a database using one of:
29 • "add_entry" in File::KDBX
31 • "add_group" in File::KDBX
33 • "add_entry" in File::KDBX::Group
35 • "add_group" in File::KDBX::Group
37 • "add_historical_entry" in File::KDBX::Entry
39 It is possible to copy or move objects between databases, but DO NOT
41 include the same object in more than one database at once or there
42 could be some strange aliasing effects (i.e. changes in one database
43 might effect another in unexpected ways). This could lead to difficult-
44 to-debug problems. It is similarly not safe or valid to add the same
45 object multiple times to the same database. For example:
46 my $entry = File::KDBX::Entry->(title => 'Whatever');
48 # DO NOT DO THIS:
50 $kdbx->add_entry($entry);
51 $another_kdbx->add_entry($entry);
52 # DO NOT DO THIS:
54 $kdbx->add_entry($entry);
55 $kdbx->add_entry($entry); # again
56 Instead, do this:
58 # Copy an entry to multiple databases:
60 $kdbx->add_entry($entry);
61 $another_kdbx->add_entry($entry->clone);
62 # OR move an existing entry from one database to another:
64 $another_kdbx->add_entry($entry->remove);
65
67 kdbx
68 $kdbx = $object->kdbx;
69 $object->kdbx($kdbx);
70 Get or set the File::KDBX instance connected with this object. Throws
72 if the object is disconnected. Other object methods might only work if
73 the object is connected to a database and so they might also throw if
74 the object is disconnected. If you're not sure if an object is
75 connected, try "is_connected".
76 uuid
78 128-bit UUID identifying the object within the connected database.
79 icon_id
81 Integer representing a default icon. See ":icon" in
82 File::KDBX::Constants for valid values.
83 custom_icon_uuid
85 128-bit UUID identifying a custom icon within the connected database.
86 tags
88 Text string with arbitrary tags which can be used to build a taxonomy.
89 previous_parent_group
91 128-bit UUID identifying a group within the connected database the
92 previously contained the object.
93 last_modification_time
95 Date and time when the entry was last modified.
96 creation_time
98 Date and time when the entry was created.
99 last_access_time
101 Date and time when the entry was last accessed.
102 expiry_time
104 Date and time when the entry expired or will expire.
105 expires
107 Boolean value indicating whether or not an entry is expired.
108 usage_count
110 The number of times an entry has been used, which typically means how
111 many times the Password string has been accessed.
112 location_changed
114 Date and time when the entry was last moved to a different parent
115 group.
116
118 new
119 $object = File::KDBX::Object->new;
120 $object = File::KDBX::Object->new(%attributes);
121 $object = File::KDBX::Object->new(\%data);
122 $object = File::KDBX::Object->new(\%data, $kdbx);
123 Construct a new KDBX object.
125 There is a subtlety to take note of. There is a significant difference
127 between:
128 File::KDBX::Entry->new(username => 'iambatman');
130 and:
132 File::KDBX::Entry->new({username => 'iambatman'}); # WRONG
134 In the first, an empty object is first created and then initialized
136 with whatever attributes are given. In the second, a hashref is blessed
137 and essentially becomes the object. The significance is that the
138 hashref key-value pairs will remain as-is so the structure is expected
139 to adhere to the shape of a raw Object (which varies based on the type
140 of object), whereas with the first the attributes will set the
141 structure in the correct way (just like using the object accessors /
142 getters / setters).
143 The second example isn't generally wrong -- this type of construction
145 is supported for a reason, to allow for working with KDBX objects at a
146 low level -- but it is wrong in this specific case only because
147 "{username => $str}" isn't a valid raw KDBX entry object. The
148 "username" attribute is really a proxy for the "UserName" string, so
149 the equivalent raw entry object should be "{strings => {UserName =>
150 {value => $str}}}". These are roughly equivalent:
151 File::KDBX::Entry->new(username => 'iambatman');
153 File::KDBX::Entry->new({strings => {UserName => {value => 'iambatman'}}});
154 If this explanation went over your head, that's fine. Just stick with
156 the attributes since they are typically easier to use correctly and
157 provide the most convenience. If in the future you think of some kind
158 of KDBX object manipulation you want to do that isn't supported by the
159 accessors and methods, just know you can access an object's data
160 directly.
161 init
163 $object = $object->init(%attributes);
164 Called by the constructor to set attributes. You normally should not
166 call this.
167 wrap
169 $object = File::KDBX::Object->wrap($object);
170 Ensure that a KDBX object is blessed.
172 label
174 $label = $object->label;
175 $object->label($label);
176 Get or set the object's label, a text string that can act as a non-
178 unique identifier. For an entry, the label is its title string. For a
179 group, the label is its name.
180 clone
182 $object_copy = $object->clone(%options);
183 $object_copy = File::KDBX::Object->new($object);
184 Make a clone of an object. By default the clone is indeed an exact copy
186 that is connected to the same database but not actually included in the
187 object tree (i.e. it has no parent group). Some options are allowed to
188 get different effects:
189 • "new_uuid" - If set, generate a new UUID for the copy (default:
191 false)
192 • "parent" - If set, add the copy to the same parent group, if any
194 (default: false)
195 • "relabel" - If set, append " - Copy" to the object's title or name
197 (default: false)
198 • "entries" - If set, copy child entries, if any (default: true)
200 • "groups" - If set, copy child groups, if any (default: true)
202 • "history" - If set, copy entry history, if any (default: true)
204 • "reference_password" - Toggle whether or not cloned entry's
206 Password string should be set as a field reference to the original
207 entry's Password string (default: false)
208 • "reference_username" - Toggle whether or not cloned entry's
210 UserName string should be set as a field reference to the original
211 entry's UserName string (default: false)
212 is_connected
214 $bool = $object->is_connected;
215 Determine whether or not an object is connected to a database.
217 id
219 $string_uuid = $object->id;
220 $string_uuid = $object->id($delimiter);
221 Get the unique identifier for this object as a formatted UUID string,
223 typically for display purposes. You could use this to compare with
224 other identifiers formatted with the same delimiter, but it is more
225 efficient to use the raw UUID for that purpose (see "uuid").
226 A delimiter can optionally be provided to break up the UUID string
228 visually. See "format_uuid" in File::KDBX::Util.
229 group
231 $parent_group = $object->group;
232 $object->group($parent_group);
233 Get or set the parent group to which an object belongs or "undef" if it
235 belongs to no group.
236 lineage
238 \@lineage = $object->lineage;
239 \@lineage = $object->lineage($base_group);
240 Get the direct line of ancestors from $base_group (default: the root
242 group) to an object. The lineage includes the base group but not the
243 target object. Returns "undef" if the target is not in the database
244 structure. Returns an empty arrayref is the object itself is a root
245 group.
246 remove
248 $object = $object->remove(%options);
249 Remove an object from its parent. If the object is a group, all
251 contained objects stay with the object and so are removed as well, just
252 like cutting off a branch takes the leafs as well. Options:
253 • "signal" Whether or not to signal the removal to the connected
255 database (default: true)
256 recycle
258 $object = $object->recycle;
259 Remove an object from its parent and add it to the connected database's
261 recycle bin group.
262 recycle_or_remove
264 $object = $object->recycle_or_remove;
265 Recycle or remove an object, depending on the connected database's
267 "recycle_bin_enabled" in File::KDBX. If the object is not connected to
268 a database or is already in the recycle bin, remove it.
269 is_recycled
271 $bool = $object->is_recycled;
272 Get whether or not an object is in a recycle bin.
274 tag_list
276 @tags = $entry->tag_list;
277 Get a list of tags, split from "tag" using delimiters ",", ".", ":",
279 ";" and whitespace.
280 custom_icon
282 $image_data = $object->custom_icon;
283 $image_data = $object->custom_icon($image_data, %attributes);
284 Get or set an icon image. Returns "undef" if there is no custom icon
286 set. Setting a custom icon will change the "custom_icon_uuid"
287 attribute.
288 Custom icon attributes (supported in KDBX4.1 and greater):
290 • "name" - Name of the icon (text)
292 • "last_modification_time" - Just what it says (datetime)
294 custom_data
296 \%all_data = $object->custom_data;
297 $object->custom_data(\%all_data);
298 \%data = $object->custom_data($key);
300 $object->custom_data($key => \%data);
301 $object->custom_data(%data);
302 $object->custom_data(key => $value, %data);
303 Get and set custom data. Custom data is metadata associated with an
305 object. It is a set of key-value pairs used to store arbitrary data,
306 usually used by software like plug-ins to keep track of state rather
307 than by end users.
308 Each data item can have a few attributes associated with it.
310 • "key" - A unique text string identifier used to look up the data
312 item (required)
313 • "value" - A text string value (required)
315 • "last_modification_time" (optional, KDBX4.1+)
317 custom_data_value
319 $value = $object->custom_data_value($key);
320 Exactly the same as "custom_data" except returns just the custom data's
322 value rather than a structure of attributes. This is a shortcut for:
323 my $data = $object->custom_data($key);
325 my $value = defined $data ? $data->{value} : undef;
326 begin_work
328 $txn = $object->begin_work(%options);
329 $object->begin_work(%options);
330 Begin a new transaction. Returns a File::KDBX::Transaction object that
332 can be scoped to ensure a rollback occurs if exceptions are thrown.
333 Alternatively, if called in void context, there will be no
334 File::KDBX::Transaction and it is instead your responsibility to call
335 "commit" or "rollback" as appropriate. It is undefined behavior to call
336 these if a File::KDBX::Transaction exists. Recursive transactions are
337 allowed.
338 Signals created during a transaction are delayed until all transactions
340 are resolved. If the outermost transaction is committed, then the
341 signals are de-duplicated and delivered. Otherwise the signals are
342 dropped. This means that the KDBX database will not fix broken
343 references or mark itself dirty until after the transaction is
344 committed.
345 How it works: With the beginning of a transaction, a snapshot of the
347 object is created. In the event of a rollback, the object's data is
348 replaced with data from the snapshot.
349 By default, the snapshot is shallow (i.e. does not include subroups,
351 entries or historical entries). This means that only modifications to
352 the object itself (its data, fields, strings, etc.) are atomic;
353 modifications to subroups etc., including adding or removing items, are
354 auto-committed instantly and will persist regardless of the result of
355 the pending transaction. You can override this for groups, entries and
356 history independently using options:
357 • "entries" - If set, snapshot entries within a group, deeply
359 (default: false)
360 • "groups" - If set, snapshot subroups within a group, deeply
362 (default: false)
363 • "history" - If set, snapshot historical entries within an entry
365 (default: false)
366 For example, if you begin a transaction on a group object using the
368 "entries" option, like this:
369 $group->begin_work(entries => 1);
371 Then if you modify any of the group's entries OR add new entries OR
373 delete entries, all of that will be undone if the transaction is rolled
374 back. With a default-configured transaction, however, changes to
375 entries are kept even if the transaction is rolled back.
376 commit
378 $object->commit;
379 Commit a transaction, making updates to $object permanent. Returns
381 itself to allow method chaining.
382 rollback
384 $object->rollback;
385 Roll back the most recent transaction, throwing away any updates to the
387 "object" made since the transaction began. Returns itself to allow
388 method chaining.
389
391 Please report any bugs or feature requests on the bugtracker website
392 <https://github.com/chazmcgarvey/File-KDBX/issues>
393 When submitting a bug or request, please include a test-file or a patch
395 to an existing test-file that illustrates the bug or desired feature.
396
398 Charles McGarvey <ccm@cpan.org>
399
401 This software is copyright (c) 2022 by Charles McGarvey.
402 This is free software; you can redistribute it and/or modify it under
404 the same terms as the Perl 5 programming language system itself.
405perl v5.38.0 2023-09-27 File::KDBX::Object(3)