1 package File
::KDBX
::Object
;
2 # ABSTRACT: A KDBX database object
7 use Devel
::GlobalDestruction
;
9 use File
::KDBX
::Util
qw(:uuid);
10 use Ref
::Util
qw(is_arrayref is_plain_hashref is_ref);
11 use Scalar
::Util
qw(blessed refaddr weaken);
14 our $VERSION = '999.999'; # VERSION
20 $object = File
::KDBX
::Entry-
>new;
21 $object = File
::KDBX
::Entry-
>new(%attributes);
22 $object = File
::KDBX
::Entry-
>new($data);
23 $object = File
::KDBX
::Entry-
>new($data, $kdbx);
25 Construct a new KDBX object
.
27 There
is a subtlety to
take note of
. There
is a significant difference between
:
29 File
::KDBX
::Entry-
>new(username
=> 'iambatman');
33 File
::KDBX
::Entry-
>new({username
=> 'iambatman'}); # WRONG
35 In the first
, an empty entry
is first created
and then initialized with whatever I
<attributes
> are
given. In
36 the second
, a hashref
is blessed
and essentially becomes the entry
. The significance
is that the hashref
37 key-value pairs will remain as-is so the structure
is expected to adhere to the shape of a raw B
<Entry
>,
38 whereas with the first the attributes will set the structure
in the correct way
(just like using the entry
39 object accessors
/ getters / setters
).
41 The second example isn
't I<generally> wrong -- this type of construction is supported for a reason, to allow
42 for working with KDBX objects at a low level -- but it is wrong in this specific case only because
43 C<< {username => $str} >> isn't a valid raw KDBX entry object
. The L
</username
> attribute
is really a proxy
44 for the C
<UserName
> string
, so the equivalent raw entry object should be
45 C
<< {strings
=> {UserName
=> {value
=> $str}}} >>. These are roughly equivalent
:
47 File
::KDBX
::Entry-
>new(username
=> 'iambatman');
48 File
::KDBX
::Entry-
>new({strings
=> {UserName
=> {value
=> 'iambatman'}}});
50 If this explanation went over your head
, that
's fine. Just stick with the attributes since they are typically
51 easier to use correctly and provide the most convenience. If in the future you think of some kind of KDBX
52 object manipulation you want to do that isn't supported by the accessors
and methods
, just know you I
<can
>
53 access an object
's data directly.
61 return $_[0]->clone if @_ == 1 && blessed $_[0] && $_[0]->isa($class);
64 $data = shift if is_plain_hashref($_[0]);
67 $kdbx = shift if @_ % 2 == 1;
70 $args{kdbx} //= $kdbx if defined $kdbx;
72 my $self = bless $data // {}, $class;
74 $self->_set_default_attributes if !$data;
82 while (my ($key, $val) = each %args) {
83 if (my $method = $self->can($key)) {
92 return if in_global_destruction;
94 delete $KDBX{refaddr($self)};
99 $object = File::KDBX::Object->wrap($object);
101 Ensure that a KDBX object is blessed.
108 return $object if blessed $object && $object->isa($class);
109 return $class->new(@_, @$object) if is_arrayref($object);
110 return $class->new($object, @_);
115 $label = $object->label;
116 $object->label($label);
118 Get or set the object's label
, a text string that can act as a non-unique identifier
. For an entry
, the label
119 is its title
. For a group
, the label
is its name
.
123 sub label
{ die "Not implemented" }
127 $object_copy = $object->clone;
128 $object_copy = File
::KDBX
::Object-
>new($object);
130 Make a clone of an entry
. By
default the clone
is indeed an exact copy that
is associated with the same
131 database but
not actually included
in the object tree
(i
.e
. it
has no parent
), but some options are allowed to
132 get different effects
:
135 * C<new_uuid> - Set a new UUID; value can be the new UUID, truthy to generate a random UUID, or falsy to keep
136 the original UUID (default: same value as C<parent>)
137 * C<parent> - If set, add the copy to the same parent (default: false)
138 * C<relabel> - If set, change the name or title of the copy to "C<$original_title> - Copy".
139 * C<entries> - Toggle whether or not to copy child entries, if any (default: true)
140 * C<groups> - Toggle whether or not to copy child groups, if any (default: true)
141 * C<history> - Toggle whether or not to copy the entry history, if any (default: true)
142 * C<reference_password> - Toggle whether or not cloned entry's Password string should be set to a reference to
143 their original entry's Password string.
144 * C<reference_username> - Toggle whether or not cloned entry's UserName string should be set to a reference to
145 their original entry's UserName string.
149 my %CLONE = (entries
=> 1, groups
=> 1, history
=> 1);
154 local $CLONE{new_uuid
} = $args{new_uuid
} // $args{parent
} // 0;
155 local $CLONE{entries
} = $args{entries
} // 1;
156 local $CLONE{groups
} = $args{groups
} // 1;
157 local $CLONE{history
} = $args{history
} // 1;
158 local $CLONE{reference_password
} = $args{reference_password
} // 0;
159 local $CLONE{reference_username
} = $args{reference_username
} // 0;
162 my $copy = Storable
::dclone
($self);
164 if ($args{relabel
} and my $label = $self->label) {
165 $copy->label("$label - Copy");
167 if ($args{parent
} and my $parent = $self->parent) {
168 $parent->add_object($copy);
174 sub STORABLE_freeze
{
179 delete $copy->{entries
} if !$CLONE{entries
};
180 delete $copy->{groups
} if !$CLONE{groups
};
181 delete $copy->{history
} if !$CLONE{history
};
183 return refaddr
($self) || '', $copy;
192 @$self{keys %$clone} = values %$clone;
194 my $kdbx = $KDBX{$addr};
195 $self->kdbx($kdbx) if $kdbx;
198 if (($CLONE{reference_password
} || $CLONE{reference_username
}) && $self->isa('File::KDBX::Entry')) {
199 my $uuid = format_uuid
($self->{uuid
});
201 local $CLONE{new_uuid
} = 0;
202 local $CLONE{entries
} = 1;
203 local $CLONE{groups
} = 1;
204 local $CLONE{history
} = 1;
205 local $CLONE{reference_password
} = 0;
206 local $CLONE{reference_username
} = 0;
207 bless Storable
::dclone
({%$clone}), 'File::KDBX::Entry';
209 my $txn = $self->begin_work($clone_obj);
210 if ($CLONE{reference_password
}) {
211 $self->password("{REF:P\@I:$uuid}");
213 if ($CLONE{reference_username
}) {
214 $self->username("{REF:U\@I:$uuid}");
218 $self->uuid(generate_uuid
) if $CLONE{new_uuid
};
224 $kdbx = $object->kdbx;
225 $object->kdbx($kdbx);
227 Get
or set the L
<File
::KDBX
> instance associated with this object
.
233 $self = $self->new if !ref $self;
234 my $addr = refaddr
($self);
236 $KDBX{$addr} = shift;
237 if (defined $KDBX{$addr}) {
244 $KDBX{$addr} or throw
'Object is disassociated from a KDBX database', object
=> $self;
249 $string_uuid = $object->id;
250 $string_uuid = $object->id($delimiter);
252 Get the unique identifier
for this object as a B
<formatted
> UUID string
, typically
for display purposes
. You
253 could
use this to compare with other identifiers formatted with the same delimiter
, but it
is more efficient
254 to
use the raw UUID
for that purpose
(see L
</uuid
>).
256 A delimiter can optionally be provided to
break up the UUID string visually
. See
257 L
<File
::KDBX
::Util
/format_uuid
>.
261 sub id
{ format_uuid
(shift-
>uuid, @_) }
265 $group = $object->group;
267 Get the parent group to which an object belongs
or C
<undef> if it belongs to
no group
.
275 my $lineage = $self->kdbx->trace_lineage($self) or return;
276 return pop @$lineage;
279 sub parent
{ shift-
>group(@_) }
283 $object = $object->remove;
285 Remove the object from the database
. If the object
is a group
, all contained objects are removed as well
.
291 my $parent = $self->parent;
292 $parent->remove_object($self) if $parent;
298 @tags = $entry->tag_list;
300 Get a list of tags
, split from L
</tag
> using delimiters C
<,>, C
<.>, C
<:>, C
<;> and whitespace
.
306 return grep { $_ ne '' } split(/[,\.:;]|\s+/, trim
($self->tags) // '');
311 $image_data = $object->custom_icon;
312 $image_data = $object->custom_icon($image_data, %attributes);
314 Get
or set an icon image
. Returns C
<undef> if there
is no custom icon set
. Setting a custom icon will change
315 the L
</custom_icon_uuid
> attribute
.
317 Custom icon attributes
(supported
in KDBX4
.1
and greater
):
320 * C<name> - Name of the icon (text)
321 * C<last_modification_time> - Just what it says (datetime)
327 my $kdbx = $self->kdbx;
330 my $uuid = defined $img ? $kdbx->add_custom_icon($img, @_) : undef;
331 $self->icon_id(0) if $uuid;
332 $self->custom_icon_uuid($uuid);
335 return $kdbx->custom_icon_data($self->custom_icon_uuid);
340 \
%all_data = $object->custom_data;
341 $object->custom_data(\
%all_data);
343 \
%data = $object->custom_data($key);
344 $object->custom_data($key => \
%data);
345 $object->custom_data(%data);
346 $object->custom_data(key
=> $value, %data);
348 Get
and set custom data
. Custom data
is metadata associated with an object
.
350 Each data item can have a few attributes associated with it
.
353 * C<key> - A unique text string identifier used to look up the data item (required)
354 * C<value> - A text string value (required)
355 * C<last_modification_time> (optional, KDBX4.1+)
361 $self->{custom_data
} = shift if @_ == 1 && is_plain_hashref
($_[0]);
362 return $self->{custom_data
} //= {} if !@_;
364 my %args = @_ == 2 ? (key
=> shift, value
=> shift)
365 : @_ % 2 == 1 ? (key
=> shift, @_) : @_;
367 if (!$args{key
} && !$args{value
}) {
368 my %standard = (key
=> 1, value
=> 1, last_modification_time
=> 1);
369 my @other_keys = grep { !$standard{$_} } keys %args;
370 if (@other_keys == 1) {
371 my $key = $args{key
} = $other_keys[0];
372 $args{value
} = delete $args{$key};
376 my $key = $args{key
} or throw
'Must provide a custom_data key to access';
378 return $self->{custom_data
}{$key} = $args{value
} if is_plain_hashref
($args{value
});
380 while (my ($field, $value) = each %args) {
381 $self->{custom_data
}{$key}{$field} = $value;
383 return $self->{custom_data
}{$key};
386 =method custom_data_value
388 $value = $object->custom_data_value($key);
390 Exactly the same as L
</custom_data
> except returns just the custom data
's value rather than a structure of
391 attributes. This is a shortcut for:
393 my $data = $object->custom_data($key);
394 my $value = defined $data ? $data->{value} : undef;
398 sub custom_data_value {
400 my $data = $self->custom_data(@_) // return undef;
401 return $data->{value};
409 KDBX is an object database. This abstract class represents an object. You should not use this class directly
410 but instead use its subclasses:
413 * L<File::KDBX::Entry>
414 * L<File::KDBX::Group>
416 There is some functionality shared by both types of objects, and that's what this
class provides
.