]> Dogcows Code - chaz/p5-File-KDBX/commitdiff
Release File-KDBX 0.900 v0.900
authorCharles McGarvey <ccm@cpan.org>
Sun, 1 May 2022 18:56:44 +0000 (12:56 -0600)
committerCharles McGarvey <ccm@cpan.org>
Sun, 1 May 2022 18:56:44 +0000 (12:56 -0600)
  * Removed the min_version methods from dumper and loader because it was
    unused and unnecessary.
  * Now use the database maintenance_history_days value as the default
    "max_age" value in prune_history method.
  * Fixed distribution prereq issues.
  * Clean up a lot of pod typos and other inaccuracies.

Changes
README.md

diff --git a/Changes b/Changes
index e8dd718424fa02b5ab47e2e3019169a4d593eb96..c0f24ec2b21fac4025f004b07c08c8abd672e564 100644 (file)
--- a/Changes
+++ b/Changes
@@ -2,11 +2,14 @@ Revision history for File-KDBX.
 
 {{$NEXT}}
 
+0.900     2022-05-01 12:55:59-0600
+
   * Removed the min_version methods from dumper and loader because it was
     unused and unnecessary.
   * Now use the database maintenance_history_days value as the default
     "max_age" value in prune_history method.
   * Fixed distribution prereq issues.
+  * Clean up a lot of pod typos and other inaccuracies.
 
 0.800     2022-04-30 21:14:30-0600
 
index f8d4aafdbbe6629009c10e40c85e3c840467c4e8..c73251487c89fd2244b474674dbec7b57e9e43e3 100644 (file)
--- a/README.md
+++ b/README.md
@@ -8,44 +8,46 @@ File::KDBX - Encrypted database to store secret text and files
 
 # VERSION
 
-version 0.800
+version 0.900
 
 # SYNOPSIS
 
