Add function for creating class attributes

[chaz/p5-File-KDBX] / lib / File / KDBX / Dumper.pm

diff --git a/lib/File/KDBX/Dumper.pm b/lib/File/KDBX/Dumper.pm
index 6d02063bdacce13c7f8369a72403ad7cf1400ca4..7e2741c9353fb1212b03e168bec57110a946c403 100644 (file)
--- a/lib/File/KDBX/Dumper.pm
+++ b/lib/File/KDBX/Dumper.pm
@@ -7,6 +7,7 @@ use strict;
 use Crypt::Digest qw(digest_data);
 use File::KDBX::Constants qw(:magic :header :version :random_stream);
 use File::KDBX::Error;
+use File::KDBX::Util qw(:class);
 use File::KDBX;
 use IO::Handle;
 use Module::Load;
@@ -237,12 +238,58 @@ sub kdbx {
 
 =attr format
 
+Get the file format used for writing the database. Normally the format is auto-detected from the database,
+which is the safest choice. Possible formats:
+
+=for :list
+* C<V3>
+* C<V4>
+* C<KDB>
+* C<XML> (only used if explicitly set)
+* C<Raw> (only used if explicitly set)
+
+B<WARNING:> There is a potential for data loss if you explicitly use a format that doesn't support the
+features used by the KDBX database being written.
+
+The most common reason to explicitly specify the file format is to save a database as an unencrypted XML file:
+
+    $kdbx->dump_file('database.xml', format => 'XML');
+
+=attr inner_format
+
+Get the format of the data inside the KDBX envelope. This only applies to C<V3> and C<V4> formats. Possible
+formats:
+
+=for :list
+* C<XML> - Write the database groups and entries as XML (default)
+* C<Raw> - Write L<File::KDBX/raw> instead of the actual database contents
+
+=attr allow_upgrade
+
+    $bool = $dumper->allow_upgrade;
+
+Whether or not to allow implicitly upgrading a database to a newer version. When enabled, in order to avoid
+potential data loss, the database can be upgraded as-needed in cases where the database file format version is
+too low to support new features being used.
+
+The default is to allow upgrading.
+
+=attr randomize_seeds
+
+    $bool = $dumper->randomize_seeds;
+
+Whether or not to randomize seeds in a database before writing. The default is to randomize seeds, and there's
+not often a good reason not to do so. If disabled, the seeds associated with the KDBX database will be used as
+they are.
+
 =cut
 
-sub format { $_[0]->{format} }
-sub inner_format { $_[0]->{inner_format} // 'XML' }
+has 'format',           is => 'ro';
+has 'inner_format',     is => 'ro', default => 'XML';
+has 'allow_upgrade',    is => 'ro', default => 1;
+has 'randomize_seeds',  is => 'ro', default => 1;
 
-=attr min_version
+=method min_version
 
     $min_version = File::KDBX::Dumper->min_version;
 
@@ -255,10 +302,6 @@ To generate older KDBX files unsupported by this module, try L<File::KeePass>.
 
 sub min_version { KDBX_VERSION_OLDEST }
 
-sub upgrade { $_[0]->{upgrade} // 1 }
-
-sub randomize_seeds { $_[0]->{randomize_seeds} // 1 }
-
 sub _fh { $_[0]->{fh} or throw 'IO handle not set' }
 
 sub _dump {
@@ -269,7 +312,7 @@ sub _dump {
     my $kdbx = $self->kdbx;
 
     my $min_version = $kdbx->minimum_version;
-    if ($kdbx->version < $min_version && $self->upgrade) {
+    if ($kdbx->version < $min_version && $self->allow_upgrade) {
         alert sprintf("Implicitly upgrading database from %x to %x\n", $kdbx->version, $min_version),
             version => $kdbx->version, min_version => $min_version;
         $kdbx->version($min_version);