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