-    use File::KDBX;
+```perl
+use File::KDBX;
 
-    my $kdbx = File::KDBX->new;
+my $kdbx = File::KDBX->new;
 
-    my $group = $kdbx->add_group(
-        name => 'Passwords',
-    );
+my $group = $kdbx->add_group(
+    name => 'Passwords',
+);
 
-    my $entry = $group->add_entry(
-        title    => 'My Bank',
-        password => 's3cr3t',
-    );
+my $entry = $group->add_entry(
+    title    => 'My Bank',
+    password => 's3cr3t',
+);
 
-    $kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
+$kdbx->dump_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
 
-    $kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
+$kdbx = File::KDBX->load_file('passwords.kdbx', 'M@st3rP@ssw0rd!');
 
-    $kdbx->entries->each(sub {
-        my ($entry) = @_;
-        say 'Entry: ', $entry->title;
-    });
+$kdbx->entries->each(sub {
+    my ($entry) = @_;
+    say 'Entry: ', $entry->title;
+});
+```
 
 See ["RECIPES"](#recipes) for more examples.
 
 # DESCRIPTION
 
-**File::KDBX** provides everything you need to work with a KDBX database. A KDBX database is a hierarchical
+**File::KDBX** provides everything you need to work with KDBX databases. A KDBX database is a hierarchical
 object database which is commonly used to store secret information securely. It was developed for the KeePass
 password safe. See ["Introduction to KDBX"](#introduction-to-kdbx) for more information about KDBX.
 
-This module lets you query entries, create new entries, delete entries and modify entries. The distribution
-also includes various parsers and generators for serializing and persisting databases.
+This module lets you query entries, create new entries, delete entries, modify entries and more. The
+distribution also includes various parsers and generators for serializing and persisting databases.
 
-This design of this software was influenced by the [KeePassXC](https://github.com/keepassxreboot/keepassxc)
+The design of this software was influenced by the [KeePassXC](https://github.com/keepassxreboot/keepassxc)
 implementation of KeePass as well as the [File::KeePass](https://metacpan.org/pod/File%3A%3AKeePass) module. **File::KeePass** is an alternative module
 that works well in most cases but has a small backlog of bugs and security issues and also does not work with
 newer KDBX version 4 files. If you're coming here from the **File::KeePass** world, you might be interested in
@@ -56,14 +58,12 @@ minor changes up until a 1.0 release. Breaking changes will be noted in the `Cha
 
 ## Features
 
-This implementation of KDBX supports a lot of features:
-
 - ☑ Read and write KDBX version 3 - version 4.1
 - ☑ Read and write KDB files (requires [File::KeePass](https://metacpan.org/pod/File%3A%3AKeePass))
 - ☑ Unicode character strings
 - ☑ ["Simple Expression"](#simple-expression) Searching
 - ☑ [Placeholders](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#Placeholders) and [field references](#resolve_reference)
-- ☑ [One-time passwords](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#One-time-passwords)
+- ☑ [One-time passwords](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#One-time-Passwords)
 - ☑ [Very secure](#security)
 - ☑ ["Memory Protection"](#memory-protection)
 - ☑ Challenge-response key components, like [YubiKey](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey%3A%3AYubiKey)
@@ -83,7 +83,7 @@ associated with each entry, group and the database as a whole.
 You can think of a KDBX database kind of like a file system, where groups are directories, entries are files,
 and strings and binaries make up a file's contents.
 
-Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e.
+Databases are typically persisted as encrypted, compressed files. They are usually accessed directly (i.e.
 not over a network). The primary focus of this type of database is data security. It is ideal for storing
 relatively small amounts of data (strings and binaries) that must remain secret except to such individuals as
 have the correct _master key_. Even if the database file were to be "leaked" to the public Internet, it
@@ -211,10 +211,6 @@ When a new entry is created, the _UserName_ string will be populated with this v
 
 Timestamp indicating when the default username was last changed.
 
-## maintenance\_history\_days
-
-TODO... not really sure what this is. 😀
-
 ## color
 
 A color associated with the database (in the form `#ffffff` where "f" is a hexidecimal digit). Some agents
@@ -251,7 +247,7 @@ The UUID of a group used to store thrown-away groups and entries.
 
 ## recycle\_bin\_changed
 
-Timestamp indicating when the recycle bin was last changed.
+Timestamp indicating when the recycle bin group was last changed.
 
 ## entry\_templates\_group
 
@@ -271,11 +267,15 @@ The UUID of the group visible at the top of the list.
 
 ## history\_max\_items
 
-The maximum number of historical entries allowed to be saved for each entry.
+The maximum number of historical entries that should be kept for each entry. Default is 10.
 
 ## history\_max\_size
 
-The maximum total size (in bytes) that each individual entry's history is allowed to grow.
+The maximum total size (in bytes) that each individual entry's history is allowed to grow. Default is 6 MiB.
+
+## maintenance\_history\_days
+
+The maximum age (in days) historical entries should be kept. Default it 365.
 
 ## settings\_changed
 
@@ -305,14 +305,18 @@ Alias of the ["memory\_protection"](#memory_protection) setting for the _Notes_
 
 ## new
 
-    $kdbx = File::KDBX->new(%attributes);
-    $kdbx = File::KDBX->new($kdbx); # copy constructor
+```
+$kdbx = File::KDBX->new(%attributes);
+$kdbx = File::KDBX->new($kdbx); # copy constructor
+```
 
 Construct a new [File::KDBX](https://metacpan.org/pod/File%3A%3AKDBX).
 
 ## init
 
-    $kdbx = $kdbx->init(%attributes);
+```
+$kdbx = $kdbx->init(%attributes);
+```
 
 Initialize a [File::KDBX](https://metacpan.org/pod/File%3A%3AKDBX) with a set of attributes. Returns itself to allow method chaining.
 
@@ -320,15 +324,19 @@ This is called by ["new"](#new).
 
 ## reset
 
-    $kdbx = $kdbx->reset;
+```
+$kdbx = $kdbx->reset;
+```
 
 Set a [File::KDBX](https://metacpan.org/pod/File%3A%3AKDBX) to an empty state, ready to load a KDBX file or build a new one. Returns itself to allow
 method chaining.
 
 ## clone
 
-    $kdbx_copy = $kdbx->clone;
-    $kdbx_copy = File::KDBX->new($kdbx);
+```
+$kdbx_copy = $kdbx->clone;
+$kdbx_copy = File::KDBX->new($kdbx);
+```
 
 Clone a [File::KDBX](https://metacpan.org/pod/File%3A%3AKDBX). The clone will be an exact copy and completely independent of the original.
 
@@ -340,21 +348,23 @@ Clone a [File::KDBX](https://metacpan.org/pod/File%3A%3AKDBX). The clone will be
 
 ## load\_handle
 
-    $kdbx = KDBX::File->load(\$string, $key);
-    $kdbx = KDBX::File->load(*IO, $key);
-    $kdbx = KDBX::File->load($filepath, $key);
-    $kdbx->load(...);           # also instance method
+```
+$kdbx = KDBX::File->load(\$string, $key);
+$kdbx = KDBX::File->load(*IO, $key);
+$kdbx = KDBX::File->load($filepath, $key);
+$kdbx->load(...);           # also instance method
 
-    $kdbx = File::KDBX->load_string($string, $key);
-    $kdbx = File::KDBX->load_string(\$string, $key);
-    $kdbx->load_string(...);    # also instance method
+$kdbx = File::KDBX->load_string($string, $key);
+$kdbx = File::KDBX->load_string(\$string, $key);
+$kdbx->load_string(...);    # also instance method
 
-    $kdbx = File::KDBX->load_file($filepath, $key);
-    $kdbx->load_file(...);      # also instance method
+$kdbx = File::KDBX->load_file($filepath, $key);
+$kdbx->load_file(...);      # also instance method
 
-    $kdbx = File::KDBX->load_handle($fh, $key);
-    $kdbx = File::KDBX->load_handle(*IO, $key);
-    $kdbx->load_handle(...);    # also instance method
+$kdbx = File::KDBX->load_handle($fh, $key);
+$kdbx = File::KDBX->load_handle(*IO, $key);
+$kdbx->load_handle(...);    # also instance method
+```
 
 Load a KDBX file from a string buffer, IO handle or file from a filesystem.
 
@@ -368,17 +378,19 @@ Load a KDBX file from a string buffer, IO handle or file from a filesystem.
 
 ## dump\_handle
 
-    $kdbx->dump(\$string, $key);
-    $kdbx->dump(*IO, $key);
-    $kdbx->dump($filepath, $key);
+```
+$kdbx->dump(\$string, $key);
+$kdbx->dump(*IO, $key);
+$kdbx->dump($filepath, $key);
 
-    $kdbx->dump_string(\$string, $key);
-    \$string = $kdbx->dump_string($key);
+$kdbx->dump_string(\$string, $key);
+\$string = $kdbx->dump_string($key);
 
-    $kdbx->dump_file($filepath, $key);
+$kdbx->dump_file($filepath, $key);
 
-    $kdbx->dump_handle($fh, $key);
-    $kdbx->dump_handle(*IO, $key);
+$kdbx->dump_handle($fh, $key);
+$kdbx->dump_handle(*IO, $key);
+```
 
 Dump a KDBX file to a string buffer, IO handle or file in a filesystem.
 
@@ -386,17 +398,21 @@ Dump a KDBX file to a string buffer, IO handle or file in a filesystem.
 
 ## user\_agent\_string
 
-    $string = $kdbx->user_agent_string;
+```perl
+$string = $kdbx->user_agent_string;
+```
 
 Get a text string identifying the database client software.
 
 ## memory\_protection
 
-    \%settings = $kdbx->memory_protection
-    $kdbx->memory_protection(\%settings);
+```perl
+\%settings = $kdbx->memory_protection
+$kdbx->memory_protection(\%settings);
 
-    $bool = $kdbx->memory_protection($string_key);
-    $kdbx->memory_protection($string_key => $bool);
+$bool = $kdbx->memory_protection($string_key);
+$kdbx->memory_protection($string_key => $bool);
+```
 
 Get or set memory protection settings. This globally (for the whole database) configures whether and which of
 the standard strings should be memory-protected. The default setting is to memory-protect only _Password_
@@ -407,7 +423,9 @@ over these global settings.
 
 ## minimum\_version
 
-    $version = $kdbx->minimum_version;
+```
+$version = $kdbx->minimum_version;
+```
 
 Determine the minimum file version required to save a database losslessly. Using certain databases features
 might increase this value. For example, setting the KDF to Argon2 will increase the minimum version to at
@@ -424,8 +442,10 @@ data loss. A database will never be automatically downgraded.
 
 ## root
 
-    $group = $kdbx->root;
-    $kdbx->root($group);
+```
+$group = $kdbx->root;
+$kdbx->root($group);
+```
 
 Get or set a database's root group. You don't necessarily need to explicitly create or set a root group
 because it autovivifies when adding entries and groups to the database.
@@ -433,18 +453,21 @@ because it autovivifies when adding entries and groups to the database.
 Every database has only a single root group at a time. Some old KDB files might have multiple root groups.
 When reading such files, a single implicit root group is created to contain the actual root groups. When
 writing to such a format, if the root group looks like it was implicitly created then it won't be written and
-the resulting file might have multiple root groups. This allows working with older files without changing
-their written internal structure while still adhering to modern semantics while the database is opened.
+the resulting file might have multiple root groups, as it was before loading. This allows working with older
+files without changing their written internal structure while still adhering to modern semantics while the
+database is opened.
 
 The root group of a KDBX database contains all of the database's entries and other groups. If you replace the
 root group, you are essentially replacing the entire database contents with something else.
 
 ## trace\_lineage
 
-    \@lineage = $kdbx->trace_lineage($group);
-    \@lineage = $kdbx->trace_lineage($group, $base_group);
-    \@lineage = $kdbx->trace_lineage($entry);
-    \@lineage = $kdbx->trace_lineage($entry, $base_group);
+```
+\@lineage = $kdbx->trace_lineage($group);
+\@lineage = $kdbx->trace_lineage($group, $base_group);
+\@lineage = $kdbx->trace_lineage($entry);
+\@lineage = $kdbx->trace_lineage($entry, $base_group);
+```
 
 Get the direct line of ancestors from `$base_group` (default: the root group) to a group or entry. The
 lineage includes the base group but _not_ the target group or entry. Returns `undef` if the target is not in
@@ -452,47 +475,59 @@ the database structure.
 
 ## recycle\_bin
 
-    $group = $kdbx->recycle_bin;
-    $kdbx->recycle_bin($group);
+```
+$group = $kdbx->recycle_bin;
+$kdbx->recycle_bin($group);
+```
 
 Get or set the recycle bin group. Returns `undef` if there is no recycle bin and ["recycle\_bin\_enabled"](#recycle_bin_enabled) is
 false, otherwise the current recycle bin or an autovivified recycle bin group is returned.
 
 ## entry\_templates
 
-    $group = $kdbx->entry_templates;
-    $kdbx->entry_templates($group);
+```
+$group = $kdbx->entry_templates;
+$kdbx->entry_templates($group);
+```
 
 Get or set the entry templates group. May return `undef` if unset.
 
 ## last\_selected
 
-    $group = $kdbx->last_selected;
-    $kdbx->last_selected($group);
+```
+$group = $kdbx->last_selected;
+$kdbx->last_selected($group);
+```
 
 Get or set the last selected group. May return `undef` if unset.
 
 ## last\_top\_visible
 
-    $group = $kdbx->last_top_visible;
-    $kdbx->last_top_visible($group);
+```
+$group = $kdbx->last_top_visible;
+$kdbx->last_top_visible($group);
+```
 
 Get or set the last top visible group. May return `undef` if unset.
 
 ## add\_group
 
-    $kdbx->add_group($group);
-    $kdbx->add_group(%group_attributes, %options);
+```
+$kdbx->add_group($group);
+$kdbx->add_group(%group_attributes, %options);
+```
 
 Add a group to a database. This is equivalent to identifying a parent group and calling
 ["add\_group" in File::KDBX::Group](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AGroup#add_group) on the parent group, forwarding the arguments. Available options:
 
-- `group` (aka `parent`) - Group object or group UUID to add the group to (default: root group)
+- `group` - Group object or group UUID to add the group to (default: root group)
 
 ## groups
 
-    \&iterator = $kdbx->groups(%options);
-    \&iterator = $kdbx->groups($base_group, %options);
+```
+\&iterator = $kdbx->groups(%options);
+\&iterator = $kdbx->groups($base_group, %options);
+```
 
 Get an [File::KDBX::Iterator](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AIterator) over _groups_ within a database. Options:
 
@@ -502,18 +537,22 @@ Get an [File::KDBX::Iterator](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AItera
 
 ## add\_entry
 
-    $kdbx->add_entry($entry, %options);
-    $kdbx->add_entry(%entry_attributes, %options);
+```
+$kdbx->add_entry($entry, %options);
+$kdbx->add_entry(%entry_attributes, %options);
+```
 
 Add a entry to a database. This is equivalent to identifying a parent group and calling
 ["add\_entry" in File::KDBX::Group](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AGroup#add_entry) on the parent group, forwarding the arguments. Available options:
 
-- `group` (aka `parent`) - Group object or group UUID to add the entry to (default: root group)
+- `group` - Group object or group UUID to add the entry to (default: root group)
 
 ## entries
 
-    \&iterator = $kdbx->entries(%options);
-    \&iterator = $kdbx->entries($base_group, %options);
+```
+\&iterator = $kdbx->entries(%options);
+\&iterator = $kdbx->entries($base_group, %options);
+```
 
 Get an [File::KDBX::Iterator](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AIterator) over _entries_ within a database. Supports the same options as ["groups"](#groups),
 plus some new ones:
@@ -524,8 +563,10 @@ plus some new ones:
 
 ## objects
 
-    \&iterator = $kdbx->objects(%options);
-    \&iterator = $kdbx->objects($base_group, %options);
+```
+\&iterator = $kdbx->objects(%options);
+\&iterator = $kdbx->objects($base_group, %options);
+```
 
 Get an [File::KDBX::Iterator](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AIterator) over _objects_ within a database. Groups and entries are considered objects,
 so this is essentially a combination of ["groups"](#groups) and ["entries"](#entries). This won't often be useful, but it can be
@@ -533,23 +574,29 @@ convenient for maintenance tasks. This method takes the same options as ["groups
 
 ## custom\_icon
 
-    \%icon = $kdbx->custom_icon($uuid);
-    $kdbx->custom_icon($uuid => \%icon);
-    $kdbx->custom_icon(%icon);
-    $kdbx->custom_icon(uuid => $value, %icon);
+```perl
+\%icon = $kdbx->custom_icon($uuid);
+$kdbx->custom_icon($uuid => \%icon);
+$kdbx->custom_icon(%icon);
+$kdbx->custom_icon(uuid => $value, %icon);
+```
 
 Get or set custom icons.
 
 ## custom\_icon\_data
 
-    $image_data = $kdbx->custom_icon_data($uuid);
+```
+$image_data = $kdbx->custom_icon_data($uuid);
+```
 
 Get a custom icon image data.
 
 ## add\_custom\_icon
 
-    $uuid = $kdbx->add_custom_icon($image_data, %attributes);
-    $uuid = $kdbx->add_custom_icon(%attributes);
+```
+$uuid = $kdbx->add_custom_icon($image_data, %attributes);
+$uuid = $kdbx->add_custom_icon(%attributes);
+```
 
 Add a custom icon and get its UUID. If not provided, a random UUID will be generated. Possible attributes:
 
@@ -560,19 +607,23 @@ Add a custom icon and get its UUID. If not provided, a random UUID will be gener
 
 ## remove\_custom\_icon
 
-    $kdbx->remove_custom_icon($uuid);
+```
+$kdbx->remove_custom_icon($uuid);
+```
 
 Remove a custom icon.
 
 ## custom\_data
 
-    \%all_data = $kdbx->custom_data;
-    $kdbx->custom_data(\%all_data);
+```perl
+\%all_data = $kdbx->custom_data;
+$kdbx->custom_data(\%all_data);
 
-    \%data = $kdbx->custom_data($key);
-    $kdbx->custom_data($key => \%data);
-    $kdbx->custom_data(%data);
-    $kdbx->custom_data(key => $value, %data);
+\%data = $kdbx->custom_data($key);
+$kdbx->custom_data($key => \%data);
+$kdbx->custom_data(%data);
+$kdbx->custom_data(key => $value, %data);
+```
 
 Get and set custom data. Custom data is metadata associated with a database.
 
@@ -584,21 +635,27 @@ Each data item can have a few attributes associated with it.
 
 ## custom\_data\_value
 
-    $value = $kdbx->custom_data_value($key);
+```
+$value = $kdbx->custom_data_value($key);
+```
 
 Exactly the same as ["custom\_data"](#custom_data) except returns just the custom data's value rather than a structure of
 attributes. This is a shortcut for:
 
-    my $data = $kdbx->custom_data($key);
-    my $value = defined $data ? $data->{value} : undef;
+```perl
+my $data = $kdbx->custom_data($key);
+my $value = defined $data ? $data->{value} : undef;
+```
 
 ## public\_custom\_data
 
-    \%all_data = $kdbx->public_custom_data;
-    $kdbx->public_custom_data(\%all_data);
+```perl
+\%all_data = $kdbx->public_custom_data;
+$kdbx->public_custom_data(\%all_data);
 
-    $value = $kdbx->public_custom_data($key);
-    $kdbx->public_custom_data($key => $value);
+$value = $kdbx->public_custom_data($key);
+$kdbx->public_custom_data($key => $value);
+```
 
 Get and set public custom data. Public custom data is similar to custom data but different in some important
 ways. Public custom data:
@@ -609,7 +666,9 @@ ways. Public custom data:
 
 ## add\_deleted\_object
 
-    $kdbx->add_deleted_object($uuid);
+```
+$kdbx->add_deleted_object($uuid);
+```
 
 Add a UUID to the deleted objects list. This list is used to support automatic database merging.
 
@@ -618,7 +677,9 @@ are removed.
 
 ## remove\_deleted\_object
 
-    $kdbx->remove_deleted_object($uuid);
+```
+$kdbx->remove_deleted_object($uuid);
+```
 
 Remove a UUID from the deleted objects list. This list is used to support automatic database merging.
 
@@ -632,8 +693,10 @@ if you don't need merging then you can clear deleted objects to reduce the datab
 
 ## resolve\_reference
 
-    $string = $kdbx->resolve_reference($reference);
-    $string = $kdbx->resolve_reference($wanted, $search_in, $expression);
+```
+$string = $kdbx->resolve_reference($reference);
+$string = $kdbx->resolve_reference($wanted, $search_in, $expression);
+```
 
 Resolve a [field reference](https://keepass.info/help/base/fieldrefs.html). A field reference is a kind of
 string placeholder. You can use a field reference to refer directly to a standard field within an entry. Field
@@ -661,22 +724,28 @@ Examples:
 
 To get the value of the _UserName_ string of the first entry with "My Bank" in the title:
 
-    my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
-    # OR the {REF:...} wrapper is optional
-    my $username = $kdbx->resolve_reference('U@T:"My Bank"');
-    # OR separate the arguments
-    my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
+```perl
+my $username = $kdbx->resolve_reference('{REF:U@T:"My Bank"}');
+# OR the {REF:...} wrapper is optional
+my $username = $kdbx->resolve_reference('U@T:"My Bank"');
+# OR separate the arguments
+my $username = $kdbx->resolve_reference(U => T => '"My Bank"');
+```
 
 Note how the text is a ["Simple Expression"](#simple-expression), so search terms with spaces must be surrounded in double
 quotes.
 
 To get the _Password_ string of a specific entry (identified by its UUID):
 
-    my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
+```perl
+my $password = $kdbx->resolve_reference('{REF:P@I:46C9B1FFBD4ABC4BBB260C6190BAD20C}');
+```
 
 ## lock
 
-    $kdbx->lock;
+```
+$kdbx->lock;
+```
 
 Encrypt all protected binaries strings in a database. The encrypted strings are stored in
 a [File::KDBX::Safe](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ASafe) associated with the database and the actual strings will be replaced with `undef` to
@@ -687,14 +756,18 @@ added after the last time the database was locked.
 
 ## unlock
 
-    $kdbx->unlock;
+```
+$kdbx->unlock;
+```
 
 Decrypt all protected strings in a database, replacing `undef` placeholders with unprotected values. Returns
 itself to allow method chaining.
 
 ## unlock\_scoped
 
-    $guard = $kdbx->unlock_scoped;
+```
+$guard = $kdbx->unlock_scoped;
+```
 
 Unlock a database temporarily, relocking when the guard is released (typically at the end of a scope). Returns
 `undef` if the database is already unlocked.
@@ -703,15 +776,19 @@ See ["lock"](#lock) and ["unlock"](#unlock).
 
 ## peek
 
-    $string = $kdbx->peek(\%string);
-    $string = $kdbx->peek(\%binary);
+```
+$string = $kdbx->peek(\%string);
+$string = $kdbx->peek(\%binary);
+```
 
 Peek at the value of a protected string or binary without unlocking the whole database. The argument can be
 a string or binary hashref as returned by ["string" in File::KDBX::Entry](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#string) or ["binary" in File::KDBX::Entry](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#binary).
 
 ## is\_locked
 
-    $bool = $kdbx->is_locked;
+```
+$bool = $kdbx->is_locked;
+```
 
 Get whether or not a database's strings are memory-protected. If this is true, then some or all of the
 protected strings within the database will be unavailable (literally have `undef` values) until ["unlock"](#unlock) is
@@ -719,25 +796,33 @@ called.
 
 ## remove\_empty\_groups
 
-    $kdbx->remove_empty_groups;
+```
+$kdbx->remove_empty_groups;
+```
 
 Remove groups with no subgroups and no entries.
 
 ## remove\_unused\_icons
 
-    $kdbx->remove_unused_icons;
+```perl
+$kdbx->remove_unused_icons;
+```
 
 Remove icons that are not associated with any entry or group in the database.
 
 ## remove\_duplicate\_icons
 
-    $kdbx->remove_duplicate_icons;
+```
+$kdbx->remove_duplicate_icons;
+```
 
 Remove duplicate icons as determined by hashing the icon data.
 
 ## prune\_history
 
-    $kdbx->prune_history(%options);
+```
+$kdbx->prune_history(%options);
+```
 
 Remove just as many older historical entries as necessary to get under certain limits.
 
@@ -747,7 +832,9 @@ Remove just as many older historical entries as necessary to get under certain l
 
 ## randomize\_seeds
 
-    $kdbx->randomize_seeds;
+```
+$kdbx->randomize_seeds;
+```
 
 Set various keys, seeds and IVs to random values. These values are used by the cryptographic functions that
 secure the database when dumped. The attributes that will be randomized are:
@@ -763,31 +850,39 @@ You normally do not need to call this method explicitly because the dumper does
 
 ## key
 
-    $key = $kdbx->key;
-    $key = $kdbx->key($key);
-    $key = $kdbx->key($primitive);
+```
+$key = $kdbx->key;
+$key = $kdbx->key($key);
+$key = $kdbx->key($primitive);
+```
 
 Get or set a [File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey). This is the master key (e.g. a password or a key file that can decrypt
-a database). See ["new" in File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#new) for an explanation of what the primitive can be.
+a database). You can also pass a primitive that can be cast to a **Key**. See ["new" in File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#new) for an
+explanation of what the primitive can be.
 
 You generally don't need to call this directly because you can provide the key directly to the loader or
 dumper when loading or dumping a KDBX file.
 
 ## composite\_key
 
-    $key = $kdbx->composite_key($key);
-    $key = $kdbx->composite_key($primitive);
+```
+$key = $kdbx->composite_key($key);
+$key = $kdbx->composite_key($primitive);
+```
 
-Construct a [File::KDBX::Key::Composite](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey%3A%3AComposite) from a primitive. See ["new" in File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#new) for an explanation of
-what the primitive can be. If the primitive does not represent a composite key, it will be wrapped.
+Construct a [File::KDBX::Key::Composite](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey%3A%3AComposite) from a **Key** or primitive. See ["new" in File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKey#new) for an
+explanation of what the primitive can be. If the primitive does not represent a composite key, it will be
+wrapped.
 
-You generally don't need to call this directly. The parser and writer use it to transform a master key into
+You generally don't need to call this directly. The loader and dumper use it to transform a master key into
 a raw encryption key.
 
 ## kdf
 
-    $kdf = $kdbx->kdf(%options);
-    $kdf = $kdbx->kdf(\%parameters, %options);
+```
+$kdf = $kdbx->kdf(%options);
+$kdf = $kdbx->kdf(\%parameters, %options);
+```
 
 Get a [File::KDBX::KDF](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKDF) (key derivation function).
 
@@ -797,8 +892,10 @@ Options:
 
 ## cipher
 
-    $cipher = $kdbx->cipher(key => $key);
-    $cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
+```perl
+$cipher = $kdbx->cipher(key => $key);
+$cipher = $kdbx->cipher(key => $key, iv => $iv, uuid => $uuid);
+```
 
 Get a [File::KDBX::Cipher](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ACipher) capable of encrypting and decrypting the body of a database file.
 
@@ -808,13 +905,15 @@ cipher), not a [File::KDBX::Key](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AKe
 If not passed, the UUID comes from `$kdbx->headers->{cipher_id}` and the encryption IV comes from
 `$kdbx->headers->{encryption_iv}`.
 
-You generally don't need to call this directly. The parser and writer use it to decrypt and encrypt KDBX
+You generally don't need to call this directly. The loader and dumper use it to decrypt and encrypt KDBX
 files.
 
 ## random\_stream
 
-    $cipher = $kdbx->random_stream;
-    $cipher = $kdbx->random_stream(id => $stream_id, key => $key);
+```perl
+$cipher = $kdbx->random_stream;
+$cipher = $kdbx->random_stream(id => $stream_id, key => $key);
+```
 
 Get a [File::KDBX::Cipher::Stream](https://metacpan.org/pod/File%3A%3AKDBX%3A%3ACipher%3A%3AStream) for decrypting and encrypting protected values.
 
@@ -823,42 +922,48 @@ If not passed, the ID and encryption key comes from `$kdbx->headers->{inner_rand
 `$kdbx->inner_headers->{inner_random_stream_key}` and
 `$kdbx->inner_headers->{inner_random_stream_id}` (respectively) for KDBX4 files.
 
-You generally don't need to call this directly. The parser and writer use it to scramble protected strings.
+You generally don't need to call this directly. The loader and dumper use it to scramble protected strings.
 
 # RECIPES
 
 ## Create a new database
 
-    my $kdbx = File::KDBX->new;
+```perl
+my $kdbx = File::KDBX->new;
 
-    my $group = $kdbx->add_group(name => 'Passwords);
-    my $entry = $group->add_entry(
-        title    => 'WayneCorp',
-        username => 'bwayne',
-        password => 'iambatman',
-        url      => 'https://example.com/login'
-    );
-    $entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
+my $group = $kdbx->add_group(name => 'Passwords);
+my $entry = $group->add_entry(
+    title    => 'WayneCorp',
+    username => 'bwayne',
+    password => 'iambatman',
+    url      => 'https://example.com/login'
+);
+$entry->add_auto_type_window_association('WayneCorp - Mozilla Firefox', '{PASSWORD}{ENTER}');
 
-    $kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
+$kdbx->dump_file('mypasswords.kdbx', 'master password CHANGEME');
+```
 
 ## Read an existing database
 
-    my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
-    $kdbx->unlock;  # cause $entry->password below to be defined
+```perl
+my $kdbx = File::KDBX->load_file('mypasswords.kdbx', 'master password CHANGEME');
+$kdbx->unlock;  # cause $entry->password below to be defined
 
-    $kdbx->entries->each(sub {
-        my ($entry) = @_;
-        say 'Found password for: ', $entry->title;
-        say '  Username: ', $entry->username;
-        say '  Password: ', $entry->password;
-    });
+$kdbx->entries->each(sub {
+    my ($entry) = @_;
+    say 'Found password for: ', $entry->title;
+    say '  Username: ', $entry->username;
+    say '  Password: ', $entry->password;
+});
+```
 
 ## Search for entries
 
-    my @entries = $kdbx->entries(searching => 1)
-        ->grep(title => 'WayneCorp')
-        ->each;     # return all matches
+```perl
+my @entries = $kdbx->entries(searching => 1)
+    ->grep(title => 'WayneCorp')
+    ->each;     # return all matches
+```
 
 The `searching` option limits results to only entries within groups with searching enabled. Other options are
 also available. See ["entries"](#entries).
@@ -867,35 +972,43 @@ See ["QUERY"](#query) for many more query examples.
 
 ## Search for entries by auto-type window association
 
-    my $window_title = 'WayneCorp - Mozilla Firefox';
-
-    my $entries = $kdbx->entries(auto_type => 1)
-        ->filter(sub {
-            my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
-            return [$_, $ata->{keystroke_sequence}] if $ata;
-        })
-        ->each(sub {
-            my ($entry, $keys) = @$_;
-            say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
-        });
+```perl
+my $window_title = 'WayneCorp - Mozilla Firefox';
+
+my $entries = $kdbx->entries(auto_type => 1)
+    ->filter(sub {
+        my ($ata) = grep { $_->{window} =~ /\Q$window_title\E/i } @{$_->auto_type_associations};
+        return [$_, $ata->{keystroke_sequence}] if $ata;
+    })
+    ->each(sub {
+        my ($entry, $keys) = @$_;
+        say 'Entry title: ', $entry->title, ', key sequence: ', $keys;
+    });
+```
 
 Example output:
 
-    Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
+```
+Entry title: WayneCorp, key sequence: {PASSWORD}{ENTER}
+```
 
 ## Remove entries from a database
 
-    $kdbx->entries
-        ->grep(notes => {'=~' => qr/too old/i})
-        ->each(sub { $_->recycle });
+```perl
+$kdbx->entries
+    ->grep(notes => {'=~' => qr/too old/i})
+    ->each(sub { $_->recycle });
+```
 
 Recycle all entries with the string "too old" appearing in the **Notes** string.
 
 ## Remove empty groups
 
-    $kdbx->groups(algorithm => 'dfs')
-        ->where(-true => 'is_empty')
-        ->each('remove');
+```perl
+$kdbx->groups(algorithm => 'dfs')
+    ->where(-true => 'is_empty')
+    ->each('remove');
+```
 
 With the search/iteration `algorithm` set to "dfs", groups will be ordered deepest first and the root group
 will be last. This allows removing groups that only contain empty groups.
@@ -998,9 +1111,11 @@ unfortunately not portable.
 To find things in a KDBX database, you should use a filtered iterator. If you have an iterator, such as
 returned by ["entries"](#entries), ["groups"](#groups) or even ["objects"](#objects) you can filter it using ["where" in File::KDBX::Iterator](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AIterator#where).
 
-    my $filtered_entries = $kdbx->entries->where($query);
+```perl
+my $filtered_entries = $kdbx->entries->where(\&query);
+```
 
-A `$query` is just a subroutine that you can either write yourself or have generated for you from either
+A `\&query` is just a subroutine that you can either write yourself or have generated for you from either
 a ["Simple Expression"](#simple-expression) or ["Declarative Syntax"](#declarative-syntax). It's easier to have your query generated, so I'll cover
 that first.
 
@@ -1019,7 +1134,9 @@ a **scalar reference** to `where`.
 
 To search for all entries in a database with the word "canyon" appearing anywhere in the title:
 
-    my $entries = $kdbx->entries->where(\'canyon', qw[title]);
+```perl
+my $entries = $kdbx->entries->where(\'canyon', qw[title]);
+```
 
 Notice the first argument is a **scalarref**. This disambiguates a simple expression from other types of
 queries covered below.
@@ -1027,24 +1144,32 @@ queries covered below.
 As mentioned, a simple expression can have multiple terms. This simple expression query matches any entry that
 has the words "red" **and** "canyon" anywhere in the title:
 
-    my $entries = $kdbx->entries->where(\'red canyon', qw[title]);
+```perl
+my $entries = $kdbx->entries->where(\'red canyon', qw[title]);
+```
 
 Each term in the simple expression must be found for an entry to match.
 
 To search for entries with "red" in the title but **not** "canyon", just prepend "canyon" with a minus sign:
 
-    my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);
+```perl
+my $entries = $kdbx->entries->where(\'red -canyon', qw[title]);
+```
 
 To search over multiple fields simultaneously, just list them all. To search for entries with "grocery" (but
 not "Foodland") in the title or notes:
 
-    my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);
+```perl
+my $entries = $kdbx->entries->where(\'grocery -Foodland', qw[title notes]);
+```
 
 The default operator is a case-insensitive regexp match, which is fine for searching text loosely. You can use
 just about any binary comparison operator that perl supports. To specify an operator, list it after the simple
 expression. For example, to search for any entry that has been used at least five times:
 
-    my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);
+```perl
+my $entries = $kdbx->entries->where(\5, '>=', qw[usage_count]);
+```
 
 It helps to read it right-to-left, like "usage\_count is greater than or equal to 5".
 
@@ -1052,7 +1177,9 @@ If you find the disambiguating structures to be distracting or confusing, you ca
 ["simple\_expression\_query" in File::KDBX::Util](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AUtil#simple_expression_query) function as a more intuitive alternative. The following example is
 equivalent to the previous:
 
-    my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));
+```perl
+my $entries = $kdbx->entries->where(simple_expression_query(5, '>=', qw[usage_count]));
+```
 
 ## Declarative Syntax
 
@@ -1061,7 +1188,9 @@ familiar with that module. Just learn by examples here.
 
 To search for all entries in a database titled "My Bank":
 
-    my $entries = $kdbx->entries->where({ title => 'My Bank' });
+```perl
+my $entries = $kdbx->entries->where({ title => 'My Bank' });
+```
 
 The query here is `{ title => 'My Bank' }`. A hashref can contain key-value pairs where the key is an
 attribute of the thing being searched for (in this case an entry) and the value is what you want the thing's
@@ -1073,26 +1202,32 @@ A hashref can contain multiple attributes. The search candidate will be a match
 attributes are equal to their respective values. For example, to search for all entries with a particular URL
 **AND** username:
 
-    my $entries = $kdbx->entries->where({
-        url      => 'https://example.com',
-        username => 'neo',
-    });
+```perl
+my $entries = $kdbx->entries->where({
+    url      => 'https://example.com',
+    username => 'neo',
+});
+```
 
 To search for entries matching _any_ criteria, just change the hashref to an arrayref. To search for entries
 with a particular URL **OR** username:
 
-    my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
-        url      => 'https://example.com',
-        username => 'neo',
-    ]);
+```perl
+my $entries = $kdbx->entries->where([ # <-- Notice the square bracket
+    url      => 'https://example.com',
+    username => 'neo',
+]);
+```
 
 You can use different operators to test different types of attributes. The ["icon\_id" in File::KDBX::Entry](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AEntry#icon_id)
 attribute is a number, so we should use a number comparison operator. To find entries using the smartphone
 icon:
 
-    my $entries = $kdbx->entries->where({
-        icon_id => { '==', ICON_SMARTPHONE },
-    });
+```perl
+my $entries = $kdbx->entries->where({
+    icon_id => { '==', ICON_SMARTPHONE },
+});
+```
 
 Note: ["ICON\_SMARTPHONE" in File::KDBX::Constants](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants#ICON_SMARTPHONE) is just a constant from [File::KDBX::Constants](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AConstants). It isn't
 special to this example or to queries generally. We could have just used a literal number.
@@ -1110,7 +1245,7 @@ operators are:
 - `==` - Number equal
 - `!=` - Number not equal
 - `<` - Number less than
-- `>`> - Number greater than
+- `>` - Number greater than
 - `<=` - Number less than or equal
 - `>=` - Number less than or equal
 - `=~` - String match regular expression
@@ -1133,11 +1268,13 @@ Other special operators:
 Let's see another example using an explicit operator. To find all groups except one in particular (identified
 by its ["uuid" in File::KDBX::Group](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AGroup#uuid)), we can use the `ne` (string not equal) operator:
 
-    my $groups = $kdbx->groups->where(
-        uuid => {
-            'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
-        },
-    );
+```perl
+my $groups = $kdbx->groups->where(
+    uuid => {
+        'ne' => uuid('596f7520-6172-6520-7370-656369616c2e'),
+    },
+);
+```
 
 Note: ["uuid" in File::KDBX::Util](https://metacpan.org/pod/File%3A%3AKDBX%3A%3AUtil#uuid) is a little utility function to convert a UUID in its pretty form into bytes.
 This utility function isn't special to this example or to queries generally. It could have been written with
@@ -1151,34 +1288,42 @@ optional. By default it will only match ALL attributes (as if there were curly-b
 Testing the truthiness of an attribute is a little bit different because it isn't a binary operation. To find
 all entries with the password quality check disabled:
 
-    my $entries = $kdbx->entries->where('!' => 'quality_check');
+```perl
+my $entries = $kdbx->entries->where('!' => 'quality_check');
+```
 
 This time the string after the operator is the attribute name rather than a value to compare the attribute
 against. To test that a boolean value is true, use the `!!` operator (or `-true` if `!!` seems a little too
 weird for your taste):
 
-    my $entries = $kdbx->entries->where('!!'  => 'quality_check');
-    my $entries = $kdbx->entries->where(-true => 'quality_check');  # same thing
+```perl
+my $entries = $kdbx->entries->where('!!'  => 'quality_check');
+my $entries = $kdbx->entries->where(-true => 'quality_check');  # same thing
+```
 
 Yes, there is also a `-false` and a `-not` if you prefer one of those over `!`. `-false` and `-not`
 (along with `-true`) are also special in that you can use them to invert the logic of a subquery. These are
 logically equivalent:
 
-    my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
-    my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });
+```perl
+my $entries = $kdbx->entries->where(-not => { title => 'My Bank' });
+my $entries = $kdbx->entries->where(title => { 'ne' => 'My Bank' });
+```
 
 These special operators become more useful when combined with two more special operators: `-and` and `-or`.
 With these, it is possible to construct more interesting queries with groups of logic. For example:
 
-    my $entries = $kdbx->entries->where({
-        title   => { '=~', qr/bank/ },
-        -not    => {
-            -or     => {
-                notes   => { '=~', qr/business/ },
-                icon_id => { '==', ICON_TRASHCAN_FULL },
-            },
+```perl
+my $entries = $kdbx->entries->where({
+    title   => { '=~', qr/bank/ },
+    -not    => {
+        -or     => {
+            notes   => { '=~', qr/business/ },
+            icon_id => { '==', ICON_TRASHCAN_FULL },
         },
-    });
+    },
+});
+```
 
 In English, find entries where the word "bank" appears anywhere in the title but also do not have either the
 word "business" in the notes or are using the full trashcan icon.
@@ -1193,9 +1338,11 @@ coderef to `where`.
 To review the different types of queries, these are all equivalent to find all entries in the database titled
 "My Bank":
 
-    my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]);     # simple expression
-    my $entries = $kdbx->entries->where(title => 'My Bank');                # declarative syntax
-    my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' });    # subroutine query
+```perl
+my $entries = $kdbx->entries->where(\'"My Bank"', 'eq', qw[title]);     # simple expression
+my $entries = $kdbx->entries->where(title => 'My Bank');                # declarative syntax
+my $entries = $kdbx->entries->where(sub { $_->title eq 'My Bank' });    # subroutine query
+```
 
 This is a trivial example, but of course your subroutine can be arbitrarily complex.
 
@@ -1203,15 +1350,17 @@ All of these query mechanisms described in this section are just tools, each wit
 If the tools are getting in your way, you can of course iterate over the contents of a database and implement
 your own query logic, like this:
 
-    my $entries = $kdbx->entries;
-    while (my $entry = $entries->next) {
-        if (wanted($entry)) {
-            do_something($entry);
-        }
-        else {
-            ...
-        }
+```perl
+my $entries = $kdbx->entries;
+while (my $entry = $entries->next) {
+    if (wanted($entry)) {
+        do_something($entry);
     }
+    else {
+        ...
+    }
+}
+```
 
 ## Iteration
 
@@ -1228,26 +1377,26 @@ When iterating over objects generically, groups always precede their direct entr
 
 If you have a database tree like this:
 
-    Database
-    - Root
-        - Group1
-            - EntryA
-            - Group2
-                - EntryB
-        - Group3
-            - EntryC
-
-IDS order of groups is: Root, Group1, Group2, Group3
-IDS order of entries is: EntryA, EntryB, EntryC
-IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
-
-DFS order of groups is: Group2, Group1, Group3, Root
-DFS order of entries is: EntryB, EntryA, EntryC
-DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
-
-BFS order of groups is: Root, Group1, Group3, Group2
-BFS order of entries is: EntryA, EntryC, EntryB
-BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB
+```
+Database
+- Root
+    - Group1
+        - EntryA
+        - Group2
+            - EntryB
+    - Group3
+        - EntryC
+```
+
+- IDS order of groups is: Root, Group1, Group2, Group3
+- IDS order of entries is: EntryA, EntryB, EntryC
+- IDS order of objects is: Root, Group1, EntryA, Group2, EntryB, Group3, EntryC
+- DFS order of groups is: Group2, Group1, Group3, Root
+- DFS order of entries is: EntryB, EntryA, EntryC
+- DFS order of objects is: Group2, EntryB, Group1, EntryA, Group3, EntryC, Root
+BFS order of groups is: Root, Group1, Group3, Group2
+BFS order of entries is: EntryA, EntryC, EntryB
+BFS order of objects is: Root, Group1, EntryA, Group3, EntryC, Group2, EntryB
 
 # SYNCHRONIZING
 
@@ -1263,53 +1412,65 @@ with these mechanisms, you can skip this section.
 You can catch fatal errors using ["eval" in functions](https://metacpan.org/pod/functions#eval) (or something like [Try::Tiny](https://metacpan.org/pod/Try%3A%3ATiny)) and non-fatal errors using
 `$SIG{__WARN__}` (see ["%SIG" in variables](https://metacpan.org/pod/variables#SIG)). Examples:
 
-    use File::KDBX::Error qw(error);
+```perl
+use File::KDBX::Error qw(error);
 
-    my $key = '';   # uh oh
-    eval {
-        $kdbx->load_file('whatever.kdbx', $key);
-    };
-    if (my $error = error($@)) {
-        handle_missing_key($error) if $error->type eq 'key.missing';
-        $error->throw;
-    }
+my $key = '';   # uh oh
+eval {
+    $kdbx->load_file('whatever.kdbx', $key);
+};
+if (my $error = error($@)) {
+    handle_missing_key($error) if $error->type eq 'key.missing';
+    $error->throw;
+}
+```
 
 or using `Try::Tiny`:
 
-    try {
-        $kdbx->load_file('whatever.kdbx', $key);
-    }
-    catch {
-        handle_error($_);
-    };
+```perl
+try {
+    $kdbx->load_file('whatever.kdbx', $key);
+}
+catch {
+    handle_error($_);
+};
+```
 
 Catching non-fatal errors:
 
-    my @warnings;
-    local $SIG{__WARN__} = sub { push @warnings, $_[0] };
+```perl
+my @warnings;
+local $SIG{__WARN__} = sub { push @warnings, $_[0] };
 
-    $kdbx->load_file('whatever.kdbx', $key);
+$kdbx->load_file('whatever.kdbx', $key);
 
-    handle_warnings(@warnings) if @warnings;
+handle_warnings(@warnings) if @warnings;
+```
 
 By default perl prints warnings to `STDERR` if you don't catch them. If you don't want to catch them and also
 don't want them printed to `STDERR`, you can suppress them lexically (perl v5.28 or higher required):
 
-    {
-        no warnings 'File::KDBX';
-        ...
-    }
+```
+{
+    no warnings 'File::KDBX';
+    ...
+}
+```
 
 or locally:
 
-    {
-        local $File::KDBX::WARNINGS = 0;
-        ...
-    }
+```
+{
+    local $File::KDBX::WARNINGS = 0;
+    ...
+}
+```
 
 or globally in your program:
 
-    $File::KDBX::WARNINGS = 0;
+```
+$File::KDBX::WARNINGS = 0;
+```
 
 You cannot suppress fatal errors, and if you don't catch them your program will exit.
 
This page took 0.053224 seconds and 4 git commands to generate.