1File::KDBX::Util(3) User Contributed Perl Documentation File::KDBX::Util(3)
2
6 File::KDBX::Util - Utility functions for working with KDBX files
7
9 version 0.906
10
12 load_xs
13 $bool = load_xs();
14 $bool = load_xs($version);
15 Attempt to load File::KDBX::XS. Return truthy if it is loaded. If
17 $version is given, it will check that at least the given version is
18 loaded.
19 assert
21 assert { ... };
22 Write an executable comment. Only executed if "DEBUG" is set in the
24 environment.
25 can_fork
27 $bool = can_fork;
28 Determine if perl can fork, with logic lifted from "CAN_FORK" in
30 Test2::Util.
31 clone
33 $clone = clone($thing);
34 Clone deeply. This is an unadorned alias to Storable "dclone".
36 clone_nomagic
38 $clone = clone_nomagic($thing);
39 Clone deeply without keeping [most of] the magic.
41 WARNING: At the moment the implementation is naïve and won't respond
43 well to nontrivial data or recursive structures.
44 DEBUG
46 Constant number indicating the level of debuggingness.
47 dumper
49 $str = dumper $thing;
50 dumper $thing; # in void context, prints to STDERR
51 Like Data::Dumper but slightly terser in some cases relevent to
53 File::KDBX.
54 empty
56 nonempty
57 $bool = empty $thing;
58 $bool = nonempty $thing;
60 Test whether a thing is empty (or nonempty). An empty thing is one of
62 these:
63 • nonexistent
65 • "undef"
67 • zero-length string
69 • zero-length array
71 • hash with zero keys
73 • reference to an empty thing (recursive)
75 Note in particular that zero 0 is not considered empty because it is an
77 actual value.
78 erase
80 erase($string, ...);
81 erase(\$string, ...);
82 Overwrite the memory used by one or more string.
84 erase_scoped
86 $scope_guard = erase_scoped($string, ...);
87 $scope_guard = erase_scoped(\$string, ...);
88 undef $scope_guard; # erase happens here
89 Get a scope guard that will cause scalars to be erased later (i.e. when
91 the scope ends). This is useful if you want to make sure a string gets
92 erased after you're done with it, even if the scope ends abnormally.
93 See "erase".
95 extends
97 extends $class;
98 Set up the current module to inheret from another module.
100 has
102 has $name => %options;
103 Create an attribute getter/setter. Possible options:
105 • "is" - Either "rw" (default) or "ro"
107 • "default" - Default value
109 • "coerce" - Coercive function
111 format_uuid
113 $string_uuid = format_uuid($raw_uuid);
114 $string_uuid = format_uuid($raw_uuid, $delimiter);
115 Format a 128-bit UUID (given as a string of 16 octets) into a
117 hexidecimal string, optionally with a delimiter to break up the UUID
118 visually into five parts. Examples:
119 my $uuid = uuid('01234567-89AB-CDEF-0123-456789ABCDEF');
121 say format_uuid($uuid); # -> 0123456789ABCDEF0123456789ABCDEF
122 say format_uuid($uuid, '-'); # -> 01234567-89AB-CDEF-0123-456789ABCDEF
123 This is the inverse of "uuid".
125 generate_uuid
127 $uuid = generate_uuid;
128 $uuid = generate_uuid(\%set);
129 $uuid = generate_uuid(\&test_uuid);
130 Generate a new random UUID. It's pretty unlikely that this will
132 generate a repeat, but if you're worried about that you can provide
133 either a set of existing UUIDs (as a hashref where the keys are the
134 elements of a set) or a function to check for existing UUIDs, and this
135 will be sure to not return a UUID already in provided set. Perhaps an
136 example will make it clear:
137 my %uuid_set = (
139 uuid('12345678-9ABC-DEFG-1234-56789ABCDEFG') => 'whatever',
140 );
141 $uuid = generate_uuid(\%uuid_set);
142 # OR
143 $uuid = generate_uuid(sub { !$uuid_set{$_} });
144 Here, $uuid can't be "12345678-9ABC-DEFG-1234-56789ABCDEFG". This
146 example uses "uuid" to easily pack a 16-byte UUID from a literal, but
147 it otherwise is not a consequential part of the example.
148 gunzip
150 $unzipped = gunzip($string);
151 Decompress an octet stream.
153 gzip
155 $zipped = gzip($string);
156 Compress an octet stream.
158 int64
160 $int = int64($string);
161 Get a scalar integer capable of holding 64-bit values, initialized with
163 a given default value. On a 64-bit perl, it will return a regular SvIV.
164 On a 32-bit perl it will return a Math::BigInt.
165 pack_Ql
167 $bytes = pack_Ql($int);
168 Like "pack('Q<', $int)", but also works on 32-bit perls.
170 pack_ql
172 $bytes = pack_ql($int);
173 Like "pack('q<', $int)", but also works on 32-bit perls.
175 unpack_Ql
177 $int = unpack_Ql($bytes);
178 Like "unpack('Q<', $bytes)", but also works on 32-bit perls.
180 unpack_ql
182 $int = unpack_ql($bytes);
183 Like "unpack('q<', $bytes)", but also works on 32-bit perls.
185 is_uuid
187 $bool = is_uuid($thing);
188 Check if a thing is a UUID (i.e. scalar string of length 16).
190 list_attributes
192 @attributes = list_attributes($package);
193 Get a list of attributes for a class.
195 load_optional
197 $package = load_optional($package);
198 Load a module that isn't required but can provide extra functionality.
200 Throw if the module is not available.
201 memoize
203 \&memoized_code = memoize(\&code, ...);
204 Memoize a function. Extra arguments are passed through to &code when it
206 is called.
207 pad_pkcs7
209 $padded_string = pad_pkcs7($string, $block_size),
210 Pad a block using the PKCS#7 method.
212 query
214 $query = query(@where);
215 $query->(\%data);
216 Generate a function that will run a series of tests on a passed hashref
218 and return true or false depending on if the data record in the hash
219 matched the specified logic.
220 The logic can be specified in a manner similar to "WHERE CLAUSES" in
222 SQL::Abstract which was the inspiration for this function, but this
223 code is distinct, supporting an overlapping but not identical feature
224 set and having its own bugs.
225 See "Declarative Syntax" in File::KDBX for examples.
227 query_any
229 Get either a "query" or "simple_expression_query", depending on the
230 arguments.
231 read_all
233 $size = read_all($fh, my $buffer, $size);
234 $size = read_all($fh, my $buffer, $size, $offset);
235 Like "read FILEHANDLE,SCALAR,LENGTH,OFFSET" in perlfunc but returns
237 "undef" if not all $size bytes are read. This is considered an error,
238 distinguishable from other errors by $! not being set.
239 recurse_limit
241 \&limited_code = recurse_limit(\&code);
242 \&limited_code = recurse_limit(\&code, $max_depth);
243 \&limited_code = recurse_limit(\&code, $max_depth, \&error_handler);
244 Wrap a function with a guard to prevent deep recursion.
246 search
248 # Generate a query on-the-fly:
249 \@matches = search(\@records, @where);
250 # Use a pre-compiled query:
252 $query = query(@where);
253 \@matches = search(\@records, $query);
254 # Use a simple expression:
256 \@matches = search(\@records, \'query terms', @fields);
257 \@matches = search(\@records, \'query terms', $operator, @fields);
258 # Use your own subroutine:
260 \@matches = search(\@records, \&query);
261 \@matches = search(\@records, sub { $record = shift; ... });
262 Execute a linear search over an array of records using a "query". A
264 "record" is usually a hash.
265 simple_expression_query
267 $query = simple_expression_query($expression, @fields);
268 $query = simple_expression_query($expression, $operator, @fields);
269 Generate a query, like "query", to be used with "search" but built from
271 a "simple expression" as described here
272 <https://keepass.info/help/base/search.html#mode_se>.
273 An expression is a string with one or more space-separated terms. Terms
275 with spaces can be enclosed in double quotes. Terms are negated if they
276 are prefixed with a minus sign. A record must match every term on at
277 least one of the given fields.
278 snakify
280 $string = snakify($string);
281 Turn a CamelCase string into snake_case.
283 split_url
285 ($scheme, $auth, $host, $port, $path, $query, $hash, $usename, $password) = split_url($url);
286 Split a URL into its parts.
288 For example, "http://user:pass@localhost:4000/path?query#hash" gets
290 split like:
291 • "http"
293 • "user:pass"
295 • "host"
297 • 4000
299 • "/path"
301 • "?query"
303 • "#hash"
305 • "user"
307 • "pass"
309 to_bool
311 to_number
312 to_string
313 to_time
314 to_tristate
315 to_uuid
316 Various typecasting / coercive functions.
317 trim
319 $string = trim($string);
320 The ubiquitous "trim" function. Removes all whitespace from both ends
322 of a string.
323 try_load_optional
325 $package = try_load_optional($package);
326 Try to load a module that isn't required but can provide extra
328 functionality, and return true if successful.
329 uri_escape_utf8
331 $string = uri_escape_utf8($string);
332 Percent-encode arbitrary text strings, like for a URI.
334 uri_unescape_utf8
336 $string = uri_unescape_utf8($string);
337 Inverse of "uri_escape_utf8".
339 uuid
341 $raw_uuid = uuid($string_uuid);
342 Pack a 128-bit UUID (given as a hexidecimal string with optional "-"'s,
344 like "12345678-9ABC-DEFG-1234-56789ABCDEFG") into a string of exactly
345 16 octets.
346 This is the inverse of "format_uuid".
348 UUID_NULL
350 Get the null UUID (i.e. string of 16 null bytes).
351
353 Please report any bugs or feature requests on the bugtracker website
354 <https://github.com/chazmcgarvey/File-KDBX/issues>
355 When submitting a bug or request, please include a test-file or a patch
357 to an existing test-file that illustrates the bug or desired feature.
358
360 Charles McGarvey <ccm@cpan.org>
361
363 This software is copyright (c) 2022 by Charles McGarvey.
364 This is free software; you can redistribute it and/or modify it under
366 the same terms as the Perl 5 programming language system itself.
367perl v5.38.0 2023-09-27 File::KDBX::Util(3)