1File::KDBX::Util(3)   User Contributed Perl Documentation  File::KDBX::Util(3)
2
3
4

NAME

6       File::KDBX::Util - Utility functions for working with KDBX files
7

VERSION

9       version 0.906
10

FUNCTIONS

12   load_xs
13           $bool = load_xs();
14           $bool = load_xs($version);
15
16       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
20   assert
21           assert { ... };
22
23       Write an executable comment. Only executed if "DEBUG" is set in the
24       environment.
25
26   can_fork
27           $bool = can_fork;
28
29       Determine if perl can fork, with logic lifted from "CAN_FORK" in
30       Test2::Util.
31
32   clone
33           $clone = clone($thing);
34
35       Clone deeply. This is an unadorned alias to Storable "dclone".
36
37   clone_nomagic
38           $clone = clone_nomagic($thing);
39
40       Clone deeply without keeping [most of] the magic.
41
42       WARNING: At the moment the implementation is naïve and won't respond
43       well to nontrivial data or recursive structures.
44
45   DEBUG
46       Constant number indicating the level of debuggingness.
47
48   dumper
49           $str = dumper $thing;
50           dumper $thing;  # in void context, prints to STDERR
51
52       Like Data::Dumper but slightly terser in some cases relevent to
53       File::KDBX.
54
55   empty
56   nonempty
57           $bool = empty $thing;
58
59           $bool = nonempty $thing;
60
61       Test whether a thing is empty (or nonempty). An empty thing is one of
62       these:
63
64       •   nonexistent
65
66       •   "undef"
67
68       •   zero-length string
69
70       •   zero-length array
71
72       •   hash with zero keys
73
74       •   reference to an empty thing (recursive)
75
76       Note in particular that zero 0 is not considered empty because it is an
77       actual value.
78
79   erase
80           erase($string, ...);
81           erase(\$string, ...);
82
83       Overwrite the memory used by one or more string.
84
85   erase_scoped
86           $scope_guard = erase_scoped($string, ...);
87           $scope_guard = erase_scoped(\$string, ...);
88           undef $scope_guard; # erase happens here
89
90       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
94       See "erase".
95
96   extends
97           extends $class;
98
99       Set up the current module to inheret from another module.
100
101   has
102           has $name => %options;
103
104       Create an attribute getter/setter. Possible options:
105
106       •   "is" - Either "rw" (default) or "ro"
107
108       •   "default" - Default value
109
110       •   "coerce" - Coercive function
111
112   format_uuid
113           $string_uuid = format_uuid($raw_uuid);
114           $string_uuid = format_uuid($raw_uuid, $delimiter);
115
116       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
120           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
124       This is the inverse of "uuid".
125
126   generate_uuid
127           $uuid = generate_uuid;
128           $uuid = generate_uuid(\%set);
129           $uuid = generate_uuid(\&test_uuid);
130
131       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
138           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
145       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
149   gunzip
150           $unzipped = gunzip($string);
151
152       Decompress an octet stream.
153
154   gzip
155           $zipped = gzip($string);
156
157       Compress an octet stream.
158
159   int64
160           $int = int64($string);
161
162       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
166   pack_Ql
167           $bytes = pack_Ql($int);
168
169       Like "pack('Q<', $int)", but also works on 32-bit perls.
170
171   pack_ql
172           $bytes = pack_ql($int);
173
174       Like "pack('q<', $int)", but also works on 32-bit perls.
175
176   unpack_Ql
177           $int = unpack_Ql($bytes);
178
179       Like "unpack('Q<', $bytes)", but also works on 32-bit perls.
180
181   unpack_ql
182           $int = unpack_ql($bytes);
183
184       Like "unpack('q<', $bytes)", but also works on 32-bit perls.
185
186   is_uuid
187           $bool = is_uuid($thing);
188
189       Check if a thing is a UUID (i.e. scalar string of length 16).
190
191   list_attributes
192           @attributes = list_attributes($package);
193
194       Get a list of attributes for a class.
195
196   load_optional
197           $package = load_optional($package);
198
199       Load a module that isn't required but can provide extra functionality.
200       Throw if the module is not available.
201
202   memoize
203           \&memoized_code = memoize(\&code, ...);
204
205       Memoize a function. Extra arguments are passed through to &code when it
206       is called.
207
208   pad_pkcs7
209           $padded_string = pad_pkcs7($string, $block_size),
210
211       Pad a block using the PKCS#7 method.
212
213   query
214           $query = query(@where);
215           $query->(\%data);
216
217       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
221       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
226       See "Declarative Syntax" in File::KDBX for examples.
227
228   query_any
229       Get either a "query" or "simple_expression_query", depending on the
230       arguments.
231
232   read_all
233           $size = read_all($fh, my $buffer, $size);
234           $size = read_all($fh, my $buffer, $size, $offset);
235
236       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
240   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
245       Wrap a function with a guard to prevent deep recursion.
246
247   search
248           # Generate a query on-the-fly:
249           \@matches = search(\@records, @where);
250
251           # Use a pre-compiled query:
252           $query = query(@where);
253           \@matches = search(\@records, $query);
254
255           # Use a simple expression:
256           \@matches = search(\@records, \'query terms', @fields);
257           \@matches = search(\@records, \'query terms', $operator, @fields);
258
259           # Use your own subroutine:
260           \@matches = search(\@records, \&query);
261           \@matches = search(\@records, sub { $record = shift; ... });
262
263       Execute a linear search over an array of records using a "query". A
264       "record" is usually a hash.
265
266   simple_expression_query
267           $query = simple_expression_query($expression, @fields);
268           $query = simple_expression_query($expression, $operator, @fields);
269
270       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
274       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
279   snakify
280           $string = snakify($string);
281
282       Turn a CamelCase string into snake_case.
283
284   split_url
285           ($scheme, $auth, $host, $port, $path, $query, $hash, $usename, $password) = split_url($url);
286
287       Split a URL into its parts.
288
289       For example, "http://user:pass@localhost:4000/path?query#hash" gets
290       split like:
291
292       •   "http"
293
294       •   "user:pass"
295
296       •   "host"
297
298       •   4000
299
300       •   "/path"
301
302       •   "?query"
303
304       •   "#hash"
305
306       •   "user"
307
308       •   "pass"
309
310   to_bool
311   to_number
312   to_string
313   to_time
314   to_tristate
315   to_uuid
316       Various typecasting / coercive functions.
317
318   trim
319           $string = trim($string);
320
321       The ubiquitous "trim" function. Removes all whitespace from both ends
322       of a string.
323
324   try_load_optional
325           $package = try_load_optional($package);
326
327       Try to load a module that isn't required but can provide extra
328       functionality, and return true if successful.
329
330   uri_escape_utf8
331           $string = uri_escape_utf8($string);
332
333       Percent-encode arbitrary text strings, like for a URI.
334
335   uri_unescape_utf8
336           $string = uri_unescape_utf8($string);
337
338       Inverse of "uri_escape_utf8".
339
340   uuid
341           $raw_uuid = uuid($string_uuid);
342
343       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
347       This is the inverse of "format_uuid".
348
349   UUID_NULL
350       Get the null UUID (i.e. string of 16 null bytes).
351

BUGS

353       Please report any bugs or feature requests on the bugtracker website
354       <https://github.com/chazmcgarvey/File-KDBX/issues>
355
356       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

AUTHOR

360       Charles McGarvey <ccm@cpan.org>
361
363       This software is copyright (c) 2022 by Charles McGarvey.
364
365       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.
367
368
369
370perl v5.36.1                      2023-09-27               File::KDBX::Util(3)
Impressum