lib/App/Access2CSV/Exporter.pm

filter: Statementstmt 100% 457 / 457 Branchbran 100% 120 / 120 Conditioncond 88.3% 53 / 60 MC/DCmcdc 75.0% 27 / 36 Subroutinesub 100% 69 / 69 Podpod 100% 2 / 2 totaltotal 97.8% 728 / 744 CC 88 SCAR 14.9
CC
88
Cov
99%
_export_table
9.0
_csv_filename
9.0
_run_program
8.0
CRAP 4.4
« lib/App/Access2CSV.pm ↑ Summary /usr/local/bin/perldoc »
1 package App::Access2CSV::Exporter;
2  
3 38 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 38 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 38 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 38 ▶use Config;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 # Sub::Private must be in enforce mode before it is loaded, so that
10 # private methods still work through $self->method dispatch
11 38 ▶BEGIN { $Sub::Private::config{mode} = 'enforce' }
Subroutine BEGIN: called CC=1 SCAR=0.0
12  
13 # Inherit i18n() and the protected _croak_i18n/_carp_i18n helpers
14 38 ▶use parent 'App::Access2CSV::I18N';
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 38 ▶use Encode qw(FB_CROAK find_encoding);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 38 ▶use File::Path qw(make_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
18 38 ▶use File::Spec;
Subroutine BEGIN: called CC=1 SCAR=0.0
19 38 ▶use File::Temp;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 38 ▶use File::Which qw(which);
Subroutine BEGIN: called CC=1 SCAR=0.0
21 37 ▶use IPC::Run3 qw(run3);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 36 ▶use Params::Get qw(get_params);
Subroutine BEGIN: called CC=1 SCAR=0.0
23 36 ▶use Params::Validate::Strict qw(validate_strict);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 36 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 36 ▶use Return::Set qw(set_return);
Subroutine BEGIN: called CC=1 SCAR=0.0
26 36 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
27 36 ▶use Sub::Private;
Subroutine BEGIN: called CC=1 SCAR=0.0
28 36 ▶use Sub::Protected;
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 36 our $VERSION = '0.001.1';
31  
32 # Stop Carp from reporting errors against the access-control wrappers
33 36 our @CARP_NOT = qw(Sub::Private Sub::Protected App::Access2CSV::I18N);
34  
35 # Exit statuses returned by run()
36 36 Readonly::Scalar my $EXIT_OK => 0;
37 36 Readonly::Scalar my $EXIT_FAILURE => 1;
38  
39 # The mdbtools programs; mdb-count is only needed for --show-counts
40 36 Readonly::Scalar my $MDB_TABLES => 'mdb-tables';
41 36 Readonly::Scalar my $MDB_EXPORT => 'mdb-export';
42 36 Readonly::Scalar my $MDB_COUNT => 'mdb-count';
43 36 Readonly::Array my @REQUIRED_PROGRAMS => ($MDB_TABLES, $MDB_EXPORT);
44  
45 # Output encodings accepted by --encoding
46 36 Readonly::Scalar my $ENC_UTF8 => 'utf8';
47 36 Readonly::Scalar my $ENC_UTF8_BOM => 'utf8-bom';
48 36 Readonly::Scalar my $ENC_CP1252 => 'cp1252';
49 36 Readonly::Array my @ENCODINGS => ($ENC_UTF8, $ENC_UTF8_BOM, $ENC_CP1252);
50  
51 # Taint mode: a value is untainted only after it has been validated, by
52 # capturing it with this pattern (anything non-empty without a NUL byte:
53 # a NUL cannot be passed to the operating system at all)
54 36 Readonly::Scalar my $UNTAINT_RE => qr/\A([^\x00]+)\z/s;
55  
56 # Environment variables that can change how a program is started (see
57 # perlsec); removed for the mdbtools processes
58 36 Readonly::Array my @UNSAFE_ENV => qw(IFS CDPATH ENV BASH_ENV);
59  
60 # Encoding objects, looked up once: calling Encode::decode/encode by name
61 # repeats the lookup for every line, which made conversion about 4 times
62 # slower on large tables. (Plain lexicals, not Readonly: Readonly's deep
63 # copy could interfere with the objects' internals.)
64 36 my $UTF8_CODEC = find_encoding('UTF-8');
65 36 my $CP1252_CODEC = find_encoding('cp1252');
66  
67 # Byte order mark written at the start of utf8-bom files (for Excel)
68 36 Readonly::Scalar my $UTF8_BOM => "\xEF\xBB\xBF";
69  
70 # Tables Access creates for itself: MSys*, USys* and ~temporary objects
71 36 Readonly::Scalar my $SYSTEM_TABLE_RE => qr/\A(?:MSys|USys|~)/i;
72  
73 # Characters that are illegal in a file name on at least one common OS
74 36 Readonly::Scalar my $UNSAFE_CHARS_RE => qr/[<>:"\/\\|?*\x00-\x1F\x7F]/;
75  
76 # Invisible text-direction controls (LRM, RLM, LRE, RLE, PDF, LRO, RLO,
77 # LRI, RLI, FSI, PDI). They can make a file name display as something
78 # else ("report<RLO>vsc.exe.csv"), so they are unsafe like other control
79 # characters. Matched both as Perl characters and as UTF-8 bytes, since
80 # table names from mdbtools arrive as bytes.
81 36 Readonly::Scalar my $BIDI_CONTROLS_RE => qr/
82 [\x{200E}\x{200F}\x{202A}-\x{202E}\x{2066}-\x{2069}] # as characters
83 | \xE2 \x80 [\x8E\x8F\xAA-\xAE] # as UTF-8: marks, embeddings, overrides
84 | \xE2 \x81 [\xA6-\xA9] # as UTF-8: isolates
85 /x;
86  
87 # Device names Windows reserves whatever the extension (CON.csv is illegal)
88 36 Readonly::Scalar my $RESERVED_NAME_RE => qr/\A(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])\z/i;
89  
90 # Name used when sanitising leaves nothing, and the extension we write
91 36 Readonly::Scalar my $UNNAMED => 'unnamed';
92 36 Readonly::Scalar my $CSV_SUFFIX => '.csv';
93  
94 # Longest file name (before any _2 suffix and ".csv"). Access allows 64
95 # characters, so a longer name comes from a damaged or hostile database.
96 # 64 characters can still be 256 bytes of UTF-8 (emoji), and most file
97 # systems allow 255 bytes per name, so there is a byte limit too, leaving
98 # room for "_" plus a collision number and ".csv"
99 36 Readonly::Scalar my $MAX_NAME_CHARS => 64;
100 36 Readonly::Scalar my $MAX_NAME_BYTES => 240;
101  
102 # Ends option parsing in mdbtools, so a table or database name that
103 # starts with "-" is never taken for an option (glib parses options
104 # anywhere on the command line, not only before the file name)
105 36 Readonly::Scalar my $END_OF_OPTIONS => '--';
106  
107 # Temporary files are hidden and live next to the target for atomic rename
108 36 Readonly::Scalar my $TEMP_TEMPLATE => '.access2csv-XXXXXX';
109  
110 # How much of an unreadable mdb-count answer to quote in the warning
111 36 Readonly::Scalar my $COUNT_SHOWN => 40;
112  
113 # Shown in the dry run's ROWS column when a table could not be counted
114 36 Readonly::Scalar my $UNKNOWN_COUNT => '?';
115  
116 # Dry-run table layout
117 36 Readonly::Scalar my $TABLE_COLUMN_WIDTH => 40;
118 36 Readonly::Scalar my $ROWS_COLUMN_WIDTH => 10;
119 36 Readonly::Scalar my $RULE_WIDTH => 70;
120  
121 # Return schema of run(), shared by its two exits
122 36 Readonly::Hash my %RUN_STATUS_SCHEMA => (type => 'integer', min => $EXIT_OK, max => $EXIT_FAILURE);
123  
124 # Mode bits for new files before the umask is applied
125 36 Readonly::Scalar my $FILE_MODE => oct('666');
126  
127 # Default settings; the flat scalar layout is compatible with Object::Configure
128 36 Readonly::Hash my %DEFAULTS => (
129 output_dir => File::Spec->curdir(),
130 overwrite => 0,
131 verbose => 0,
132 dry_run => 0,
133 show_counts => 0,
134 progress => 1,
135 encoding => $ENC_UTF8,
136 );
137  
138 # Constructor argument schema, shared by new() and the POD
139 36 Readonly::Hash my %NEW_SCHEMA => (
140 output_dir => { type => 'string', min => 1, optional => 1 },
141 tables => { type => 'arrayref', element_type => 'string', optional => 1 },
142 overwrite => { type => 'boolean', optional => 1 },
143 verbose => { type => 'boolean', optional => 1 },
144 dry_run => { type => 'boolean', optional => 1 },
145 show_counts => { type => 'boolean', optional => 1 },
146 progress => { type => 'boolean', optional => 1 },
147 encoding => { type => 'string', memberof => [@ENCODINGS], optional => 1 },
148 logger => { type => 'object', can => ['debug', 'info', 'warn'], optional => 1 },
149 language => { type => 'string', optional => 1 },
150 );
151  
152 =encoding utf8
153  
154 =head1 NAME
155  
156 App::Access2CSV::Exporter - Export the tables of a Microsoft Access database to CSV files
157  
158 =head1 VERSION
159  
160 Version 0.001.1
161  
162 =head1 SYNOPSIS
163  
164 use App::Access2CSV::Exporter;
165  
166 # 1. The simplest case: every table, into the current directory
167 my $exporter = App::Access2CSV::Exporter->new();
168 my $status = $exporter->run('shop.accdb'); # 0 = all OK, 1 = some failed
169  
170 # 2. Some tables, into a directory, for Excel, replacing old files
171 my $exporter = App::Access2CSV::Exporter->new(
172 output_dir => 'exports',
173 tables => ['Customers', 'Orders'],
174 encoding => 'utf8-bom',
175 overwrite => 1,
176 );
177 $exporter->run('shop.accdb');
178  
179 # 3. Only look: print the table list and row counts, write nothing
180 App::Access2CSV::Exporter->new(dry_run => 1, show_counts => 1)->run('shop.accdb');
181  
182 # 4. Inside a larger program: no progress lines, a log, and full
183 # error handling
184 use Log::Abstraction;
185  
186 my $exporter = App::Access2CSV::Exporter->new({
187 output_dir => '/srv/exports',
188 progress => 0,
189 logger => Log::Abstraction->new(logger => '/var/log/export.log'),
190 });
191 my $status = eval { $exporter->run('/data/shop.accdb') };
192 if(!defined $status) {
193 die "Nothing was exported: $@"; # for example, the file is missing
194 } elsif($status == 1) {
195 warn "Some tables were not exported; see the log\n";
196 }
197  
198 =head1 DESCRIPTION
199  
200 This module does the real work of the C<access2csv> program. It writes
201 one CSV file for each table of a Microsoft Access database.
202  
203 It runs three programs from the B<mdbtools> package: C<mdb-tables> (to
204 list the tables), C<mdb-export> (to get each table as CSV) and, only when
205 row counts are wanted, C<mdb-count>. They must be in your C<PATH>.
206  
207 Access's own internal tables (names starting with C<MSys>, C<USys> or
208 C<~>) are skipped.
209  
210 Each file is first written to a hidden temporary file in the output
211 directory, and renamed to its real name only when it is complete. So a
212 failed export never leaves a half-written CSV file, and an old file is
213 only replaced by a complete new one. New files get the usual
214 permissions (0666 minus your umask).
215  
216 An exporter can be used for more than one C<run>. Each C<run> starts
217 again with the same file names, so running twice gives the same files.
218  
219 The mdbtools programs are looked up only in absolute C<PATH> directory, so
220 a program planted in the current directory is never run, and they are
221 started with a cleaned environment (see L<App::Access2CSV/SECURITY>).
222 The module works under taint mode (C<perl -T>). Table names are
223 printed and logged with control characters escaped, so a hostile name
224 cannot send escape sequences to your terminal.
225  
226 Table names and the database path are handed to mdbtools as separate
227 arguments, never through a shell, and after a C<--> marker. So names
228 containing shell characters (C<; | E<gt> $( )>), spaces or newlines, or
229 starting with C<->, are always treated as names, never as commands or
230 options. A table name can never place a file outside the output
231 directory: C</> and C<\> are replaced, and names cannot start with a dot.
232  
233 An existing entry at the target name - including a symbolic link, even a
234 broken one - counts as "already exists". With C<overwrite>, the link
235 itself is replaced; the file it pointed to is never written.
236  
237 The rules for file names are described in
238 L<App::Access2CSV/How the CSV files are named>.
239  
240 =head1 ENCODING
241  
242 =over 4
243  
244 =item * B<CSV data.> mdbtools gives UTF-8. With C<encoding> set to
245 C<utf8> or C<utf8-bom> the bytes are copied exactly, so every character,
246 including emoji and non-Latin scripts, is kept. C<utf8-bom> also writes
247 the three-byte UTF-8 "byte order mark" first, which Microsoft Excel
248 needs. With C<cp1252>, each line is converted to Windows-1252; if a line
249 has a character that Windows-1252 does not have (for example Greek,
250 Chinese or an emoji), that table fails and nothing is written for it.
251  
252 =item * B<Database path and output_dir.> These are passed to the operating
253 system unchanged. Give them as byte strings (the form you get from
254 C<@ARGV> or C<readdir>). Non-ASCII names work on systems whose file names
255 are UTF-8, such as Linux and macOS.
256  
257 =item * B<Table names> (in C<tables>). They are compared with the names
258 that C<mdb-tables> prints, which are UTF-8 bytes. So give UTF-8 byte
259 strings, not decoded Perl character strings. If you have a decoded
260 string, use C<Encode::encode('UTF-8', $name)> first. The CSV file name is
261 made from the same bytes, so non-ASCII names and emoji are kept.
262  
263 =item * B<Messages.> All messages are plain ASCII English.
264  
265 =back
266  
267 =head1 COMMON PITFALLS
268  
269 =over 4
270  
271 =item * B<undef means "use the default", not "false".> In C<new>,
272 C<< overwrite => undef >> is the same as not giving C<overwrite> at all.
273 To switch something off, give C<0>.
274  
275 =item * B<An empty table list exports nothing.> C<< tables => undef >>
276 (or no C<tables>) means "all tables". C<< tables => [] >> means "no
277 tables": nothing is exported, and C<run> returns 0.
278  
279 =item * B<Table names are case-sensitive.> C<'orders'> does not match the
280 table C<Orders>. Names that do not match any table give a warning.
281  
282 =item * B<A failing logger does not stop the export.> If the logger dies
283 (for example, its disk is full), C<run> warns once with "Cannot write to
284 the log", stops logging for this exporter, and carries on exporting.
285  
286 =item * B<run can croak.> C<run> returns 1 when some tables fail, but it
287 croaks (throws an exception) when nothing can be exported at all: the
288 database is missing or unreadable, mdbtools is not installed, or the
289 output directory cannot be created. Wrap C<run> in C<eval> if your program
290 must keep going.
291  
292 =item * B<run may change the show_counts setting.> If C<show_counts> is
293 on but C<mdb-count> cannot be found, C<run> warns and switches
294 C<show_counts> off for this exporter.
295  
296 =item * B<Settings are copied, not shared.> C<new> makes its own copy of
297 the C<tables> list; changing your array later has no effect. Settings are
298 not merged in depth: a new C<tables> list replaces the default completely.
299  
300 =item * B<Warnings go through carp.> Failed tables and unknown table names
301 are reported with C<carp>, so they appear on standard error (or in your
302 C<$SIG{__WARN__}> handler) even when a logger is given.
303  
304 =item * B<Load the module with use, not require.> Protection of the
305 private methods is set up at compile time. After a run-time
306 C<require> Perl prints "Too late to run CHECK block" and the protection is
307 missing.
308  
309 =back
310  
311 =head1 METHODS
312  
313 =head2 new
314  
315 =head3 Purpose
316  
317 Make a new exporter with your settings. Nothing is checked on disk yet.
318  
319 =head3 Arguments
320  
321 Named arguments, either as a list or as one hash reference. All of them
322 are optional. An argument whose value is C<undef> is ignored, so its
323 default is used.
324  
325 =over 4
326  
327 =item C<output_dir> - the directory for the CSV files. Default: the current directory.
328  
329 =item C<tables> - an array reference of table names to export. Default:
330 all tables. An empty array means no tables.
331  
332 =item C<overwrite> - true to replace CSV files that already exist. Default: false.
333  
334 =item C<verbose> - true to log extra detail. Default: false.
335  
336 =item C<dry_run> - true to only print what would be written. Default: false.
337  
338 =item C<show_counts> - true to report row counts (needs C<mdb-count>). Default: false.
339  
340 =item C<progress> - true to print C<[n/total] table> lines to standard
341 error. Default: true.
342  
343 =item C<encoding> - C<utf8>, C<utf8-bom> or C<cp1252>. Default: C<utf8>.
344  
345 =item C<logger> - an object with C<debug>, C<info> and C<warn> methods,
346 such as a L<Log::Abstraction> object. Default: no logging.
347  
348 =item C<language> - a language code such as C<en> for messages. Default:
349 taken from the locale (see L<App::Access2CSV::I18N>).
350  
351 =back
352  
353 =head3 Returns
354  
355 A new C<App::Access2CSV::Exporter> object.
356  
357 =head3 Side Effects
358  
359 None. Your C<$@>, C<$!> and C<$_> are left as they were.
360  
361 =head3 Usage
362  
363 my $exporter = App::Access2CSV::Exporter->new({ dry_run => 1 });
364  
365 =head3 EXAMPLE
366  
367 # Export two tables as Windows-1252, replacing older files, with a log
368 my $exporter = App::Access2CSV::Exporter->new(
369 output_dir => 'out',
370 tables => ['Customers', 'Orders'],
371 encoding => 'cp1252',
372 overwrite => 1,
373 logger => Log::Abstraction->new(logger => 'export.log'),
374 );
375  
376 =head3 API SPECIFICATION
377  
378 =head4 Input
379  
380 {
381 output_dir => { type => 'string', min => 1, optional => 1 },
382 tables => { type => 'arrayref', element_type => 'string', optional => 1 },
383 overwrite => { type => 'boolean', optional => 1 },
384 verbose => { type => 'boolean', optional => 1 },
385 dry_run => { type => 'boolean', optional => 1 },
386 show_counts => { type => 'boolean', optional => 1 },
387 progress => { type => 'boolean', optional => 1 },
388 encoding => { type => 'string', memberof => ['utf8', 'utf8-bom', 'cp1252'], optional => 1 },
389 logger => { type => 'object', can => ['debug', 'info', 'warn'], optional => 1 },
390 language => { type => 'string', optional => 1 },
391 }
392  
393 Valid and invalid values (tested in F<t/domain.t>):
394  
395 output_dir valid: any path of 1 character or more ("0" is valid),
396 including non-ASCII names given as UTF-8 bytes
397 invalid: "" (below the minimum), references
398 tables valid: undef (all tables), [] (no tables), one name,
399 many names; names are matched byte for byte
400 invalid: anything but an array reference; elements
401 that are references
402 booleans valid: exactly 1 true TRUE yes on / 0 false FALSE no off
403 (overwrite, invalid: everything else, e.g. "", 2, -1, "True", "Yes",
404 verbose, "0.0", " 1"
405 dry_run, show_counts, progress)
406 encoding valid: exactly utf8, utf8-bom, cp1252
407 invalid: other spellings (UTF8, utf-8, CP1252, " utf8")
408 logger valid: an object with debug, info and warn methods
409 invalid: an object missing any of them, a plain hash,
410 a string
411 language valid: any string; "" means "use the environment"
412 invalid: references
413  
414 =head4 Output
415  
416 {
417 type => 'object',
418 isa => 'App::Access2CSV::Exporter',
419 }
420  
421 =head3 MESSAGES
422  
423 All are fatal, and read "Invalid setting: REASON". The REASON part
424 comes from L<Params::Validate::Strict> and is not translated; for example:
425  
426 +--------------------------------------+------------------------------+-----------------------------+
427 | Message | Meaning | What to do |
428 +--------------------------------------+------------------------------+-----------------------------+
429 | Invalid setting: Unknown parameter | X is not a known setting | Remove X, or fix its |
430 | 'X' | | spelling |
431 | Invalid setting: Parameter | This encoding is not | Use utf8, utf8-bom or |
432 | 'encoding' (X) must be one of utf8, | supported | cp1252 |
433 | utf8-bom, cp1252 | | |
434 | Invalid setting: Parameter 'logger' | logger is not an object | Give a logger object |
435 | must be an object | | |
436 | Invalid setting: Parameter 'tables' | tables is not an array | Give an array reference |
437 | must be ... | reference | |
438 +--------------------------------------+------------------------------+-----------------------------+
439  
440 =cut
441  
442 1809 ▶sub new {
Subroutine new: called CC=5 SCAR=16.1
Pod documented
443 1809 my $class = shift;
444  
445 # Validation uses eval internally; the caller's $@ must survive
446 1809 local $@;
447  
448 # Drop undefined values so that "not given" means "use the default"
449 1809 ▶ my $args = get_params(undef, \@_) || {};
Condition100%2/2
get_params(undef, \@_) || {}
l!l
7911017
MC/DC100%1/1
get_params(undef, \@_) || {}
get_params(undef, \@_)
Truth table100%2/2
A
A= get_params(undef, \@_)
Aresult
11
00
450 1808 my %given = map { $_ => $args->{$_} } grep { defined $args->{$_} } keys %{$args};
451  
452 # A bad setting is reported in plain words ("Invalid setting: ..."),
453 # not with Params::Validate::Strict's internal prefix and location
454 1808 ▶ my $params = eval { validate_strict(schema => { %NEW_SCHEMA }, input => \%given) }
Branch: 1 branch
BranchTrueFalseTotal
my $params = eval { do { validate_strict("schema", {%NEW_SCHEMA}, "input", \%given) } } or $class->_croak_i18n("invalid_setting", {"params", [_validation_reason($@)]}) 1716 92 1808
455 or $class->_croak_i18n('invalid_setting', { params => [_validation_reason($@)] });
456  
457 # Copy the table list so later changes by the caller cannot affect us
458 1716 ▶ $params->{tables} = [ @{ $params->{tables} } ] if $params->{tables};
Branch: 1 branch
BranchTrueFalseTotal
if $params->{"tables"} 46 1670 1716
459  
460 # The output directory is the invoking user's own choice; it is only used
461 # as a directory name, so it is untainted here (see _untaint)
462 1716 ▶ $params->{output_dir} = _untaint($params->{output_dir}) if defined $params->{output_dir};
Branch: 1 branch
BranchTrueFalseTotal
if defined $params->{"output_dir"} 491 1225 1716
463  
464 1716 my $self = bless { %DEFAULTS, %{$params}, used_names => {}, next_suffix => {}, programs => {} }, $class;
465 1716 return set_return($self, { type => 'object' });
466 }
467  
468 =head2 run
469  
470 =head3 Purpose
471  
472 Export the selected tables of one database to CSV files. In dry-run mode,
473 only print what would be exported.
474  
475 =head3 Arguments
476  
477 =over 4
478  
479 =item C<database> (string, required) - the path of the C<.mdb> or C<.accdb> file.
480 The name is taken literally: C<-> is a file called C<->. (Reading from
481 standard input is a feature of the command-line program; see
482 L<App::Access2CSV/Reading the database from standard input>.)
483  
484 =back
485  
486 You can give it on its own, C<< $exporter->run('shop.accdb') >>, or as a
487 hash reference, C<< $exporter->run({ database => 'shop.accdb' }) >>.
488  
489 =head3 Returns
490  
491 C<0> if every selected table was exported, or in dry-run mode.
492 C<1> if at least one table was not exported (the others were).
493  
494 =head3 Side Effects
495  
496 =over 4
497  
498 =item * Creates the output directory if needed (not in dry-run mode, and
499 not when no table is selected).
500  
501 =item * Writes one CSV file per table (not in dry-run mode).
502  
503 =item * Prints progress lines to standard error, if C<progress> is on.
504  
505 =item * Prints the dry-run list to standard output, in dry-run mode.
506  
507 =item * Sends messages to the logger, if there is one.
508  
509 =item * Warns (with C<carp>) about each table that failed, about unknown
510 names in C<tables>, and about a missing C<mdb-count>.
511  
512 =item * Croaks, before writing anything, if the database cannot be read, a
513 needed mdbtools program is missing, C<mdb-tables> fails, or the output
514 directory cannot be created.
515  
516 =item * Switches C<show_counts> off for this exporter if C<mdb-count> is
517 missing.
518  
519 =item * While it runs, handles the signals INT, QUIT, TERM and HUP (only
520 those you have not set a handler for yourself; they are restored when
521 C<run> returns). Any of them stops the run: the table being exported is
522 discarded - its temporary file deleted, any old CSV file left as it was -
523 no further table is started, and C<run> croaks. Pressing Ctrl-C, which
524 also stops the mdbtools program, has the same effect.
525  
526 =item * Leaves your C<$@>, C<$!>, C<$?>, C<$_>, C<$.> and any pending C<alarm>
527 as they were (except that a croak sets C<$@> in your C<eval>, as usual).
528  
529 =back
530  
531 =head3 Usage
532  
533 exit $exporter->run('shop.accdb');
534  
535 =head3 EXAMPLE
536  
537 my $exporter = App::Access2CSV::Exporter->new(output_dir => 'out');
538  
539 # eval catches the fatal errors; the return value covers the rest
540 my $status = eval { $exporter->run('shop.accdb') };
541 if(!defined $status) {
542 print STDERR "Nothing was exported: $@";
543 } elsif($status) {
544 print STDERR "Some tables failed; see the warnings above\n";
545 } else {
546 print "Done\n";
547 }
548  
549 =head3 API SPECIFICATION
550  
551 =head4 Input
552  
553 {
554 database => {
555 type => 'string',
556 min => 1,
557 optional => 0,
558 },
559 }
560  
561 Valid and invalid values (tested in F<t/domain.t>):
562  
563 database valid: a readable regular file
564 invalid: "" (below the 1-character minimum), undef,
565 a missing file, a directory, a device or FIFO,
566 an unreadable file
567 edges: each part of the path may be up to 255 bytes;
568 256 gives "File name too long"
569  
570 The table names that mdbtools reports are data, not arguments, but they
571 have limits of their own:
572  
573 length a CSV file name is the table name plus ".csv". Access
574 allows at most 64 characters, so longer names (only from
575 a damaged or hostile database) are shortened to 64
576 characters, and also to at most 240 bytes of UTF-8 (64
577 emoji would be 256 bytes; most file systems allow 255).
578 A name is never cut inside a character, nor between a
579 letter and its accents or inside a joined emoji.
580 Shortened names that clash are numbered as usual.
581 characters non-ASCII letters, emoji, joined emoji, combining marks
582 and right-to-left text are kept byte for byte.
583 Characters that are unsafe in file names - including
584 invisible text-direction controls such as U+202E - are
585 replaced by "_". So is each byte that is not part of
586 valid UTF-8 (only a damaged database has them; macOS
587 refuses such file names).
588 collisions the first name has no suffix, then _2, _3, ... _10 ...
589 cp1252 U+00FF and the Euro sign convert; U+0100 and above
590 (except the few Windows-1252 symbols), the C1 controls
591 U+0080-U+009F and emoji make the table fail.
592  
593 =head4 Output
594  
595 {
596 type => 'integer',
597 min => 0,
598 max => 1,
599 }
600  
601 =head3 MESSAGES
602  
603 "fatal" means C<run> croaks and nothing is exported. "per table" means
604 only that table fails; C<run> warns, logs, and carries on.
605  
606 +-----------------------------------------+------------------------------+-------------------------------+
607 | Message | Meaning | What to do |
608 +-----------------------------------------+------------------------------+-------------------------------+
609 | Interrupted by SIGx: stopped, and the | Ctrl-C, Ctrl-\\, kill or a | Run again; tables finished |
610 | table being exported was discarded | closed terminal stopped the | before the interruption are |
611 | (fatal) | run | complete |
612 | run() must be called on an object | run was called on the class | Call new() first, then run() |
613 | created by new() (fatal) | or on something that is not | on the object it returns |
614 | | an exporter | |
615 | Cannot read database F: E (fatal) | F does not exist, or cannot | Check the path |
616 | | be reached; E is the reason | |
617 | | from the operating system | |
618 | Database F is not a regular file (fatal)| F is a directory or a device | Give the database file |
619 | Database F is not readable (fatal) | No permission to read F | Fix the permissions |
620 | | (never happens for root) | |
621 | Required program not found in PATH: P | mdbtools is not installed, | Install mdbtools, or fix PATH |
622 | (fatal) | or not in PATH | |
623 | mdb-tables failed with exit status N: E | mdbtools cannot read the | Check that F is a real Access |
624 | (fatal) | file | database |
625 | Cannot create output directory D: E | The directory cannot be made; | Check permissions and path |
626 | (fatal) | E is the reason for D itself | |
627 | | (e.g. "Not a directory" when | |
628 | | a file is in the way) | |
629 | Cannot count the rows of T: E (warning) | mdb-count failed for table T | The table is still exported |
630 | | (only with show_counts) | (dry run: count shown as "?") |
631 | ... mdb-count printed no number: "X" | mdb-count's answer was not | As above; X shows what it |
632 | | just a number | printed |
633 | Tables not found in database: T | Names in tables are not in | Check spelling and case |
634 | (warning) | the database | |
635 | mdb-count not found in PATH; row counts | show_counts is on, but | Install mdb-count, or turn |
636 | are unavailable (warning) | mdb-count is missing | show_counts off |
637 | FAILED: T: E (warning, logged) | Table T was not exported, | See E, one of the messages |
638 | | because of E | below |
639 | Output file already exists: F (use | F exists (a symbolic link, | Set overwrite, or use another |
640 | --overwrite to replace it) (per table) | even a broken one, counts) | output_dir |
641 | | and overwrite is off | |
642 | mdb-export failed with exit status N: E | mdbtools could not read this | Check the table in Access |
643 | (per table) | table | |
644 | P was killed by signal N (per table, | The program was stopped from | Check memory and system |
645 | or fatal for mdb-tables) | outside | limits |
646 | P could not be run: E (per table, or | The program was found but | Check its permissions and |
647 | fatal for mdb-tables) | could not be started | that it is a real program |
648 | Table T, line N: cannot be represented | A character is not in | Use utf8 or utf8-bom |
649 | in cp1252 (per table) | Windows-1252 | |
650 | Table T, line N: output of mdb-export | mdbtools gave bytes that are | Check the MDB_ICONV setting |
651 | is not valid UTF-8 (per table) | not UTF-8 | |
652 | Cannot write F: E (per table) | The file could not be | Check permissions and free |
653 | | written or renamed into place| disk space |
654 | Cannot write to the log: E (warning, | The logger failed. Exports | Check the log's disk or |
655 | once) | go on; logging stops | destination |
656 +-----------------------------------------+------------------------------+-------------------------------+
657  
658 =head3 PSEUDOCODE
659  
660 check the argument
661 stop (croak) unless the database is a readable file
662 find mdb-tables and mdb-export (croak if missing),
663 and mdb-count if row counts are wanted (warn if missing)
664 forget the file names given out by any earlier run
665 tables := the sorted user tables, filtered by "tables"
666 (warn about names that are not found)
667 if dry run:
668 print the table -> file list (row count "?" with a warning
669 if a count fails)
670 return 0
671 if there are tables to export:
672 create the output directory (croak if that fails)
673 for each table:
674 print "[n/total] table" if progress is on
675 try to export the table
676 if that failed: warn, log, and count the failure
677 (a failed row count after the file is in place is only a
678 warning; the table still counts as exported)
679 log the summary
680 return 1 if any table failed, else 0
681  
682 =cut
683  
684 401 ▶sub run {
Subroutine run: called CC=7 SCAR=19.5
Pod documented
685 401 my $self = shift;
686  
687 # State machine guard: run() is only a transition out of READY, which
688 # only new() can create. Refuse anything else before doing any work.
689 # (Reported through the class: $self may not even be an object.)
690 401 ▶ blessed($self) && $self->isa(__PACKAGE__) or __PACKAGE__->_croak_i18n('needs_object');
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($self) and $self->isa(__PACKAGE__) or __PACKAGE__->_croak_i18n("needs_object") 397 4 401
Condition66%2/3
builtin::blessed($self) and $self->isa(__PACKAGE__)
!ll&&!rl&&r
40397
MC/DC50%1/2
builtin::blessed($self) and $self->isa(__PACKAGE__)
builtin::blessed($self) $self->isa(__PACKAGE__)
Truth table66%2/3
A and B
A= builtin::blessed($self)B= $self->isa(__PACKAGE__)
ABresult
0X0
100
111
691  
692 # File tests, evals and child processes below would otherwise leave
693 # their marks in the caller's $@ and $!
694 397 local ($@, $!);
695  
696 # An undef database is a missing one, not a file called "". Work on a
697 # copy: get_params hands back the caller's own hash when given one.
698 # (Params::Get either dies or returns a hash reference - proved in
699 # t/path.t - so no test of what it returned is needed.)
700 397 my $input = { %{ get_params('database', \@_) } };
701 391 ▶ delete $input->{database} unless defined $input->{database};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $input->{"database"} 4 387 391
702 391 my $params = validate_strict(
703 schema => { database => { type => 'string', min => 1 } },
704 input => $input,
705 );
706 382 my $database = $params->{database};
707  
708 # Fail fast, before any output, on problems that affect every table
709 382 $self->_check_database($database)
710 ->_verify_dependencies()
711 ->_reset_names();
712  
713 # Stopping part-way must behave like a failed transaction: the table
714 # being exported is discarded (its temporary file deleted) and no
715 # further table is started. Perl's default action for these signals
716 # is to exit at once, skipping the clean-up, so while run() is active
717 # they raise an exception instead. A handler the caller has set is
718 # left alone; everything is restored when run() returns.
719 313 local $self->{interrupted};
720 313 my @ours = @{ $self->_interrupt_signals() };
721 1 ▶ local @SIG{@ours} = (sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
722 1 $self->{interrupted} = $_[0];
723 1 die $self->_printable($self->i18n('interrupted', { params => [$_[0]] })), "\n";
724 313 }) x @ours;
725  
726 # Premise: the database is now known to be a readable regular file, and
727 # it is only ever passed to mdbtools as one list argument after "--".
728 # Conclusion: it is safe to untaint.
729 313 $database = _untaint($database);
730  
731 313 my $tables = $self->_select_tables($self->_get_tables($database));
732  
733 # Guard clause: a dry run must not touch the file system, so it leaves
734 # before mkdir. Premise: _dry_run writes nothing that can fail a table.
735 # Conclusion: a dry run always succeeds.
736 297 ▶ if($self->{dry_run}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"dry_run"}) 64 233 297
737 64 $self->_dry_run($database, $tables);
738 64 return set_return($EXIT_OK, { %RUN_STATUS_SCHEMA });
739 }
740  
741 # The output directory is only made when there is something to put in it;
742 # with no tables selected the run goes straight to the summary
743 233 ▶ my $failed = (@{$tables} ? $self->_make_output_dir() : $self)->_export_all($database, $tables);
Branch: 1 branch
BranchTrueFalseTotal
@{$tables;} ? : 219 14 233
744 224 ▶ return set_return($failed ? $EXIT_FAILURE : $EXIT_OK, { %RUN_STATUS_SCHEMA });
Branch: 1 branch
BranchTrueFalseTotal
$failed ? : 52 172 224
745 }
746  
747 # _check_database
748 # Purpose: Make sure the database is a readable regular file.
749 # Entry Criteria: $database is a defined, non-empty path.
750 # Exit Status: Returns $self for chaining; croaks otherwise.
751 # Side Effects: stat()s the file; sets $!.
752 386 ▶sub _check_database :Private {
Subroutine _check_database: called CC=4 SCAR=13.9
753 386 my ($self, $database) = @_;
754  
755 # The stat result is reused via "_" so the file is only examined once;
756 # $! is captured straight away because later calls may overwrite it
757 386 ▶ if(!-e $database) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-e $database) 35 351 386
758 35 $self->_croak_i18n('database_not_found', { params => [$database, "$!"] });
759 }
760 351 ▶ $self->_croak_i18n('database_not_file', { params => [$database] }) unless -f _;
Branch: 1 branch
BranchTrueFalseTotal
unless -f _ 13 338 351
761 338 ▶ $self->_croak_i18n('database_unreadable', { params => [$database] }) unless -r _;
Branch: 1 branch
BranchTrueFalseTotal
unless -r _ 6 332 338
762  
763 332 return $self;
764 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
765  
766 # _verify_dependencies
767 # Purpose: Locate the mdbtools programs in PATH.
768 # Entry Criteria: None.
769 # Exit Status: Returns $self; croaks if a required program is missing.
770 # Side Effects: Sets $self->{programs}; may switch off show_counts (with a
771 # warning) when mdb-count is unavailable; logs at debug level.
772 355 ▶sub _verify_dependencies :Private {
Subroutine _verify_dependencies: called CC=5 SCAR=16.1
773 355 my $self = shift;
774  
775 355 my %programs;
776 355 foreach my $program (@REQUIRED_PROGRAMS) {
777 686 ▶ $programs{$program} = $self->_find_program($program)
Branch: 1 branch
BranchTrueFalseTotal
$programs{$program} = $self->_find_program($program) or $self->_croak_i18n("program_missing", {"params", [$program]}) 647 39 686
778 or $self->_croak_i18n('program_missing', { params => [$program] });
779 }
780  
781 # mdb-count is only needed for row counts, so its absence is not fatal.
782 # _find_program returns a path or false, so one branch decides both
783 # "store it" and "switch counts off" (nothing is stored and removed).
784 316 ▶ if($self->{show_counts}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"show_counts"}) 47 269 316
785 47 ▶ if(my $path = $self->_find_program($MDB_COUNT)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $path = $self->_find_program($MDB_COUNT)) { } 35 12 47
786 35 $programs{$MDB_COUNT} = $path;
787 } else {
788 12 $self->{show_counts} = 0;
789 12 $self->_warn('no_row_counter');
790 }
791 }
792  
793 316 $self->{programs} = \%programs;
794 316 return $self;
795 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
796  
797 # _find_program
798 # Purpose: Look up one program in PATH and note where it was found.
799 # Entry Criteria: $program is a bare program name.
800 # Exit Status: Returns the full path, or undef if not found.
801 # Side Effects: Logs the location at debug level when --verbose is on.
802 732 ▶sub _find_program :Private {
Subroutine _find_program: called CC=5 SCAR=16.1
803 732 my ($self, $program) = @_;
804  
805 # Only absolute paths are trusted. A relative entry in PATH (".", or
806 # an empty one) would run whatever file of that name is in the current
807 # directory - a classic way to plant a program.
808 732 ▶ my ($path) = grep { defined && File::Spec->file_name_is_absolute($_) } which($program);
Condition100%3/3
defined $_ && 'File::Spec'->file_name_is_absolute($_)
!ll&&!rl&&r
2710680
MC/DC100%2/2
defined $_ && 'File::Spec'->file_name_is_absolute($_)
defined $_ 'File::Spec'->file_name_is_absolute($_)
Truth table100%3/3
A && B
A= defined $_B= 'File::Spec'->file_name_is_absolute($_)
ABresult
0X0
100
111
809  
810 # An absolute path to an existing program: safe to untaint
811 732 ▶ $path = _untaint($path) if defined $path;
Branch: 1 branch
BranchTrueFalseTotal
if defined $path 680 52 732
812 732 ▶ if($path && $self->{verbose}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($path and $self->{"verbose"}) 8 724 732
Condition100%3/3
$path and $self->{"verbose"}
!ll&&!rl&&r
526728
MC/DC100%2/2
$path and $self->{"verbose"}
$path $self->{"verbose"}
Truth table100%3/3
A and B
A= $pathB= $self->{"verbose"}
ABresult
0X0
100
111
813 8 $self->_log(debug => 'program_found', { params => [$program, $path] });
814 }
815 732 return $path;
816 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
817  
818 # _reset_names
819 # Purpose: Forget file names allocated by a previous run() so that
820 # running the same exporter twice gives the same names.
821 # Entry Criteria: None.
822 # Exit Status: Returns $self.
823 # Side Effects: Empties $self->{used_names}.
824 313 ▶sub _reset_names :Private {
Subroutine _reset_names: called CC=1 SCAR=0.0
825 313 my $self = shift;
826  
827 313 $self->{used_names} = {};
828 313 $self->{next_suffix} = {};
829 313 return $self;
830 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
831  
832 # _get_tables
833 # Purpose: List the user tables in the database.
834 # Entry Criteria: _verify_dependencies() has run.
835 # Exit Status: Returns an arrayref of table names, sorted; croaks if
836 # mdb-tables fails.
837 # Side Effects: Runs mdb-tables.
838 309 ▶sub _get_tables :Protected {
Subroutine _get_tables: called CC=3 SCAR=11.0
839 309 my ($self, $database) = @_;
840  
841 # -1 puts one table per line, so names containing spaces survive;
842 # "--" stops a database path starting with "-" being read as an option
843 309 my $stdout = '';
844 309 $self->_run_program($MDB_TABLES, ['-1', $END_OF_OPTIONS, $database], \$stdout);
845  
846 # \r? copes with mdbtools builds that emit CRLF line endings; a program
847 # that printed nothing may leave $stdout undefined
848 # Table names are untainted: they are only used as one list argument
849 # after "--", and in file names only after _csv_filename has made them
850 # safe
851 293 ▶ my @tables = sort map { _untaint($_) } grep { length($_) && !$self->_is_system_table($_) } split /\r?\n/, $stdout // '';
Condition100%5/5
length $_ && !$self->_is_system_table($_)
!ll&&!rl&&r
14000161525
$stdout // ""
l!l
2912
MC/DC100%2/2
length $_ && !$self->_is_system_table($_)
length $_ !$self->_is_system_table($_)
MC/DC100%1/1
$stdout // ""
$stdout
Truth table100%3/3
A && not(B)
A= length $_B= !$self->_is_system_table($_)
ABresult
0X0
100
111
Truth table100%2/2
A
A= $stdout
Aresult
11
00
852 293 return \@tables;
853 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
854  
855 # _is_system_table
856 # Purpose: Decide whether a table is Access's own rather than the user's.
857 # Entry Criteria: $table is a table name.
858 # Exit Status: Returns 1 for system tables, 0 otherwise.
859 # Side Effects: None. Protected so that subclasses can widen the filter.
860 401551 ▶sub _is_system_table :Protected {
Subroutine _is_system_table: called CC=2 SCAR=6.9
861 401551 my ($self, $table) = @_;
862  
863 401551 ▶ return ($table =~ $SYSTEM_TABLE_RE) ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
$table =~ /$SYSTEM_TABLE_RE/i ? : 400021 1530 401551
864 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
865  
866 # _select_tables
867 # Purpose: Apply the --table filter to the list of tables.
868 # Entry Criteria: $tables is the arrayref from _get_tables().
869 # Exit Status: Returns an arrayref, in database (sorted) order.
870 # Side Effects: Warns and logs about requested tables that do not exist.
871 303 ▶sub _select_tables :Private {
Subroutine _select_tables: called CC=3 SCAR=11.0
872 303 my ($self, $tables) = @_;
873  
874 303 ▶ return $tables unless $self->{tables};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"tables"} 268 35 303
875  
876 # Matching is exact, as mdb-export itself is case-sensitive
877 35 my %available = map { $_ => 1 } @{$tables};
878 35 my %wanted = map { $_ => 1 } @{ $self->{tables} };
879  
880 35 my @missing = sort grep { !$available{$_} } keys %wanted;
881 35 ▶ if(@missing) {
Branch: 1 branch
BranchTrueFalseTotal
if (@missing) 12 23 35
882 12 $self->_warn('unknown_tables', { params => [join(', ', @missing)], count => scalar(@missing) });
883 }
884  
885 35 return [ grep { $wanted{$_} } @{$tables} ];
886 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
887  
888 # _make_output_dir
889 # Purpose: Create the output directory (and parents) if necessary.
890 # Entry Criteria: Not in dry-run mode.
891 # Exit Status: Returns $self; croaks if the directory cannot be created.
892 # Side Effects: Creates directories.
893 231 ▶sub _make_output_dir :Private {
Subroutine _make_output_dir: called CC=7 SCAR=19.5
894 231 my $self = shift;
895  
896 231 my $dir = $self->{output_dir};
897 231 ▶ return $self if -d $dir;
Branch: 1 branch
BranchTrueFalseTotal
if -d $dir 54 177 231
898  
899 # Ask File::Path to report errors rather than carp/croak on its own,
900 # so the message can be translated and names the directory we wanted
901 177 make_path($dir, { error => \my $errors });
902 177 ▶ if(@{$errors} || !-d $dir) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$errors;} or not -d $dir) 18 159 177
Condition100%3/3
@{$errors;} or not -d $dir
l!l&&r!l&&!r
144159
MC/DC100%2/2
@{$errors;} or not -d $dir
@{$errors;} not -d $dir
Truth table100%3/3
A or not(B)
A= @{$errors;}B= not -d $dir
ABresult
1X1
011
000
903 # File::Path may also report a parent (e.g. "File exists" for a
904 # plain file in the way); the reason for $dir itself, or failing
905 # that the last one, is what explains the failure
906 18 my ($mine) = grep { exists $_->{$dir} } @{$errors};
907 18 ▶ my $detail = $mine ? $mine->{$dir} : (@{$errors} ? (values %{ $errors->[-1] })[0] : undef);
Branch: 2 branches
BranchTrueFalseTotal
$mine ? : 12 6 18
@{$errors;} ? : 2 4 6
908 18 ▶ $self->_croak_i18n('mkdir_failed', { params => [$dir, $detail || "$!"] });
Condition66%2/3
$detail || "$!"
l!l&&r!l&&!r
1440
MC/DC0%0/2
$detail || "$!"
$detail "$!"
Truth table66%2/3
A || B
A= $detailB= "$!"
ABresult
1X1
011
000
909 }
910 159 return $self;
911 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
912  
913 # _export_all
914 # Purpose: Export each table, carrying on past individual failures.
915 # Entry Criteria: The output directory exists.
916 # Exit Status: Returns the number of tables that failed.
917 # Side Effects: Writes CSV files; prints progress; warns; logs.
918 229 ▶sub _export_all :Private {
Subroutine _export_all: called CC=6 SCAR=17.9
919 229 my ($self, $database, $tables) = @_;
920  
921 229 my $total = scalar @{$tables};
922 229 my $failed = 0;
923  
924 # eval below would otherwise overwrite the caller's $@
925 229 local $@;
926  
927 # An index loop, not each(), which shares the array's iterator with the
928 # caller and would silently skip tables if it was already part-way
929 229 foreach my $index (0 .. $#{$tables}) {
930 1391 my $table = $tables->[$index];
931 # Progress goes to STDERR so that STDOUT can be redirected cleanly
932 1391 ▶ if($self->{progress}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"progress"}) 53 1338 1391
933 53 print STDERR $self->_printable($self->i18n('progress', { params => [$index + 1, $total, $table] })), "\n";
934 }
935  
936 # One bad table should not stop the rest from being exported
937 1391 ▶ next if eval { $self->_export_table($database, $table); 1 };
Branch: 1 branch
BranchTrueFalseTotal
if eval { do { $self->_export_table($database, $table); 1 } } 1315 76 1391
938  
939 # ... but an interruption stops them all: the failed table has been
940 # discarded (its temporary file went with the exception), and no
941 # further table is started
942 76 ▶ $self->_croak_i18n('interrupted', { params => [$self->{interrupted}] }) if $self->{interrupted};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"interrupted"} 2 74 76
943  
944 74 ▶ my $error = $@ || 'Unknown error';
Condition100%2/2
$@ || 'Unknown error'
l!l
731
MC/DC100%1/1
$@ || 'Unknown error'
$@
Truth table100%2/2
A
A= $@
Aresult
11
00
945 74 chomp $error;
946 74 ++$failed;
947 74 $self->_warn('export_failed', { params => [$table, $error] });
948 }
949  
950 227 $self->_log(info => 'summary', { params => [$total, $failed], count => $total });
951 227 return $failed;
952 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
953  
954 # _export_table
955 # Purpose: Export one table to its CSV file.
956 # Entry Criteria: _verify_dependencies() and _make_output_dir() have run.
957 # Exit Status: Returns $self; croaks on any failure, leaving no partial file.
958 # Side Effects: Runs mdb-export (and mdb-count); creates or replaces a file.
959 1391 ▶sub _export_table :Protected {
Subroutine _export_table: called CC=9 SCAR=22.0
960 1391 my ($self, $database, $table) = @_;
961  
962 1391 my $outfile = File::Spec->catfile($self->{output_dir}, $self->_csv_filename($table));
963  
964 # Check before exporting so that we do not waste time on a big table
965 # -l as well as -e: a dangling symlink is an existing entry too, and
966 # must not be silently replaced. The overwrite flag is tested first:
967 # when it is set the answer is already known, so no file test is needed.
968 1391 ▶ if(!$self->{overwrite} && (-e $outfile || -l $outfile)) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $self->{"overwrite"} and -e $outfile || -l $outfile) 24 1367 1391
Condition100%6/6
not $self->{"overwrite"} and -e $outfile || -l $outfile
!ll&&!rl&&r
72129524
-e $outfile or -l $outfile
l!l&&r!l&&!r
2131295
MC/DC100%3/3
not $self->{"overwrite"} and -e $outfile || -l $outfile
not $self->{"overwrite"} -e $outfile -l $outfile
Truth table100%4/4
not(A) and B or C
A= not $self->{"overwrite"}B= -e $outfileC= -l $outfile
ABCresult
0XX0
1000
11X1
1011
969 24 $self->_croak_i18n('output_exists', { params => [$outfile] });
970 }
971  
972 # Write into a temporary file next to the target; it is deleted
973 # automatically if anything below croaks
974 1367 my $tmp = File::Temp->new(DIR => $self->{output_dir}, TEMPLATE => $TEMP_TEMPLATE, UNLINK => 1);
975 1365 binmode $tmp, ':raw';
976  
977 1365 ▶ if($self->{encoding} eq $ENC_CP1252) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'encoding'} eq $ENC_CP1252) { } 45 1320 1365
978 45 $self->_export_transcoded($database, $table, $tmp);
979 } else {
980 # The BOM must reach the file before mdb-export starts writing to
981 # the same descriptor, hence the explicit flush
982 1320 ▶ print {$tmp} $UTF8_BOM if $self->{encoding} eq $ENC_UTF8_BOM;
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"encoding"} eq $ENC_UTF8_BOM 19 1301 1320
983 1320 ▶ $tmp->flush() or $self->_croak_i18n('write_failed', { params => [$outfile, "$!"] });
Branch: 1 branch
BranchTrueFalseTotal
$tmp->flush or $self->_croak_i18n("write_failed", {"params", [$outfile, "$!"]}) 1317 3 1320
984 1317 $self->_run_program($MDB_EXPORT, [$END_OF_OPTIONS, $database, $table], $tmp);
985 }
986  
987 1320 $self->_install_file($tmp, $outfile);
988  
989 # The file is now in place, so the table has been exported. Row counts
990 # are optional extras: if counting fails it is only a warning (see
991 # _try_count_rows), and the export is logged without a count.
992 1316 ▶ my $rows = $self->{show_counts} ? $self->_try_count_rows($database, $table) : undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->{'show_counts'} ? : 39 1277 1316
993 1316 ▶ if(defined $rows) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rows) { } 31 1285 1316
994 31 $self->_log(info => 'exported_rows', { params => [$table, $outfile, $rows], count => $rows });
995 } else {
996 1285 $self->_log(info => 'exported', { params => [$table, $outfile] });
997 }
998 1316 return $self;
999 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1000  
1001 # _export_transcoded
1002 # Purpose: Export a table and convert it from UTF-8 to Windows-1252.
1003 # Entry Criteria: $out is an open, raw, writable filehandle.
1004 # Exit Status: Returns $self; croaks on invalid UTF-8 or on a character
1005 # that has no cp1252 equivalent (rather than silently
1006 # replacing it with '?').
1007 # Side Effects: Runs mdb-export into a second temporary file.
1008 51 ▶sub _export_transcoded :Private {
Subroutine _export_transcoded: called CC=4 SCAR=13.9
1009 51 my ($self, $database, $table, $out) = @_;
1010  
1011 # Reading the spool changes $. and the evals change $@; keep the
1012 # caller's values
1013 51 local $.;
1014 51 local $@;
1015  
1016 # Spool to disk rather than memory, so huge tables do not exhaust RAM
1017 51 my $spool = File::Temp->new(DIR => $self->{output_dir}, TEMPLATE => $TEMP_TEMPLATE, UNLINK => 1);
1018 51 binmode $spool, ':raw';
1019 51 $self->_run_program($MDB_EXPORT, [$END_OF_OPTIONS, $database, $table], $spool);
1020 43 seek $spool, 0, 0;
1021  
1022 # Convert line by line; $. gives the user a line number to look at
1023 43 ▶ while(my $line = <$spool>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined(my $line = readline $spool)) 81 25 106
1024 81 my $chars = eval { $UTF8_CODEC->decode($line, FB_CROAK) };
1025 81 ▶ $self->_croak_i18n('invalid_utf8', { params => [$table, $.] }) unless defined $chars;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $chars 7 74 81
1026  
1027 74 my $bytes = eval { $CP1252_CODEC->encode($chars, FB_CROAK) };
1028 74 ▶ $self->_croak_i18n('unmappable', { params => [$table, $., $ENC_CP1252] }) unless defined $bytes;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $bytes 11 63 74
1029  
1030 63 print {$out} $bytes;
1031 }
1032  
1033 # Close the spool explicitly once it has been read. (On a croak above,
1034 # File::Temp's destructor closes and deletes it.)
1035 25 close $spool;
1036 25 return $self;
1037 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1038  
1039 # _install_file
1040 # Purpose: Move a finished temporary file to its final name.
1041 # Entry Criteria: $tmp is a File::Temp holding the complete CSV.
1042 # Exit Status: Returns $self; croaks if the rename or chmod fails.
1043 # Side Effects: Replaces $outfile; the temporary file is no longer
1044 # auto-deleted.
1045 1315 ▶sub _install_file :Private {
Subroutine _install_file: called CC=2 SCAR=6.9
1046 1315 my ($self, $tmp, $outfile) = @_;
1047  
1048 # The eval must not overwrite the caller's $@
1049 1315 local $@;
1050  
1051 # File::Temp creates files as 0600; give the CSV the permissions a
1052 # normal open() would have, i.e. 0666 less the umask
1053 1315 my $ok = eval {
1054 1315 close $tmp;
1055 1315 chmod $FILE_MODE & ~umask(), $tmp->filename();
1056 1315 rename $tmp->filename(), $outfile;
1057 1309 1;
1058 };
1059 1315 ▶ $self->_croak_i18n('write_failed', { params => [$outfile, _os_error($@)] }) unless $ok;
Branch: 1 branch
BranchTrueFalseTotal
unless $ok 6 1309 1315
1060  
1061 1309 $tmp->unlink_on_destroy(0);
1062 1309 return $self;
1063 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1064  
1065 # _count_rows
1066 # Purpose: Ask mdb-count how many rows a table has.
1067 # Entry Criteria: $self->{programs}{'mdb-count'} is set.
1068 # Exit Status: Returns a non-negative integer; croaks if mdb-count fails.
1069 # Side Effects: Runs mdb-count.
1070 57 ▶sub _count_rows :Private {
Subroutine _count_rows: called CC=4 SCAR=13.9
1071 57 my ($self, $database, $table) = @_;
1072  
1073 57 my $stdout = '';
1074 57 $self->_run_program($MDB_COUNT, [$END_OF_OPTIONS, $database, $table], \$stdout);
1075  
1076 # mdb-count prints just the number (perhaps with spaces around it).
1077 # Anything else - nothing, "-5", an error text - is not a count, and
1078 # must not quietly become 0: it is reported (as a warning, by
1079 # _try_count_rows)
1080 50 ▶ my ($rows) = ($stdout // '') =~ /\A\s*(\d+)\s*\z/;
Condition100%2/2
$stdout // ""
l!l
491
MC/DC100%1/1
$stdout // ""
$stdout
Truth table100%2/2
A
A= $stdout
Aresult
11
00
1081 50 ▶ defined($rows) or $self->_croak_i18n('count_unreadable', { params => [$self->_printable(substr($stdout // '', 0, $COUNT_SHOWN))] });
Branch: 1 branch
BranchTrueFalseTotal
defined $rows or $self->_croak_i18n("count_unreadable", {"params", [$self->_printable(substr($stdout // "", 0, $COUNT_SHOWN))]}) 42 8 50
Condition100%2/2
$stdout // ""
l!l
71
MC/DC100%1/1
$stdout // ""
$stdout
Truth table100%2/2
A
A= $stdout
Aresult
11
00
1082 42 return $rows;
1083 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1084  
1085 # _try_count_rows
1086 # Purpose: Count a table's rows, where a failure is only a warning.
1087 # Row counts are optional extras: they must never make an
1088 # exported table count as failed, nor end a dry run.
1089 # Entry Criteria: $self->{programs}{'mdb-count'} is set.
1090 # Exit Status: Returns the count, or undef if it could not be had.
1091 # Side Effects: Runs mdb-count; on failure warns and logs "Cannot count
1092 # the rows of T: E". An interruption is not a failure to
1093 # count: it is passed on, to stop the run.
1094 61 ▶sub _try_count_rows :Private {
Subroutine _try_count_rows: called CC=3 SCAR=11.0
1095 61 my ($self, $database, $table) = @_;
1096  
1097 61 local $@;
1098 61 my $rows = eval { $self->_count_rows($database, $table) };
1099 61 ▶ return $rows if defined $rows;
Branch: 1 branch
BranchTrueFalseTotal
if defined $rows 46 15 61
1100  
1101 15 ▶ die $@ if $self->{interrupted};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"interrupted"} 1 14 15
1102 14 my $error = $@;
1103 14 chomp $error;
1104 14 $self->_warn('count_failed', { params => [$table, $error] });
1105 14 return;
1106 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1107  
1108 # _run_program
1109 # Purpose: Run an mdbtools program and check that it succeeded.
1110 # Shared by every call to mdbtools, so that failures are
1111 # reported consistently.
1112 # Entry Criteria: $name is a key of $self->{programs}; $args is an arrayref;
1113 # $stdout is a scalar ref or a filehandle for run3().
1114 # Exit Status: Returns $self; croaks if the program exits non-zero or
1115 # dies from a signal.
1116 # Side Effects: Runs a child process; writes to $stdout; sets $?.
1117 1722 ▶sub _run_program :Private {
Subroutine _run_program: called CC=8 SCAR=20.8
1118 1722 my ($self, $name, $args, $stdout) = @_;
1119  
1120 # run3 sets $?, and reads captured output back from a temporary file,
1121 # which changes the handle $. refers to; keep the caller's values
1122 1722 local ($?, $.);
1123  
1124 # Start the program in a clean environment (as perlsec asks, and as
1125 # taint mode requires): PATH keeps only absolute directory, and variables
1126 # that can change how a program is started are removed
1127 # (File::Spec->path and path_sep, not ":": Windows separates PATH with
1128 # ";" and its paths contain ":", as in C:\\)
1129 1722 ▶ local $ENV{PATH} = join($Config{path_sep}, map { _untaint($_) } grep { length && File::Spec->file_name_is_absolute($_) } File::Spec->path());
Condition66%2/3
length $_ && 'File::Spec'->file_name_is_absolute($_)
!ll&&!rl&&r
0817473
MC/DC50%1/2
length $_ && 'File::Spec'->file_name_is_absolute($_)
length $_ 'File::Spec'->file_name_is_absolute($_)
Truth table66%2/3
A && B
A= length $_B= 'File::Spec'->file_name_is_absolute($_)
ABresult
0X0
100
111
1130 1722 local @ENV{@UNSAFE_ENV};
1131 1722 delete @ENV{@UNSAFE_ENV};
1132  
1133 # A list (not a string) is passed, so no shell ever sees the file or
1134 # table name and quoting cannot be abused
1135 1722 my $stderr = '';
1136 1722 run3([$self->{programs}{$name}, @{$args}], \undef, $stdout, \$stderr);
1137  
1138 # Distinguish "never started" (-1) and a signal from an ordinary
1139 # non-zero exit status; $! only means something in the first case
1140 1716 my ($status, $reason) = ($?, "$!");
1141 1716 chomp $stderr;
1142 1716 ▶ if($status == -1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($status == -1) 6 1710 1716
1143 6 $self->_croak_i18n('program_not_run', { params => [$name, $reason] });
1144 }
1145 1710 ▶ if($status & 127) {
Branch: 1 branch
BranchTrueFalseTotal
if ($status & 127) 14 1696 1710
1146 # While system() waits, Perl ignores INT and QUIT in this process,
1147 # so Ctrl-C shows up only as the child dying of SIGINT. Treat
1148 # that as the user stopping the whole run, not as a bad table.
1149 14 ▶ my $signal = (split ' ', $Config{sig_name})[$status & 127] // '';
Condition50%1/2
(split(' ', $App::Access2CSV::Exporter::Config{"sig_name"}, 0))[$status & 127] // ""
l!l
140
MC/DC0%0/1
(split(' ', $App::Access2CSV::Exporter::Config{"sig_name"}, 0))[$status & 127] // ""
(split(' ', $App::Access2CSV::Exporter::Config{"sig_name"}, 0))[$status & 127]
Truth table50%1/2
A
A= (split(' ', $App::Access2CSV::Exporter::Config{"sig_name"}, 0))[$status & 127]
Aresult
11
00
1150 14 ▶ if($signal eq 'INT' || $signal eq 'QUIT') {
Branch: 1 branch
BranchTrueFalseTotal
if ($signal eq "INT" or $signal eq "QUIT") 3 11 14
Condition66%2/3
$signal eq "INT" or $signal eq "QUIT"
l!l&&r!l&&!r
3011
MC/DC50%1/2
$signal eq "INT" or $signal eq "QUIT"
$signal eq "INT" $signal eq "QUIT"
Truth table66%2/3
A or B
A= $signal eq "INT"B= $signal eq "QUIT"
ABresult
1X1
011
000
1151 3 $self->{interrupted} = $signal;
1152 3 $self->_croak_i18n('interrupted', { params => [$signal] });
1153 }
1154 11 $self->_croak_i18n('program_signalled', { params => [$name, $status & 127] });
1155 }
1156 1696 ▶ if($status) {
Branch: 1 branch
BranchTrueFalseTotal
if ($status) 33 1663 1696
1157 33 $self->_croak_i18n('program_failed', { params => [$name, $status >> 8, $stderr] });
1158 }
1159 1663 return $self;
1160 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1161  
1162 # _csv_filename
1163 # Purpose: Turn a table name into a safe, unique CSV file name.
1164 # Entry Criteria: $table is a table name (possibly empty).
1165 # Exit Status: Returns a file name (no directory) ending in ".csv".
1166 # Side Effects: Records the name in $self->{used_names}.
1167 #
1168 # Names are compared case-insensitively, because Windows and macOS file
1169 # systems are, so "Orders" and "ORDERS" do not overwrite each other.
1170 # The loop (rather than a single suffix) guarantees uniqueness even when
1171 # another table is literally called "Orders_2".
1172 17112 ▶sub _csv_filename :Protected {
Subroutine _csv_filename: called CC=9 SCAR=22.0
1173 17112 my ($self, $table) = @_;
1174  
1175 17112 ▶ my $name = $table // '';
Condition100%2/2
$table // ""
l!l
171084
MC/DC100%1/1
$table // ""
$table
Truth table100%2/2
A
A= $table
Aresult
11
00
1176  
1177 # macOS only accepts file names that are valid UTF-8 (anything else
1178 # fails with "Illegal byte sequence"). mdbtools gives UTF-8, so other
1179 # bytes come from a damaged database: each one becomes "_", on every
1180 # system, so a table gets the same file name everywhere
1181 17112 ▶ if(!utf8::is_utf8($name)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (utf8::is_utf8($name)) 17110 2 17112
1182 17110 ▶ $name = $UTF8_CODEC->encode($UTF8_CODEC->decode($name, sub { '_' }));
Subroutine __ANON__: called CC=1 SCAR=0.0
1183 }
1184  
1185 # Replace characters that are illegal somewhere, then strip leading
1186 # and trailing whitespace; Windows also silently drops trailing dots
1187 17112 $name =~ s/$UNSAFE_CHARS_RE/_/g;
1188 17112 $name =~ s/$BIDI_CONTROLS_RE/_/g;
1189  
1190 # C1 controls (U+0080-U+009F; U+009B acts like ESC [ on terminals).
1191 # In a byte string they must be matched as their UTF-8 form, because a
1192 # bare [\x80-\x9F] would also hit the continuation bytes of ordinary
1193 # characters such as the Euro sign (E2 82 AC)
1194 17112 ▶ if(utf8::is_utf8($name)) {
Branch: 1 branch
BranchTrueFalseTotal
if (utf8::is_utf8($name)) { } 2 17110 17112
1195 2 $name =~ s/[\x{80}-\x{9F}]/_/g;
1196 } else {
1197 17110 $name =~ s/\xC2[\x80-\x9F]/_/g;
1198 }
1199 17112 $name =~ s/\A\s+//;
1200  
1201 # Shorten over-long names (a hostile or corrupt database can give any
1202 # length), before trailing spaces and dots are removed, as shortening
1203 # may leave some at the end
1204 17112 $name = $self->_shorten_name($name);
1205 17112 $name =~ s/[\s.]+\z//;
1206  
1207 # Avoid hidden files, Windows device names and empty names
1208 17112 $name =~ s/\A\./_/;
1209 17112 ▶ $name = "_$name" if $name =~ $RESERVED_NAME_RE;
Branch: 1 branch
BranchTrueFalseTotal
if $name =~ /$RESERVED_NAME_RE/i 5 17107 17112
1210 17112 ▶ $name = $UNNAMED unless length $name;
Branch: 1 branch
BranchTrueFalseTotal
unless length $name 11 17101 17112
1211  
1212 # Find the smallest free suffix (_2, _3, ...). Start from where this
1213 # name's last search ended rather than from 2: every suffix below that
1214 # point was taken then and is still taken (names are never released
1215 # during a run), so the answer is the same, but N tables with the same
1216 # name cost O(N) in total instead of O(N squared).
1217 17112 my $used = $self->{used_names};
1218 17112 my $base = lc $name;
1219 17112 my $file = $name . $CSV_SUFFIX;
1220 17112 ▶ if(exists $used->{lc $file}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $$used{lc $file}) 11698 5414 17112
1221 11698 ▶ my $n = $self->{next_suffix}{$base} // 2;
Condition100%2/2
$self->{"next_suffix"}{$base} // 2
l!l
74414257
MC/DC100%1/1
$self->{"next_suffix"}{$base} // 2
$self->{"next_suffix"}{$base}
Truth table100%2/2
A
A= $self->{"next_suffix"}{$base}
Aresult
11
00
1222 11698 ▶ $n++ while exists $used->{lc "${name}_$n$CSV_SUFFIX"};
Branch: 1 branch
BranchTrueFalseTotal
exists $$used{lc "${name}_$n$CSV_SUFFIX"} and do { ++$n } 1286 11698 12984
1223 11698 $file = "${name}_$n$CSV_SUFFIX";
1224 11698 $self->{next_suffix}{$base} = $n + 1;
1225 }
1226 17112 $used->{lc $file} = 1;
1227  
1228 17112 return $file;
1229 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1230  
1231 # _shorten_name
1232 # Purpose: Keep a file name within $MAX_NAME_CHARS characters and
1233 # $MAX_NAME_BYTES bytes of UTF-8, without cutting a
1234 # character, or a character from its accents (a grapheme,
1235 # such as a joined emoji), in half.
1236 # Entry Criteria: $name is a character string, or a byte string of valid
1237 # UTF-8 (_csv_filename has replaced any other bytes).
1238 # Exit Status: Returns $name if it fits, otherwise its longest
1239 # beginning that fits, in the same form (bytes or
1240 # characters).
1241 # Side Effects: None.
1242 17123 ▶sub _shorten_name :Private {
Subroutine _shorten_name: called CC=8 SCAR=20.8
1243 17123 my ($self, $name) = @_;
1244  
1245 17123 my $chars = utf8::is_utf8($name);
1246 17123 my $bytes = $name;
1247 17123 ▶ utf8::encode($bytes) if $chars;
Branch: 1 branch
BranchTrueFalseTotal
if $chars 7 17116 17123
1248  
1249 17123 my $text = $bytes;
1250 17123 utf8::decode($text);
1251 17123 ▶ return $name if length($text) <= $MAX_NAME_CHARS && length($bytes) <= $MAX_NAME_BYTES;
Branch: 1 branch
BranchTrueFalseTotal
if length $text <= $MAX_NAME_CHARS and length $bytes <= $MAX_NAME_BYTES 17101 22 17123
Condition100%3/3
length $text <= $MAX_NAME_CHARS and length $bytes <= $MAX_NAME_BYTES
!ll&&!rl&&r
19317101
MC/DC100%2/2
length $text <= $MAX_NAME_CHARS and length $bytes <= $MAX_NAME_BYTES
length $text <= $MAX_NAME_CHARS length $bytes <= $MAX_NAME_BYTES
Truth table100%3/3
A and B
A= length $text <= $MAX_NAME_CHARSB= length $bytes <= $MAX_NAME_BYTES
ABresult
0X0
100
111
1252  
1253 # Whole graphemes, as many as fit both limits
1254 22 my ($kept, $count, $size) = ('', 0, 0);
1255 22 foreach my $grapheme ($text =~ /(\X)/g) {
1256 1271 my $encoded = $grapheme;
1257 1271 utf8::encode($encoded);
1258 1271 ▶ last if $count + length($grapheme) > $MAX_NAME_CHARS
Branch: 1 branch
BranchTrueFalseTotal
if $count + length($grapheme) > $MAX_NAME_CHARS or $size + length($encoded) > $MAX_NAME_BYTES 22 1249 1271
Condition100%3/3
$count + length($grapheme) > $MAX_NAME_CHARS or $size + length($encoded) > $MAX_NAME_BYTES
l!l&&r!l&&!r
1931249
MC/DC100%2/2
$count + length($grapheme) > $MAX_NAME_CHARS or $size + length($encoded) > $MAX_NAME_BYTES
$count + length($grapheme) > $MAX_NAME_CHARS $size + length($encoded) > $MAX_NAME_BYTES
Truth table100%3/3
A or B
A= $count + length($grapheme) > $MAX_NAME_CHARSB= $size + length($encoded) > $MAX_NAME_BYTES
ABresult
1X1
011
000
1259 || $size + length($encoded) > $MAX_NAME_BYTES;
1260 1249 $kept .= $grapheme;
1261 1249 $count += length $grapheme;
1262 1249 $size += length $encoded;
1263 }
1264 22 ▶ utf8::encode($kept) unless $chars;
Branch: 1 branch
BranchTrueFalseTotal
unless $chars 17 5 22
1265 22 return $kept;
1266 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1267  
1268 # _dry_run
1269 # Purpose: Print the table -> file mapping without writing anything.
1270 # Entry Criteria: $tables is the arrayref of selected tables.
1271 # Exit Status: Returns $self.
1272 # Side Effects: Prints to STDOUT; runs mdb-count when show_counts is on.
1273 67 ▶sub _dry_run :Private {
Subroutine _dry_run: called CC=6 SCAR=17.9
1274 67 my ($self, $database, $tables) = @_;
1275  
1276 # Only show the ROWS column when counts are actually available
1277 67 my $counts = $self->{show_counts};
1278 67 ▶ my $format = $counts
Branch: 1 branch
BranchTrueFalseTotal
$counts ? : 14 53 67
1279 ? "%-${TABLE_COLUMN_WIDTH}s %${ROWS_COLUMN_WIDTH}s %s\n"
1280 : "%-${TABLE_COLUMN_WIDTH}s %s\n";
1281 67 ▶ my @header = map { $self->i18n($_) } ($counts ? qw(column_table column_rows column_output) : qw(column_table column_output));
Branch: 1 branch
BranchTrueFalseTotal
$counts ? : 14 53 67
1282  
1283 # Underline the title to the length of whatever the translation is
1284 67 my $title = $self->i18n('dry_run_title');
1285 67 print "\n$title\n", '=' x length($title), "\n\n";
1286 67 printf $format, @header;
1287 67 print '-' x $RULE_WIDTH, "\n";
1288  
1289 67 foreach my $table (@{$tables}) {
1290 90 my @row = ($table);
1291 # A count that cannot be had is shown as "?" (with a warning), so a
1292 # dry run still lists every table and succeeds
1293 90 ▶ push @row, $self->_try_count_rows($database, $table) // $UNKNOWN_COUNT if $counts;
Branch: 1 branch
BranchTrueFalseTotal
if $counts 19 71 90
Condition66%2/3
$self->_try_count_rows($database, $table) // $UNKNOWN_COUNT
l!l&&r!l&&!r
1450
MC/DC0%0/2
$self->_try_count_rows($database, $table) // $UNKNOWN_COUNT
$self->_try_count_rows($database, $table) $UNKNOWN_COUNT
Truth table66%2/3
A // B
A= $self->_try_count_rows($database, $table)B= $UNKNOWN_COUNT
ABresult
1X1
011
000
1294 # The table name comes from the database, so show it escaped (the
1295 # file name is already safe; escaping it too costs nothing)
1296 90 $row[0] = $self->_printable($row[0]);
1297 90 printf $format, @row, $self->_printable($self->_csv_filename($table));
1298 }
1299 67 print "\n";
1300  
1301 67 return $self;
1302 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1303  
1304 # _warn
1305 # Purpose: Warn the user and record the same text in the log.
1306 # Entry Criteria: $key is a catalog key; $args an optional i18n() hashref.
1307 # Exit Status: Returns $self.
1308 # Side Effects: carp()s; logs at warn level.
1309 110 ▶sub _warn :Private {
Subroutine _warn: called CC=1 SCAR=0.0
1310 110 my ($self, $key, $args) = @_;
1311  
1312 110 $self->_carp_i18n($key, $args);
1313 110 return $self->_log(warn => $key, $args);
1314 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1315  
1316 # _log
1317 # Purpose: Send a localised message to the logger, if there is one.
1318 # Entry Criteria: $level is a logger method name (debug, info or warn).
1319 # Exit Status: Returns $self.
1320 # Side Effects: Calls $self->{logger}->$level().
1321 1648 ▶sub _log :Private {
Subroutine _log: called CC=3 SCAR=11.0
1322 1648 my ($self, $level, $key, $args) = @_;
1323  
1324 1648 ▶ my $logger = $self->{logger} or return $self;
Branch: 1 branch
BranchTrueFalseTotal
my $logger = $self->{"logger"} or return $self 174 1474 1648
1325  
1326 # Logging is secondary: a logger that dies (full disk, closed socket)
1327 # must not make a finished export look failed. Say so once and stop
1328 # using it.
1329 174 local $@;
1330 # Escaped, so a hostile table name cannot forge log lines (CR, LF)
1331 # or send escape sequences to whoever views the log
1332 174 ▶ if(!eval { $logger->$level($self->_printable($self->i18n($key, $args))); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (eval { do { $logger->$level($self->_printable($self->i18n($key, $args))); 1 } }) 5 169 174
1333 5 my $error = $@;
1334 5 chomp $error;
1335 5 delete $self->{logger};
1336 5 $self->_carp_i18n('log_failed', { params => [$error] });
1337 }
1338 174 return $self;
1339 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1340  
1341 # _validation_reason
1342 # Purpose: Reduce a Params::Validate::Strict error to its meaning,
1343 # e.g. "Parameter 'encoding' (latin1) must be one of utf8,
1344 # utf8-bom, cp1252", dropping the module's own prefix
1345 # ("Params::Validate::Strict line N: validate_strict: ")
1346 # and the Perl location it appends.
1347 # Entry Criteria: $error is the exception from validate_strict.
1348 # Exit Status: Returns a one-line string.
1349 # Side Effects: None. A plain function, not a method.
1350 92 ▶sub _validation_reason :Private {
Subroutine _validation_reason: called CC=1 SCAR=0.0
1351 92 my $error = shift;
1352  
1353 92 my $reason = "$error";
1354 92 $reason =~ s/\AParams::Validate::Strict line \d+: //;
1355 92 $reason =~ s/\Avalidate_strict: //;
1356 92 $reason =~ s/ at \S+ line \d+\.?\n?\z//;
1357 92 chomp $reason;
1358 92 return $reason;
1359 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1360  
1361 # _untaint
1362 # Purpose: Mark a value that has already been validated as safe for
1363 # taint mode.
1364 # Entry Criteria: $value has been checked by the caller (see each call).
1365 # Exit Status: Returns the untainted value; returns $value unchanged if
1366 # it is empty or contains a NUL (it will then fail safely
1367 # at the operating system, still tainted).
1368 # Side Effects: None. A plain function, not a method.
1369 20482 ▶sub _untaint :Private {
Subroutine _untaint: called CC=3 SCAR=11.1
1370 20482 my $value = shift;
1371  
1372 20482 ▶ return ($value // '') =~ $UNTAINT_RE ? $1 : $value;
Branch: 1 branch
BranchTrueFalseTotal
($value // '') =~ /$UNTAINT_RE/s ? : 20481 1 20482
Condition50%1/2
$value // ""
l!l
204820
MC/DC0%0/1
$value // ""
$value
Truth table50%1/2
A
A= $value
Aresult
11
00
1373 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1374  
1375 # _os_error
1376 # Purpose: Get a readable OS error from an autodie exception or string.
1377 # Entry Criteria: $error is whatever eval left in $@.
1378 # Exit Status: Returns a string.
1379 # Side Effects: None. A plain function, not a method.
1380 14 ▶sub _os_error :Private {
Subroutine _os_error: called CC=3 SCAR=11.0
1381 14 my $error = shift;
1382  
1383 # autodie::exception keeps the original $! for us. blessed(), not
1384 # ref(): asking an unblessed reference ->can() would die and hide
1385 # the real error.
1386 14 ▶ my $text = (blessed($error) && $error->can('errno')) ? $error->errno() : "$error";
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($error) && $error->can('errno') ? : 9 5 14
Condition100%3/3
builtin::blessed($error) and $error->can("errno")
!ll&&!rl&&r
419
MC/DC100%2/2
builtin::blessed($error) and $error->can("errno")
builtin::blessed($error) $error->can("errno")
Truth table100%3/3
A and B
A= builtin::blessed($error)B= $error->can("errno")
ABresult
0X0
100
111
1387 14 chomp $text;
1388 14 return $text;
1389 36 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
1390  
1391 36 1;
1392  
1393 __END__
« lib/App/Access2CSV.pm ↑ Summary /usr/local/bin/perldoc »