lib/App/Access2CSV.pm

filter: Statementstmt 99.4% 184 / 185 Branchbran 94.6% 53 / 56 Conditioncond 86.9% 20 / 23 MC/DCmcdc 75.0% 9 / 12 Subroutinesub 100% 38 / 38 Podpod 100% 1 / 1 totaltotal 96.8% 305 / 315 CC 38 SCAR 14.9
CC
38
Cov
97%
_parse_options
9.0
_make_logger
8.0
run
8.0
CRAP 4.4
« lib/App/Access2CSV/I18N.pm ↑ Summary lib/App/Access2CSV/Exporter.pm »
1 package App::Access2CSV;
2  
3 42 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 42 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 42 ▶use autodie qw(:all);
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 # Sub::Private must be in enforce mode before it is loaded, so that
8 # private class methods still work through $class->method dispatch
9 42 ▶BEGIN { $Sub::Private::config{mode} = 'enforce' }
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 # Inherit i18n() and the protected _croak_i18n/_carp_i18n helpers
12 42 ▶use parent 'App::Access2CSV::I18N';
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 36 ▶use App::Access2CSV::Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 34 ▶use Errno qw(EISDIR);
Subroutine BEGIN: called CC=1 SCAR=0.0
16 34 ▶use Fcntl qw(O_APPEND O_CREAT O_WRONLY);
Subroutine BEGIN: called CC=1 SCAR=0.0
17 34 ▶use File::Temp;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 34 ▶use Getopt::Long qw(GetOptionsFromArray);
Subroutine BEGIN: called CC=1 SCAR=0.0
19 34 ▶use IO::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
20 34 ▶use Log::Abstraction;
Subroutine BEGIN: called CC=1 SCAR=0.0
21 33 ▶use Pod::Usage qw(pod2usage);
Subroutine BEGIN: called CC=1 SCAR=0.0
22 33 ▶use Readonly;
Subroutine BEGIN: called CC=1 SCAR=0.0
23 33 ▶use Return::Set qw(set_return);
Subroutine BEGIN: called CC=1 SCAR=0.0
24 33 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
25 33 ▶use Sub::Private;
Subroutine BEGIN: called CC=1 SCAR=0.0
26  
27 33 our $VERSION = '0.001.1';
28  
29 # ---------------------------------------------------------------------
30 # Roadmap (from the pre-release gap analysis)
31 #
32 # Features
33 # TODO: Pass mdbtools' CSV options through: --delimiter, --quote,
34 # --date-format, --no-header, binary column handling (mdb-export's
35 # -d, -q, -D, -H and -b).
36 # TODO: --schema: write each table's definition next to its data, using
37 # mdb-schema.
38 # TODO: Export one table to standard output (--table X --output -), for
39 # use in pipes.
40 # TODO: --gzip, or a single ZIP file holding all the CSV files.
41 # TODO: More output formats: JSON Lines, and SQL INSERT statements
42 # (mdb-export -I).
43 # TODO: --jobs N: export several tables at once. Starting one mdbtools
44 # process per table is the main cost of a run.
45 # TODO: A second back end using ODBC (DBD::ODBC with the Microsoft Access
46 # driver), so Windows does not need mdbtools.
47 # TODO: Ship at least one real translation (e.g. German) to prove the
48 # message catalog end to end.
49 # TODO: Read settings from a configuration file via Object::Configure;
50 # %DEFAULTS is already laid out for it.
51 # TODO: Optionally exit 130 on Ctrl-C (the shell convention), not 3.
52 #
53 # Technical debt
54 # TODO: Sub::Private/Sub::Protected hide the real subs from Devel::Cover
55 # (worked around by the CHECK block in I18N.pm) and refuse
56 # Test::Mockingbird hooks unless $Sub::*::BYPASS is set. Fix both in
57 # Sub::Private/Sub::Protected, then drop the workaround.
58 # TODO: Remove the IO::Handle::flush workaround in t/edge_cases.t once the
59 # Test::Mockingbird fix for mocking inherited methods is released.
60 # TODO: IPC::Run3 does not reveal the child's process ID, so after SIGTERM
61 # the running mdb-export is not stopped. Moving to IPC::Run or
62 # IPC::Open3 would allow that, and streaming for --jobs.
63 # TODO: I18N.pm also holds helpers unrelated to messages (_printable,
64 # _interrupt_signals, the coverage CHECK block); move them to a small
65 # shared module, and remove the duplicated control-character patterns
66 # (I18N.pm and Exporter.pm) at the same time.
67 # TODO: The test files repeat the same helpers (slurp, new_database, cli,
68 # stand-in set-up); a shared t/lib helper module would shrink them and
69 # remove most Windows skips in one place.
70 # TODO: Tests read exporter internals ($e->{show_counts}, {used_names});
71 # small read-only accessors would make refactoring safer.
72 # ---------------------------------------------------------------------
73  
74 # Stop Carp from reporting errors against the access-control wrappers
75 33 our @CARP_NOT = qw(Sub::Private Sub::Protected App::Access2CSV::I18N);
76  
77 # Exit statuses, documented in the POD below
78 33 Readonly::Scalar my $EXIT_OK => 0;
79 33 Readonly::Scalar my $EXIT_FAILURE => 1;
80 33 Readonly::Scalar my $EXIT_USAGE => 2;
81 33 Readonly::Scalar my $EXIT_FATAL => 3;
82  
83 # Pod::Usage verbosity levels for --help and --man, and for usage errors
84 33 Readonly::Scalar my $POD_SYNOPSIS => 0;
85 33 Readonly::Scalar my $POD_OPTIONS => 1;
86 33 Readonly::Scalar my $POD_FULL => 2;
87  
88 # The database name that means "read it from standard input"
89 33 Readonly::Scalar my $STDIN_NAME => '-';
90  
91 # Standard input is copied, in chunks of this many bytes, to a private
92 # temporary file named from this template (mdbtools need a real file)
93 33 Readonly::Scalar my $READ_CHUNK => 65_536;
94 33 Readonly::Scalar my $STDIN_TEMPLATE => 'access2csv-stdin-XXXXXX';
95  
96 # Log levels: --verbose adds the debug messages
97 33 Readonly::Scalar my $LOG_LEVEL => 'info';
98 33 Readonly::Scalar my $LOG_LEVEL_VERBOSE => 'debug';
99  
100 # Command-line defaults; the flat layout is compatible with Object::Configure
101 33 Readonly::Hash my %DEFAULTS => (
102 output_dir => '.',
103 overwrite => 0,
104 verbose => 0,
105 dry_run => 0,
106 show_counts => 0,
107 progress => 1,
108 encoding => 'utf8',
109 log => 'access2csv.log',
110 );
111  
112 =encoding utf8
113  
114 =head1 NAME
115  
116 App::Access2CSV - Export the tables of a Microsoft Access database to CSV files
117  
118 =head1 VERSION
119  
120 Version 0.001.1
121  
122 =head1 SYNOPSIS
123  
124 # Export every table to the current directory
125 access2csv shop.accdb
126  
127 # See what would be written, with row counts, without writing anything
128 access2csv --dry-run --show-counts shop.accdb
129  
130 # Export only two tables, into a directory called "exports"
131 access2csv --output-dir exports --table Customers --table Orders shop.mdb
132  
133 # Make files that Excel opens correctly, replace old files, no log file
134 access2csv --encoding utf8-bom --overwrite --no-log shop.accdb
135  
136 # Read the database from standard input ("-"), e.g. from a download
137 curl -s https://example.com/shop.accdb | access2csv --output-dir exports -
138  
139 # Nightly job: quiet, with a log in a fixed place, and stop on failure
140 access2csv --no-progress --log /var/log/access2csv.log \
141 --output-dir /srv/exports --overwrite shop.accdb || exit 1
142  
143 =head1 DESCRIPTION
144  
145 Microsoft Access keeps its data in C<.mdb> or C<.accdb> files.
146 C<access2csv> reads one of these files and writes one CSV file
147 (comma-separated values, a plain-text table) for each table in it.
148  
149 It does not read the Access file itself. It runs three small programs
150 from the free B<mdbtools> package:
151  
152 =over 4
153  
154 =item * C<mdb-tables> - to get the list of tables
155  
156 =item * C<mdb-export> - to get the data of each table as CSV
157  
158 =item * C<mdb-count> - to count rows (only when you use B<--show-counts>)
159  
160 =back
161  
162 These programs must be installed and must be in your C<PATH>.
163  
164 Access also keeps its own internal tables in the file. Their names start
165 with C<MSys>, C<USys> or C<~>. They are skipped.
166  
167 =head2 How the CSV files are named
168  
169 Each file has the name of its table plus C<.csv>, for example
170 C<Orders.csv>. Some characters are not allowed in file names on some
171 computers (C<< < > : " / \ | ? * >> and control characters). They are
172 changed to C<_>, and so are invisible text-direction controls (such as
173 U+202E, "right-to-left override"), which could make a file name look
174 like something else. Bytes that are not valid UTF-8 (only a damaged
175 database has them, and macOS cannot store them in a file name) are also
176 changed to C<_>. Spaces and dots at the end, and spaces at the start,
177 are removed. A name such as C<CON> or C<NUL> (reserved on Windows) gets a
178 C<_> in front. An empty name becomes C<unnamed>.
179  
180 Access names are at most 64 characters, so a longer name can only come
181 from a damaged database. It is shortened to 64 characters (and to 240
182 bytes, to fit the file name limit of most systems), without cutting a
183 character in half.
184  
185 If two tables would get the same file name, the second one gets C<_2>,
186 the third C<_3>, and so on. Upper and lower case count as the same here,
187 because Windows and macOS treat C<Orders.csv> and C<ORDERS.csv> as one file.
188  
189 =head2 Reading the database from standard input
190  
191 If the database name is C<->, the database is read from standard input
192 instead of a file, so it can be piped in. mdbtools can only read a real
193 file, so the data is first copied to a private temporary file (readable
194 by you only) in the temporary directory (C<TMPDIR>, or F</tmp>), and that
195 copy is deleted when the program ends - whether it succeeds, fails or is
196 interrupted.
197  
198 C<-> is refused if standard input is a terminal (there is nothing to
199 read but the keyboard), and a directory or empty input is an error. To use
200 a file that is really called C<->, write F<./->.
201  
202 =head2 How files are written
203  
204 Each file is first written to a hidden temporary file (its name starts
205 with C<.access2csv->) in the output directory. Only when it is complete
206 is it renamed to its real name. So if something goes wrong, you never
207 get a half-written CSV file, and an old file is only replaced by a
208 complete new one.
209  
210 =head1 REQUIREMENTS
211  
212 The mdbtools programs C<mdb-tables> and C<mdb-export> must be installed
213 and in your C<PATH>; C<mdb-count> is needed only for B<--show-counts>.
214 They are not Perl modules, so the CPAN installer cannot install them for
215 you. Install them with your system's package manager, for example:
216  
217 sudo apt install mdbtools # Debian, Ubuntu
218 sudo dnf install mdbtools # Fedora
219 brew install mdbtools # macOS (Homebrew)
220 pacman -S mingw-w64-x86_64-mdbtools # Windows (MSYS2)
221  
222 Without them the program stops with "Required program not found in
223 PATH". Project home: L<https://github.com/mdbtools/mdbtools>.
224  
225 =head1 USING FROM PERL
226  
227 The program is a very thin wrapper. You can call the same code from Perl:
228  
229 use App::Access2CSV;
230  
231 my $status = App::Access2CSV->run('--no-log', '--output-dir', 'out', 'shop.accdb');
232  
233 For more control, use L<App::Access2CSV::Exporter> directly.
234  
235 =head1 OPTIONS
236  
237 =over 4
238  
239 =item B<--output-dir> I<DIR>
240  
241 The directory to write the CSV files to. It is created if it does not exist.
242 Default: the directory.
243  
244 =item B<--table> I<NAME>
245  
246 Export only this table. You can use this option more than once.
247 Names must match exactly, including upper and lower case. A name that is
248 not in the database gives a warning.
249  
250 =item B<--overwrite>
251  
252 Replace CSV files that already exist. Without this option, a table whose
253 CSV file already exists is not exported, and it counts as a failure.
254  
255 =item B<--verbose>
256  
257 Write more detail to the log (where each mdbtools program was found).
258 Also show the Perl file and line number in fatal error messages.
259  
260 =item B<--dry-run>
261  
262 Only print a list of the tables and the file names they would get.
263 Nothing is written. The output directory is not created.
264  
265 =item B<--show-counts>
266  
267 Show the number of rows of each table: in the dry-run list, and in the
268 log. This needs C<mdb-count>. Without it you get a warning, and the
269 export goes on without counts.
270  
271 =item B<--no-progress>
272  
273 Do not print the C<[1/5] Customers> progress lines. (These lines go to
274 standard error, not standard output.)
275  
276 =item B<--encoding> I<utf8|utf8-bom|cp1252>
277  
278 The character encoding of the CSV files. See L</ENCODING>.
279 Default: C<utf8>.
280  
281 =item B<--log> I<FILE>
282  
283 Add log messages to the end of I<FILE>. Default: F<access2csv.log> in
284 the directory. An empty name (C<--log ''>) means no log. I<FILE>
285 must not be a symbolic link (see L</SECURITY>).
286  
287 =item B<--no-log>
288  
289 Do not write a log file.
290  
291 =item B<--help>, B<-h>
292  
293 Print the synopsis and the options, then stop.
294  
295 =item B<--man>
296  
297 Print this whole manual, then stop.
298  
299 =item B<--version>
300  
301 Print the version ("access2csv version 0.001.1"), then stop.
302  
303 =back
304  
305 =head1 EXIT STATUS
306  
307 The program ends with one of these numbers. Scripts can test it.
308  
309 0 Every selected table was exported. Also used for --dry-run,
310 --help, --man and --version.
311 1 At least one table was not exported. The other tables were.
312 2 The command line was wrong, for example an unknown option, an
313 invalid value (--encoding latin1), no database name, or "-" while
314 standard input is a terminal. Nothing has been done.
315 3 A fatal error happened before any table was exported, for example
316 the database does not exist or mdbtools is not installed.
317  
318 =head1 ENCODING
319  
320 =head2 The data in the CSV files
321  
322 mdbtools gives the table data as UTF-8, the encoding that can hold every
323 character, including accented letters, Chinese and Japanese text, and
324 emoji.
325  
326 =over 4
327  
328 =item * C<utf8> (the default) - the data is copied exactly as mdbtools
329 gives it. Every character, including emoji, is kept.
330  
331 =item * C<utf8-bom> - the same, plus three bytes at the very start of each
332 file (a "byte order mark"). These bytes tell Microsoft Excel that the file
333 is UTF-8. Without them, Excel may show accented letters wrongly. Some
334 other programs show the mark as strange characters in the first column
335 name.
336  
337 =item * C<cp1252> - Windows-1252, an old Western European encoding. It has
338 only 256 characters: English letters, most Western European accented
339 letters, and a few symbols such as the Euro sign. It has no Greek,
340 Cyrillic, Chinese, Japanese or emoji. If a table contains a character
341 that Windows-1252 cannot hold, that table is B<not> exported, and the
342 error message gives the line number. Nothing is silently replaced.
343  
344 =back
345  
346 =head2 Names on the command line
347  
348 Database paths, directory names, log file names and table names are used
349 exactly as the operating system gives them to the program (as bytes).
350 On Linux and macOS, where the terminal uses UTF-8, names with accented
351 letters, non-Latin scripts and emoji work. On Windows, the command line
352 uses the system code page, so names outside that code page may not work.
353  
354 =head2 Messages
355  
356 All messages that the program prints and logs are in plain ASCII English.
357  
358 =head1 ENVIRONMENT
359  
360 =over 4
361  
362 =item C<PATH>
363  
364 Used to find C<mdb-tables>, C<mdb-export> and C<mdb-count>. Only
365 absolute directories in C<PATH> are used: relative entries such as C<.> are
366 ignored, so a program planted in the directory is never run.
367  
368 =item C<LANGUAGE>, C<LC_ALL>, C<LC_MESSAGES>, C<LANG>
369  
370 Choose the language of messages (see L<App::Access2CSV::I18N>). Only the
371 language code at the start is used; any other value means English.
372  
373 =item C<TMPDIR>
374  
375 Where a database read from standard input (C<->) is copied while it is
376 exported. Default: F</tmp>.
377  
378 =item C<MDB_ICONV>
379  
380 Not read by this program, but by mdbtools: it sets the character set
381 mdbtools converts to. Leave it unset, so that the output is UTF-8.
382  
383 =back
384  
385 =head1 SECURITY
386  
387 The program treats the database as untrusted: an Access file received
388 from someone else may contain table names and data designed to cause
389 harm.
390  
391 =over 4
392  
393 =item * B<No shell, no option injection.> Programs are run directly
394 (never through a shell), and table and file names are passed after a
395 C<--> marker, so names containing C<; | $( ) `> or starting with C<->
396 are only ever names.
397  
398 =item * B<No planted programs.> Relative C<PATH> entries are ignored
399 (see L</ENVIRONMENT>). The mdbtools programs are started with a cleaned
400 environment: C<PATH> holds only absolute directories, and C<IFS>, C<CDPATH>,
401 C<ENV> and C<BASH_ENV> are removed.
402  
403 =item * B<Taint mode.> The program runs under Perl's taint mode
404 (C<perl -T>). Every outside value - the database path, table names,
405 C<--output-dir>, C<--log> and the program paths found in C<PATH> - is
406 checked first and only then marked as safe. Under C<-T>, Perl also
407 refuses to start mdbtools while C<PATH> contains a directory other users can
408 write to; the program then stops with "Insecure directory in
409 $ENV{PATH}".
410  
411 =item * B<Private copies of piped input.> A database read from standard
412 input is copied with L<File::Temp> (a new, unpredictable name, readable
413 by you only) and deleted when the program ends, also after an error or
414 an interruption.
415  
416 =item * B<Safe file names.> Table names cannot place a file outside the
417 output directory, and control characters - including invisible
418 text-direction controls and C1 controls - are replaced by C<_>.
419  
420 =item * B<Safe terminal and log output.> Table names and mdbtools error
421 text are printed with control characters shown as escapes such as
422 C<\x1B>. So a table name cannot retitle or clear your terminal, hide
423 text, or forge lines in the log.
424  
425 =item * B<No writing through symbolic links.> If the log file is a
426 symbolic link (for example one planted in a shared directory such as
427 F</tmp>), the program stops instead of writing to the file it points at.
428 Existing CSV files that are links are replaced, never written through.
429  
430 =item * B<Spreadsheet formulas are NOT neutralised.> A value such as
431 C<=cmd|' /C calc'!A0> is copied into the CSV exactly as it is in the
432 database, because changing data would corrupt genuine values. Some
433 spreadsheet programs run such formulas when a CSV is opened. Do not open
434 CSV files exported from an untrusted database in a spreadsheet without
435 checking them, or import them as text.
436  
437 =back
438  
439 =head1 COMMON PITFALLS
440  
441 =over 4
442  
443 =item * B<A log file appears in the directory directory.> By default the log is
444 F<access2csv.log> in the directory you run the program from. Use B<--log> to
445 choose another place, or B<--no-log>.
446  
447 =item * B<The second run fails.> If the CSV files already exist, each table
448 fails (exit status 1) unless you give B<--overwrite>.
449  
450 =item * B<--table does not find my table.> Table names are case-sensitive:
451 C<--table orders> does not match C<Orders>. Use B<--dry-run> to see the
452 exact names.
453  
454 =item * B<A file is called Orders_2.csv.> Two tables had names that give
455 the same file name (for example C<Orders> and C<ORDERS>, or C<A/B> and
456 C<A:B>).
457  
458 =item * B<Progress lines appear even though I redirected the output.>
459 Progress lines go to standard error. Use B<--no-progress>, or redirect
460 standard error too (C<2E<gt>/dev/null>).
461  
462 =item * B<run() does not end the program.> When calling from Perl,
463 C<< App::Access2CSV->run(...) >> returns the exit status. It does not
464 call C<exit>. Write C<< exit App::Access2CSV->run(@ARGV) >> if you want
465 the program to end.
466  
467 =item * B<Pass a list, not an array reference.> Write
468 C<< App::Access2CSV->run(@args) >>, not C<< App::Access2CSV->run(\@args) >>.
469  
470 =item * B<A file called "-".> C<-> means standard input, even after
471 C<-->. Write F<./-> for a file with that name.
472  
473 =item * B<Piped databases need temporary space.> The whole database is
474 copied to the temporary directory first; if that directory is small, set
475 C<TMPDIR> to one with room.
476  
477 =back
478  
479 =head1 METHODS
480  
481 =head2 run
482  
483 =head3 Purpose
484  
485 This is the whole C<access2csv> program. It reads the command-line
486 options, opens the log, and runs an L<App::Access2CSV::Exporter>.
487  
488 =head3 Arguments
489  
490 The command-line arguments, as a list of strings (normally C<@ARGV>).
491 Your array is copied first, so it is not changed.
492  
493 =head3 Returns
494  
495 A number from 0 to 3, as described in L</EXIT STATUS>.
496 C<run> never calls C<exit> itself.
497  
498 =head3 Side Effects
499  
500 =over 4
501  
502 =item * Everything that L<App::Access2CSV::Exporter/run> does: it creates
503 the output directory, writes CSV files, and prints progress to standard error.
504  
505 =item * It prints help or usage text (help to standard output, usage errors
506 to standard error).
507  
508 =item * It prints a fatal error, if there is one, to standard error as one
509 line that starts with C<access2csv:>.
510  
511 =item * It creates or adds to the log file, unless logging is off.
512  
513 =item * It leaves your C<$@>, C<$!>, C<$_> and any pending C<alarm> as
514 they were.
515  
516 =back
517  
518 =head3 Usage
519  
520 exit App::Access2CSV->run(@ARGV);
521  
522 =head3 EXAMPLE
523  
524 use App::Access2CSV;
525  
526 # Export to ./out without a log file, then check what happened
527 my $status = App::Access2CSV->run('--output-dir', 'out', '--no-log', 'shop.accdb');
528  
529 if($status == 0) {
530 print "All tables were exported\n";
531 } elsif($status == 1) {
532 print "Some tables could not be exported\n";
533 } elsif($status == 2) {
534 print "The arguments were wrong\n";
535 } else {
536 print "Nothing was exported\n";
537 }
538  
539 =head3 API SPECIFICATION
540  
541 =head4 Input
542  
543 {
544 argv => {
545 type => 'arrayref',
546 optional => 1,
547 element_type => 'string',
548 description => 'Command-line arguments, passed as a list',
549 },
550 }
551  
552 Valid and invalid values (tested in F<t/domain.t>):
553  
554 database names exactly 1; 0 or 2 or more give exit status 2.
555 "-" means standard input (exit 2 if it is a
556 terminal, 3 if it is empty or unreadable)
557 --encoding utf8, utf8-bom or cp1252; anything else gives exit 2
558 --table 0 times (all tables), once, or many times; names
559 may be non-ASCII
560 --log a file name; '' means no log, like --no-log
561  
562 =head4 Output
563  
564 {
565 type => 'integer',
566 min => 0,
567 max => 3,
568 }
569  
570 =head3 MESSAGES
571  
572 +-------------------------------------+-------------------------------+------------------------------+
573 | Message | Meaning | What to do |
574 +-------------------------------------+-------------------------------+------------------------------+
575 | Unknown option: X (exit 2) | X is not an option of this | See --help |
576 | | program | |
577 | Option X requires an argument | An option such as --log was | Give a value after it |
578 | (exit 2) | the last word | |
579 | Invalid setting: REASON (exit 2) | An option value is not | Use a documented value (see |
580 | | allowed, e.g. --encoding | OPTIONS) |
581 | | latin1; REASON says which | |
582 | Missing database filename (exit 2) | No database name was given, | Give exactly one database |
583 | | it was empty, or more than | |
584 | | one was given | |
585 | Standard input is a terminal: pipe | "-" was given, but nothing is | Pipe the database in, or |
586 | the database in, or give its file | piped in | give its file name |
587 | name (exit 2) | | |
588 | access2csv: Standard input is empty:| "-" was given, but the pipe | Check the command that |
589 | no database was piped in (exit 3) | delivered nothing | produces the database |
590 | access2csv: Cannot read standard | Reading the pipe failed; E is | See E |
591 | input: E (exit 3) | the reason ("Is a directory" | |
592 | | if a directory was given) | |
593 | access2csv: Interrupted by SIGx | Stopped (Ctrl-C, kill) while | Run again |
594 | while reading the database from | waiting for piped input; the | |
595 | standard input (exit 3) | partial copy was deleted | |
596 | access2csv: Cannot open log file F: | The log file cannot be | Use --log with another file, |
597 | E (exit 3) | written; E is the reason from | or --no-log |
598 | | the operating system, "no | |
599 | | logger was created", or "it | |
600 | | is a symbolic link" | |
601 | access2csv: MESSAGE (exit 3) | Any fatal error from the | See MESSAGES in |
602 | | exporter | App::Access2CSV::Exporter |
603 +-------------------------------------+-------------------------------+------------------------------+
604  
605 =head3 PSEUDOCODE
606  
607 options := default settings
608 read the command line into options
609 if the command line is wrong: print usage, return 2
610 if --help or --man: print the documentation, return 0
611 if there is not exactly one database name: print usage, return 2
612 try:
613 open the log, unless logging is off
614 status := new Exporter(options).run(database)
615 if that failed:
616 print "access2csv: <reason>" to standard error
617 status := 3
618 return status
619  
620 =cut
621  
622 201 ▶sub run {
Subroutine run: called CC=8 SCAR=20.8
Pod documented
623 201 my ($class, @argv) = @_;
624  
625 # Option parsing, file tests and the eval below would otherwise leave
626 # their marks in the caller's $@ and $!
627 201 local ($@, $!);
628  
629 # Parsing may already decide the outcome (--help, bad options, ...)
630 201 my %opt = %DEFAULTS;
631 201 my $status = $class->_parse_options(\@argv, \%opt);
632  
633 # CHECKING SETTINGS: a bad option value (e.g. --encoding latin1) is a
634 # command-line mistake like any other: a usage error (exit 2), found
635 # before anything with a side effect happens - before standard input
636 # is copied and before the log file is created
637 201 my %settings = map { $_ => $opt{$_} } grep { $_ ne 'log' } keys %opt;
638 201 ▶ if(!defined($status) && !eval { App::Access2CSV::Exporter->new(%settings); 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $status or eval { do { "App::Access2CSV::Exporter"->new(%settings); 1 } }) 6 195 201
Condition100%3/3
defined $status or eval { do { "App::Access2CSV::Exporter"->new(%settings); 1 } }
l!l&&r!l&&!r
511446
MC/DC100%2/2
defined $status or eval { do { "App::Access2CSV::Exporter"->new(%settings); 1 } }
defined $status eval { do { "App::Access2CSV::Exporter"->new(%settings); 1 } }
Truth table100%3/3
A or B
A= defined $statusB= eval { do { "App::Access2CSV::Exporter"->new(%settings); 1 } }
ABresult
1X1
011
000
639 6 $status = $class->_usage($EXIT_USAGE, $POD_SYNOPSIS, _strip_location($@));
640 }
641  
642 201 ▶ if(!defined $status) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $status) 144 57 201
643 # Any croak from here on is a fatal error: report it, don't die
644 144 $status = eval {
645 # READING STDIN: "-" means standard input. mdbtools can only
646 # read a real file, so the data is copied to a private temporary
647 # file first; the copy is deleted when $piped goes out of scope,
648 # whatever happens
649 144 ▶ my $piped = ($argv[0] eq $STDIN_NAME) ? $class->_read_stdin() : undef;
Branch: 1 branch
BranchTrueFalseTotal
$argv[0] eq $STDIN_NAME ? : 18 126 144
650 132 ▶ my $database = $piped ? $piped->filename() : $argv[0];
Branch: 1 branch
BranchTrueFalseTotal
$piped ? : 6 126 132
651  
652 # OPENING LOG, then EXPORTING
653 132 my $logger = $class->_make_logger(\%opt);
654 119 ▶ App::Access2CSV::Exporter->new(%settings, ($logger ? (logger => $logger) : ()))->run($database);
Branch: 1 branch
BranchTrueFalseTotal
$logger ? : 24 95 119
655 };
656 144 ▶ $status = $class->_report_fatal($@, $opt{verbose}) unless defined $status;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $status 60 84 144
657 }
658  
659 201 return set_return($status, { type => 'integer', min => $EXIT_OK, max => $EXIT_FATAL });
660 }
661  
662 # _parse_options
663 # Purpose: Turn the command line into settings.
664 # Entry Criteria: $argv is an arrayref (modified in place: options are
665 # removed, leaving the positional arguments); $opt is a
666 # hashref of defaults.
667 # Exit Status: Returns undef if the export should go ahead, otherwise
668 # the exit status to return straight away.
669 # Side Effects: Fills in $opt; prints help, the manual or usage text.
670 211 ▶sub _parse_options :Private {
Subroutine _parse_options: called CC=9 SCAR=22.0
671 211 my ($class, $argv, $opt) = @_;
672  
673 211 my ($help, $show_version) = (0, 0);
674 my $parsed = GetOptionsFromArray(
675 $argv,
676 'output-dir=s' => \$opt->{output_dir},
677 'table=s@' => \$opt->{tables},
678 'overwrite!' => \$opt->{overwrite},
679 'verbose!' => \$opt->{verbose},
680 'dry-run!' => \$opt->{dry_run},
681 'show-counts!' => \$opt->{show_counts},
682 'progress!' => \$opt->{progress},
683 'encoding=s' => \$opt->{encoding},
684 'log=s' => \$opt->{log},
685 116 ▶ 'no-log' => sub { $opt->{log} = undef },
Subroutine __ANON__: called CC=1 SCAR=0.0
686 17 ▶ 'help|h' => sub { $help = $POD_OPTIONS },
Subroutine __ANON__: called CC=1 SCAR=0.0
687 5 ▶ 'man' => sub { $help = $POD_FULL },
Subroutine __ANON__: called CC=1 SCAR=0.0
688 211 'version' => \$show_version,
689 );
690  
691 # Only one of these applies; the first match decides the exit status.
692 # Getopt::Long has already warned about any unknown option.
693 211 ▶ return $class->_usage($EXIT_USAGE, $POD_SYNOPSIS) unless $parsed;
Branch: 1 branch
BranchTrueFalseTotal
unless $parsed 18 193 211
694 193 ▶ return $class->_usage($EXIT_OK, $help) if $help;
Branch: 1 branch
BranchTrueFalseTotal
if $help 19 174 193
695 174 ▶ if($show_version) {
Branch: 1 branch
BranchTrueFalseTotal
if ($show_version) 1 173 174
696 1 print $class->i18n('version', { params => [$VERSION] }), "\n";
697 1 return $EXIT_OK;
698 }
699 # An empty or undefined name is as good as no name at all. length()
700 # of an empty string is 0, so one length test covers "", and "// ''"
701 # turns undef into "" first.
702 173 ▶ if(@{$argv} != 1 || !length($argv->[0] // '')) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$argv;} != 1 or not length($argv->[0] // "")) 23 150 173
Condition100%5/5
@{$argv;} != 1 or not length($argv->[0] // "")
l!l&&r!l&&!r
194150
$argv->[0] // ""
l!l
1522
MC/DC100%2/2
@{$argv;} != 1 or not length($argv->[0] // "")
@{$argv;} != 1 $argv->[0]
Truth table100%3/3
A or not(B)
A= @{$argv;} != 1B= $argv->[0]
ABresult
1X1
001
010
703 23 return $class->_usage($EXIT_USAGE, $POD_SYNOPSIS, $class->i18n('missing_database'));
704 }
705  
706 # Reading a database from a terminal would only wait for keystrokes
707 150 ▶ if($argv->[0] eq $STDIN_NAME && -t STDIN) {
Branch: 1 branch
BranchTrueFalseTotal
if ($argv->[0] eq $STDIN_NAME and -t STDIN) 3 147 150
Condition100%3/3
$argv->[0] eq $STDIN_NAME and -t STDIN
!ll&&!rl&&r
130173
MC/DC100%2/2
$argv->[0] eq $STDIN_NAME and -t STDIN
$argv->[0] eq $STDIN_NAME -t STDIN
Truth table100%3/3
A and B
A= $argv->[0] eq $STDIN_NAMEB= -t STDIN
ABresult
0X0
100
111
708 3 return $class->_usage($EXIT_USAGE, $POD_SYNOPSIS, $class->i18n('stdin_is_terminal'));
709 }
710 147 return;
711 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
712  
713 # _usage
714 # Purpose: Print documentation from this module's POD.
715 # Entry Criteria: $status is the exit status to return; $verbose is a
716 # Pod::Usage verbosity; $message is an optional error.
717 # Exit Status: Returns $status.
718 # Side Effects: Prints to STDOUT (help) or STDERR (errors).
719 60 ▶sub _usage :Private {
Subroutine _usage: called CC=3 SCAR=11.0
720 60 my ($class, $status, $verbose, $message) = @_;
721  
722 # The POD lives here, not in bin/access2csv, so point Pod::Usage at
723 # this file; NOEXIT keeps run() testable
724 60 ▶ pod2usage(
Branch: 2 branches
BranchTrueFalseTotal
$status == $EXIT_OK ? : 17 43 60
defined $message ? : 31 29 60
725 -input => __FILE__,
726 -verbose => $verbose,
727 -exitval => 'NOEXIT',
728 -output => $status == $EXIT_OK ? \*STDOUT : \*STDERR,
729 (defined($message) ? (-message => $message) : ()),
730 );
731 60 return $status;
732 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
733  
734 # _make_logger
735 # Purpose: Create the log, unless logging is switched off.
736 # Entry Criteria: $opt->{log} is a file name, or undef/'' for no log.
737 # Exit Status: Returns a Log::Abstraction object or undef; croaks if the
738 # file cannot be appended to.
739 # Side Effects: Creates the log file if it does not exist.
740 140 ▶sub _make_logger :Private {
Subroutine _make_logger: called CC=8 SCAR=20.8
741 140 my ($class, $opt) = @_;
742  
743 140 ▶ return unless length($opt->{log} // '');
Branch: 1 branch
BranchTrueFalseTotal
unless length($opt->{"log"} // "") 96 44 140
Condition100%2/2
$opt->{"log"} // ""
l!l
4991
MC/DC100%1/1
$opt->{"log"} // ""
$opt->{"log"}
Truth table100%2/2
A
A= $opt->{"log"}
Aresult
11
00
744  
745 44 my $file = $opt->{log};
746  
747 # Never write through a symbolic link: in a shared directory such as /tmp
748 # anyone could plant "access2csv.log" pointing at a file of yours
749 44 ▶ if(-l $file) {
Branch: 1 branch
BranchTrueFalseTotal
if (-l $file) 4 40 44
750 4 $class->_croak_i18n('log_open_failed', { params => [$file, $class->i18n('log_is_symlink')] });
751 }
752  
753 # The log file is the invoking user's own choice and is not a link, so
754 # it is untainted (for taint mode); a NUL byte cannot name a file at all
755 40 ▶ ($file) = $file =~ /\A([^\x00]+)\z/s or $class->_croak_i18n('log_open_failed', { params => [$opt->{log}, $class->i18n('invalid_name')] });
Branch: 1 branch
BranchTrueFalseTotal
($file) = $file =~ /\A([^\x00]+)\z/s or $class->_croak_i18n("log_open_failed", {"params", [$opt->{"log"}, $class->i18n("invalid_name")]}) 40 0 40
756  
757 # Open the log once, here, and give Log::Abstraction the handle, not the
758 # name. Given a name, it reopens the file for every message (following
759 # any link planted since the -l test above), rejects names containing
760 # "..", "$", "!", ";" and the like only when the first message is
761 # written, and ignores a file it cannot open - losing the log without
762 # telling anyone. O_NOFOLLOW (where the OS has it) closes the gap
763 # between the -l test and this open. The eval must not overwrite the
764 # caller's $@.
765 40 local $@;
766 40 my $fh;
767 40 ▶ eval {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { &App::Access2CSV::sysopen($fh, $file, 1089 | _no_follow()); 1 } } or $class->_croak_i18n("log_open_failed", {"params", [$file, _failure_reason($@)]}) 31 9 40
768 40 sysopen $fh, $file, O_WRONLY | O_APPEND | O_CREAT | _no_follow();
769 31 1;
770 } or $class->_croak_i18n('log_open_failed', { params => [$file, _failure_reason($@)] });
771  
772 # Write each line as it is logged, as reopening the file did, so a
773 # killed run still leaves its log behind
774 31 $fh->autoflush(1);
775  
776 # The handle is closed when the last reference to the logger goes
777 my $logger = Log::Abstraction->new(
778 logger => { fd => $fh },
779 31 ▶ level => $opt->{verbose} ? $LOG_LEVEL_VERBOSE : $LOG_LEVEL,
Branch: 1 branch
BranchTrueFalseTotal
$opt->{'verbose'} ? : 2 29 31
780 );
781  
782 # The user asked for a log; carrying on without one would silently
783 # break that promise
784 31 ▶ $logger or $class->_croak_i18n('log_open_failed', { params => [$file, $class->i18n('logger_unavailable')] });
Branch: 1 branch
BranchTrueFalseTotal
$logger or $class->_croak_i18n("log_open_failed", {"params", [$file, $class->i18n("logger_unavailable")]}) 27 4 31
785 27 return $logger;
786 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
787  
788 # _read_stdin
789 # Purpose: Copy the database piped in on standard input to a
790 # private temporary file, because mdbtools can only read
791 # a real, seekable file.
792 # Entry Criteria: STDIN is not a terminal (checked by _parse_options).
793 # Exit Status: Returns the File::Temp object; the file is deleted when
794 # the object is destroyed. Croaks if the input is a
795 # directory or empty, cannot be read, cannot be stored, or
796 # the copy is interrupted.
797 # Side Effects: Reads all of STDIN; writes a file (mode 0600) in the
798 # temporary directory (TMPDIR).
799 17 ▶sub _read_stdin :Private {
Subroutine _read_stdin: called CC=7 SCAR=19.5
800 17 my $class = shift;
801  
802 # Perl's default action for INT/TERM/... exits at once, which would
803 # leave the copy behind in the temporary directory. Raise an exception
804 # instead, so the File::Temp object is destroyed and deletes the file.
805 17 my $interrupted;
806 17 my @ours = @{ $class->_interrupt_signals() };
807 17 ▶ local @SIG{@ours} = (sub { $interrupted = $_[0]; die "\n" }) x @ours;
Subroutine __ANON__: called CC=1 SCAR=0.0
808  
809 # A directory as standard input ("access2csv - < dir"). On Linux reading
810 # it fails with EISDIR, but NetBSD (and FreeBSD before 13) return the
811 # directory's raw entries, which would be copied as if they were a
812 # database. Refuse it on every system, with the reason Linux gives.
813 # https://www.cpantesters.org/cpan/report/e9759fca-bda8-11f1-b0a1-a794297aa253
814 17 ▶ if(-d STDIN) {
Branch: 1 branch
BranchTrueFalseTotal
if (-d STDIN) 4 13 17
815 4 $class->_croak_i18n('stdin_read_failed', { params => [do { local $! = EISDIR; "$!" }] });
816 }
817  
818 13 my $copy = File::Temp->new(TEMPLATE => $STDIN_TEMPLATE, TMPDIR => 1, UNLINK => 1);
819 13 binmode $copy, ':raw';
820 13 binmode STDIN, ':raw';
821  
822 # Copy in chunks: a large database is never held in memory at once
823 13 my $total = 0;
824 13 local $@;
825 eval {
826 13 ▶ while(my $got = read(STDIN, my $buffer, $READ_CHUNK)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $got = &App::Access2CSV::read("STDIN", \my $buffer, $READ_CHUNK)) 38 10 48
827 38 print {$copy} $buffer;
828 38 $total += $got;
829 }
830 10 1;
831 13 ▶ } or do {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { while (my $got = &App::Access2CSV::read("STDIN", \my $buffer, $READ_CHUNK)) { do { print {$copy;} $buffer; $total += $got }; } ; 1 } } or do { $class->_croak_i18n("interrupted_reading", {"params", [$interrupted]}) if $interrupted; $class->_croak_i18n("stdin_read_failed", {"params", [_failure_reason($@)]}) } 10 3 13
832 3 ▶ $class->_croak_i18n('interrupted_reading', { params => [$interrupted] }) if $interrupted;
Branch: 1 branch
BranchTrueFalseTotal
if $interrupted 3 0 3
833 0 $class->_croak_i18n('stdin_read_failed', { params => [_failure_reason($@)] });
834 };
835  
836 10 ▶ $class->_croak_i18n('stdin_empty') unless $total;
Branch: 1 branch
BranchTrueFalseTotal
unless $total 5 5 10
837  
838 # Make sure every byte reached the file (e.g. the disk may be full)
839 5 ▶ $copy->flush() or $class->_croak_i18n('write_failed', { params => [$copy->filename(), "$!"] });
Branch: 1 branch
BranchTrueFalseTotal
$copy->flush or $class->_croak_i18n("write_failed", {"params", [$copy->filename, "$!"]}) 5 0 5
840 5 return $copy;
841 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
842  
843 # _strip_location
844 # Purpose: Remove the " at FILE line N." that Carp appends, which is
845 # noise for a command-line user.
846 # Entry Criteria: $text is an error message.
847 # Exit Status: Returns the message without the location or newline.
848 # Side Effects: None. A plain function, not a method.
849 #
850 # The file name may contain spaces ("My Documents"), so it cannot be
851 # matched as \S+. Instead: " at ", then the shortest run of characters
852 # that does not contain another " at ", then " line N." at the very end.
853 # The (?! at ) guard keeps this linear: each attempt stops at the next
854 # " at ", so no character is scanned by more than one attempt.
855 81 ▶sub _strip_location :Private {
Subroutine _strip_location: called CC=1 SCAR=0.0
856 81 my $text = shift;
857  
858 81 $text =~ s/
859 [ ] at [ ] # Carp's separator
860 (?: (?! [ ] at [ ] ) . )*? # the file name: anything but another " at "
861 [ ] line [ ] \d+ \.? # " line 42."
862 \n? \z # at the very end
863 //x;
864 81 chomp $text;
865 81 return $text;
866 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
867  
868 # _failure_reason
869 # Purpose: Explain why an eval failed. An autodie exception carries
870 # the operating system's reason; anything else (such as a
871 # taint-mode "Insecure dependency") is reported as it is,
872 # not replaced by a stale $! from some earlier call.
873 # Entry Criteria: $error is the eval's $@.
874 # Exit Status: Returns a one-line string.
875 # Side Effects: None. A plain function, not a method.
876 12 ▶sub _failure_reason :Private {
Subroutine _failure_reason: called CC=4 SCAR=14.1
877 12 my $error = shift;
878  
879 12 ▶ my $reason = (blessed($error) && $error->can('errno') && length($error->errno())) ? $error->errno() : "$error";
Branch: 1 branch
BranchTrueFalseTotal
builtin::blessed($error) && $error->can('errno') && length $error->errno ? : 10 2 12
Condition66%4/6
builtin::blessed($error) and $error->can("errno") and length $error->errno
!ll&&!rl&&r
2010
builtin::blessed($error) and $error->can("errno")
!ll&&!rl&&r
2010
MC/DC33%1/3
builtin::blessed($error) and $error->can("errno") and length $error->errno
builtin::blessed($error) $error->can("errno") length $error->errno
Truth table50%2/4
A and B and C
A= builtin::blessed($error)B= $error->can("errno")C= length $error->errno
ABCresult
0XX0
10X0
1100
1111
880 12 return _strip_location($reason);
881 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
882  
883 # _no_follow
884 # Purpose: The O_NOFOLLOW open flag, or 0 where the OS lacks it.
885 # Entry Criteria: None.
886 # Exit Status: Returns an integer flag.
887 # Side Effects: None.
888 40 ▶sub _no_follow :Private {
Subroutine _no_follow: called CC=2 SCAR=7.2
889 40 ▶ return eval { Fcntl::O_NOFOLLOW() } || 0;
Condition50%1/2
eval { do { 131072 } } || 0
l!l
400
MC/DC0%0/1
eval { do { 131072 } } || 0
eval { do { 131072 } }
Truth table50%1/2
A
A= eval { do { 131072 } }
Aresult
11
00
890 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
891  
892 # _report_fatal
893 # Purpose: Tell the user why the program stopped.
894 # Entry Criteria: $error is the exception from eval; $verbose is the
895 # --verbose flag.
896 # Exit Status: Returns the fatal exit status.
897 # Side Effects: Prints to STDERR.
898 70 ▶sub _report_fatal :Private {
Subroutine _report_fatal: called CC=4 SCAR=13.9
899 70 my ($class, $error, $verbose) = @_;
900  
901 # Carp appends " at FILE line N."; that is noise for a command-line
902 # user, but useful when debugging, so keep it with --verbose
903 70 ▶ my $text = length($error // '') ? "$error" : 'Unknown error';
Branch: 1 branch
BranchTrueFalseTotal
length($error // '') ? : 66 4 70
Condition100%2/2
$error // ""
l!l
664
MC/DC100%1/1
$error // ""
$error
Truth table100%2/2
A
A= $error
Aresult
11
00
904 70 ▶ $text = $verbose ? $text : _strip_location($text);
Branch: 1 branch
BranchTrueFalseTotal
$verbose ? : 7 63 70
905 70 chomp $text;
906  
907 # The reason may quote a hostile table name or file name: escape it
908 70 print STDERR $class->_printable($class->i18n('fatal', { params => [$text] })), "\n";
909 70 return $EXIT_FATAL;
910 33 ▶}
Subroutine BEGIN: called CC=1 SCAR=0.0
911  
912 33 1;
913  
914 __END__
« lib/App/Access2CSV/I18N.pm ↑ Summary lib/App/Access2CSV/Exporter.pm »