X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fp5-File-KDBX;a=blobdiff_plain;f=lib%2FFile%2FKDBX%2FObject.pm;h=63eadcca0dbd03da9881221e2ef2b54c35c59ede;hp=9f25c3897b95bae4b6226dd26a07418954e2cf53;hb=63d73bf382edfb0089b36a45193fc2835cb58b6d;hpb=00078cf200c23f392322f4fdc29e4f44ddf73f41

diff --git a/lib/File/KDBX/Object.pm b/lib/File/KDBX/Object.pm
index 9f25c38..63eadcc 100644
--- a/lib/File/KDBX/Object.pm
+++ b/lib/File/KDBX/Object.pm
@@ -131,11 +131,11 @@ sub label { die 'Not implemented' }
 
 =method clone
 
-    $object_copy = $object->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). Some options are allowed to get
+but not actually included in the object tree (i.e. it has no parent group). Some options are allowed to get
 different effects:
 
 =for :list
@@ -170,7 +170,7 @@ sub clone {
     if ($args{relabel} and my $label = $self->label) {
         $copy->label("$label - Copy");
     }
-    if ($args{parent} and my $parent = $self->parent) {
+    if ($args{parent} and my $parent = $self->group) {
         $parent->add_object($copy);
     }
 
@@ -236,7 +236,9 @@ sub STORABLE_thaw {
     $kdbx = $object->kdbx;
     $object->kdbx($kdbx);
 
-Get or set the L<File::KDBX> instance connected with this object.
+Get or set the L<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 L</is_connected>.
 
 =cut
 
@@ -286,13 +288,8 @@ sub id { format_uuid(shift->uuid, @_) }
 
 =method group
 
-=method parent
-
-    $group = $object->group;
-    # OR equivalently
-    $group = $object->parent;
-
-    $object->group($new_parent);
+    $parent_group = $object->group;
+    $object->group($parent_group);
 
 Get or set the parent group to which an object belongs or C<undef> if it belongs to no group.
 
@@ -306,6 +303,7 @@ sub group {
         return $new_group if Hash::Util::FieldHash::id($old_group) == Hash::Util::FieldHash::id($new_group);
         # move to a new parent
         $self->remove(signal => 0) if $old_group;
+        $self->location_changed('now');
         $new_group->add_object($self);
     }
 
@@ -322,8 +320,6 @@ sub group {
     return $group;
 }
 
-sub parent { shift->group(@_) }
-
 sub _set_group {
     my $self = shift;
     if (my $parent = shift) {
@@ -358,10 +354,10 @@ sub lineage {
 
     # try leaf to root
     my @path;
-    my $o = $self;
-    while ($o = $o->parent) {
-        unshift @path, $o;
-        last if $base_addr == Hash::Util::FieldHash::id($o);
+    my $object = $self;
+    while ($object = $object->group) {
+        unshift @path, $object;
+        last if $base_addr == Hash::Util::FieldHash::id($object);
     }
     return \@path if @path && ($base_addr == Hash::Util::FieldHash::id($path[0]) || $path[0]->is_root);
 
@@ -374,7 +370,7 @@ sub lineage {
     $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. Options:
+are removed as well, just like cutting off a branch takes the leafs as well. Options:
 
 =for :list
 * C<signal> Whether or not to signal the removal to the connected database (default: true)
@@ -383,7 +379,7 @@ are removed as well. Options:
 
 sub remove {
     my $self = shift;
-    my $parent = $self->parent;
+    my $parent = $self->group;
     $parent->remove_object($self, @_) if $parent;
     $self->_set_group(undef);
     return $self;
@@ -399,7 +395,7 @@ Remove an object from its parent and add it to the connected database's recycle
 
 sub recycle {
     my $self = shift;
-    return $self->parent($self->kdbx->recycle_bin);
+    return $self->group($self->kdbx->recycle_bin);
 }
 
 =method recycle_or_remove
@@ -433,7 +429,7 @@ Get whether or not an object is in a recycle bin.
 sub is_recycled {
     my $self = shift;
     eval { $self->kdbx } or return FALSE;
-    return !!($self->parent && any { $_->is_recycle_bin } @{$self->lineage});
+    return !!($self->group && any { $_->is_recycle_bin } @{$self->lineage});
 }
 
 ##############################################################################
@@ -490,7 +486,9 @@ sub custom_icon {
     $object->custom_data(%data);
     $object->custom_data(key => $value, %data);
 
-Get and set custom data. Custom data is metadata associated with an object.
+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.
 
@@ -817,7 +815,7 @@ one of:
 * L<File::KDBX::Entry/add_historical_entry>
 
 It is possible to copy or move objects between databases, but B<DO NOT> include the same object in more
-than one database at once or there could some strange aliasing effects (i.e. changes in one database might
+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:
 
@@ -838,6 +836,55 @@ Instead, do this:
     $another_kdbx->add_entry($entry->clone);
 
     # OR move an existing entry from one database to another:
-    $kdbx->add_entry($entry->remove);
+    $another_kdbx->add_entry($entry->remove);
+
+=attr uuid
+
+128-bit UUID identifying the object within the connected database.
+
+=attr icon_id
+
+Integer representing a default icon. See L<File::KDBX::Constants/":icon"> for valid values.
+
+=attr custom_icon_uuid
+
+128-bit UUID identifying a custom icon within the connected database.
+
+=attr tags
+
+Text string with arbitrary tags which can be used to build a taxonomy.
+
+=attr previous_parent_group
+
+128-bit UUID identifying a group within the connected database the previously contained the object.
+
+=attr last_modification_time
+
+Date and time when the entry was last modified.
+
+=attr creation_time
+
+Date and time when the entry was created.
+
+=attr last_access_time
+
+Date and time when the entry was last accessed.
+
+=attr expiry_time
+
+Date and time when the entry expired or will expire.
+
+=attr expires
+
+Boolean value indicating whether or not an entry is expired.
+
+=attr usage_count
+
+The number of times an entry has been used, which typically means how many times the B<Password> string has
+been accessed.
+
+=attr location_changed
+
+Date and time when the entry was last moved to a different parent group.
 
 =cut