| 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, \@_) || {}
MC/DC100%1/1
get_params(undef, \@_) || {}
get_params(undef, \@_)
Truth table100%2/2
A
A= get_params(undef, \@_)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
builtin::blessed($self) and $self->isa(__PACKAGE__)
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__)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 744 | 224 | ▶ | return set_return($failed ? $EXIT_FAILURE : $EXIT_OK, { %RUN_STATUS_SCHEMA }); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 761 | 338 | ▶ | $self->_croak_i18n('database_unreadable', { params => [$database] }) unless -r _; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 785 | 47 | ▶ | if(my $path = $self->_find_program($MDB_COUNT)) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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($_)
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($_)
| |||||||||||||||||||||||||||||||||||||||||||
| 809 | |||||||||||||||||||||||||||||||||||||||||||
| 810 | # An absolute path to an existing program: safe to untaint | ||||||||||||||||||||||||||||||||||||||||||
| 811 | 732 | ▶ | $path = _untaint($path) if defined $path; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 812 | 732 | ▶ | if($path && $self->{verbose}) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$path and $self->{"verbose"}
MC/DC100%2/2
$path and $self->{"verbose"}
$path
$self->{"verbose"}
Truth table100%3/3
A and B
A= $pathB= $self->{"verbose"}
| |||||||||||||||||||||||||||||||||||||||||||
| 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($_)
$stdout // ""
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($_)
Truth table100%2/2
A
A= $stdout
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
@{$errors;} or not -d $dir
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 908 | 18 | ▶ | $self->_croak_i18n('mkdir_failed', { params => [$dir, $detail || "$!"] }); | ||||||||||||||||||||||||||||||||||||||||
|
Condition66%2/3
$detail || "$!"
MC/DC0%0/2
$detail || "$!"
$detail
"$!"
Truth table66%2/3
A || B
A= $detailB= "$!"
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 943 | |||||||||||||||||||||||||||||||||||||||||||
| 944 | 74 | ▶ | my $error = $@ || 'Unknown error'; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$@ || 'Unknown error'
MC/DC100%1/1
$@ || 'Unknown error'
$@
Truth table100%2/2
A
A= $@
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%6/6
not $self->{"overwrite"} and -e $outfile || -l $outfile
-e $outfile or -l $outfile
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 983 | 1320 | ▶ | $tmp->flush() or $self->_croak_i18n('write_failed', { params => [$outfile, "$!"] }); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 993 | 1316 | ▶ | if(defined $rows) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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 // ""
MC/DC100%1/1
$stdout // ""
$stdout
Truth table100%2/2
A
A= $stdout
| |||||||||||||||||||||||||||||||||||||||||||
| 1081 | 50 | ▶ | defined($rows) or $self->_croak_i18n('count_unreadable', { params => [$self->_printable(substr($stdout // '', 0, $COUNT_SHOWN))] }); | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%2/2
$stdout // ""
MC/DC100%1/1
$stdout // ""
$stdout
Truth table100%2/2
A
A= $stdout
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1100 | |||||||||||||||||||||||||||||||||||||||||||
| 1101 | 15 | ▶ | die $@ if $self->{interrupted}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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($_)
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($_)
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1143 | 6 | $self->_croak_i18n('program_not_run', { params => [$name, $reason] }); | |||||||||||||||||||||||||||||||||||||||||
| 1144 | } | ||||||||||||||||||||||||||||||||||||||||||
| 1145 | 1710 | ▶ | if($status & 127) { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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] // ""
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]
| |||||||||||||||||||||||||||||||||||||||||||
| 1150 | 14 | ▶ | if($signal eq 'INT' || $signal eq 'QUIT') { | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$signal eq "INT" or $signal eq "QUIT"
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"
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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 // ""
MC/DC100%1/1
$table // ""
$table
Truth table100%2/2
A
A= $table
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1210 | 17112 | ▶ | $name = $UNNAMED unless length $name; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 1221 | 11698 | ▶ | my $n = $self->{next_suffix}{$base} // 2; | ||||||||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self->{"next_suffix"}{$base} // 2
MC/DC100%1/1
$self->{"next_suffix"}{$base} // 2
$self->{"next_suffix"}{$base}
Truth table100%2/2
A
A= $self->{"next_suffix"}{$base}
| |||||||||||||||||||||||||||||||||||||||||||
| 1222 | 11698 | ▶ | $n++ while exists $used->{lc "${name}_$n$CSV_SUFFIX"}; | ||||||||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
length $text <= $MAX_NAME_CHARS and length $bytes <= $MAX_NAME_BYTES
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
$count + length($grapheme) > $MAX_NAME_CHARS or $size + length($encoded) > $MAX_NAME_BYTES
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition66%2/3
$self->_try_count_rows($database, $table) // $UNKNOWN_COUNT
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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition50%1/2
$value // ""
MC/DC0%0/1
$value // ""
$value
Truth table50%1/2
A
A= $value
| |||||||||||||||||||||||||||||||||||||||||||
| 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
Condition100%3/3
builtin::blessed($error) and $error->can("errno")
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")
| |||||||||||||||||||||||||||||||||||||||||||
| 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__ | ||||||||||||||||||||||||||||||||||||||||||