| 1 | # ex:ts=8 sw=4: | ||||||||||||||||||||||||||||
| 2 | # $OpenBSD$ | ||||||||||||||||||||||||||||
| 3 | # | ||||||||||||||||||||||||||||
| 4 | # Copyright (c) 2026 Dick Olsson <hi@senzilla.io> | ||||||||||||||||||||||||||||
| 5 | # | ||||||||||||||||||||||||||||
| 6 | # Permission to use, copy, modify, and distribute this software for any | ||||||||||||||||||||||||||||
| 7 | # purpose with or without fee is hereby granted, provided that the above | ||||||||||||||||||||||||||||
| 8 | # copyright notice and this permission notice appear in all copies. | ||||||||||||||||||||||||||||
| 9 | # | ||||||||||||||||||||||||||||
| 10 | # THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | ||||||||||||||||||||||||||||
| 11 | # WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | ||||||||||||||||||||||||||||
| 12 | # MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | ||||||||||||||||||||||||||||
| 13 | # ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | ||||||||||||||||||||||||||||
| 14 | # WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | ||||||||||||||||||||||||||||
| 15 | # ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | ||||||||||||||||||||||||||||
| 16 | # OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | ||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||
| 18 | package App::FuguBench; | ||||||||||||||||||||||||||||
| 19 | 117 | our $VERSION = '0.1.1'; | |||||||||||||||||||||||||||
| 20 | |||||||||||||||||||||||||||||
| 21 | 117 | ▶ | use v5.34; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 22 | 117 | ▶ | use warnings; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 23 | 117 | ▶ | use experimental 'signatures'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 24 | 117 | ▶ | no feature qw(indirect multidimensional bareword_filehandles); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 25 | |||||||||||||||||||||||||||||
| 26 | 117 | ▶ | use Cwd (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 27 | 117 | ▶ | use File::Temp (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 28 | 117 | ▶ | use Getopt::Long (); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 29 | |||||||||||||||||||||||||||||
| 30 | 117 | ▶ | use Fugu::CLI; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 31 | 117 | ▶ | use Fugu::File; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 32 | 117 | ▶ | use Fugu::Process; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 33 | 117 | ▶ | use Fugu::Sandbox; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 34 | |||||||||||||||||||||||||||||
| 35 | 117 | ▶ | use App::FuguBench::Checkout; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 36 | 117 | ▶ | use App::FuguBench::Deps; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 37 | 117 | ▶ | use App::FuguBench::Dist; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 38 | 117 | ▶ | use App::FuguBench::Doctor; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 39 | 117 | ▶ | use App::FuguBench::Fetch; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 40 | 117 | ▶ | use App::FuguBench::Hook; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 41 | 117 | ▶ | use App::FuguBench::Traces; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 42 | 117 | ▶ | use App::FuguBench::Update; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 43 | 117 | ▶ | use App::FuguBench::Version; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 44 | 117 | ▶ | use App::FuguBench::Wiki; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 45 | 117 | ▶ | use App::FuguBench::Worktree; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 46 | |||||||||||||||||||||||||||||
| 47 | # App::FuguBench - the dispatcher of the fugubench program. | ||||||||||||||||||||||||||||
| 48 | # | ||||||||||||||||||||||||||||
| 49 | # Every verb shares one dispatcher, one checkout discovery, one | ||||||||||||||||||||||||||||
| 50 | # sandbox entry, and one channel discipline. Fugu::CLI parses the | ||||||||||||||||||||||||||||
| 51 | # global options, finds the verb, parses the options of the verb, and | ||||||||||||||||||||||||||||
| 52 | # calls it. Its exit codes are the codes of the program. | ||||||||||||||||||||||||||||
| 53 | # | ||||||||||||||||||||||||||||
| 54 | # Standard output carries the result line of a verb, and nothing | ||||||||||||||||||||||||||||
| 55 | # else. Every diagnostic goes to the logger, which writes to standard | ||||||||||||||||||||||||||||
| 56 | # error, because a hook reads standard output. | ||||||||||||||||||||||||||||
| 57 | # | ||||||||||||||||||||||||||||
| 58 | # The namespace is an application, not a library. It uses Fugu:: and | ||||||||||||||||||||||||||||
| 59 | # core Perl, and it never uses another App:: namespace. | ||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | # The verb table. Each entry names a verb and the module that holds | ||||||||||||||||||||||||||||
| 62 | # it. The module returns the entry of the Fugu::CLI table from its | ||||||||||||||||||||||||||||
| 63 | # command class method. | ||||||||||||||||||||||||||||
| 64 | 117 | my @VERBS = ( | |||||||||||||||||||||||||||
| 65 | [ 'doctor', 'App::FuguBench::Doctor' ], | ||||||||||||||||||||||||||||
| 66 | [ 'hook', 'App::FuguBench::Hook' ], | ||||||||||||||||||||||||||||
| 67 | [ 'traces', 'App::FuguBench::Traces' ], | ||||||||||||||||||||||||||||
| 68 | [ 'version', 'App::FuguBench::Version' ], | ||||||||||||||||||||||||||||
| 69 | [ 'wiki', 'App::FuguBench::Wiki' ], | ||||||||||||||||||||||||||||
| 70 | [ 'worktree', 'App::FuguBench::Worktree' ], | ||||||||||||||||||||||||||||
| 71 | [ 'deps', 'App::FuguBench::Deps' ], | ||||||||||||||||||||||||||||
| 72 | [ 'fetch', 'App::FuguBench::Fetch' ], | ||||||||||||||||||||||||||||
| 73 | [ 'shim', 'App::FuguBench::Dist' ], | ||||||||||||||||||||||||||||
| 74 | [ 'install', 'App::FuguBench::Dist' ], | ||||||||||||||||||||||||||||
| 75 | [ 'update', 'App::FuguBench::Update' ], | ||||||||||||||||||||||||||||
| 76 | ); | ||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||
| 78 | # The sandbox row of each verb (CLI-SANDBOX). A row names the pledge | ||||||||||||||||||||||||||||
| 79 | # promises of the verb, and the unveil paths of a verb that opens a | ||||||||||||||||||||||||||||
| 80 | # file of its own. A row that names subcommands gives one promise set | ||||||||||||||||||||||||||||
| 81 | # to each named subcommand, and the promises of the row to every | ||||||||||||||||||||||||||||
| 82 | # other one. | ||||||||||||||||||||||||||||
| 83 | # | ||||||||||||||||||||||||||||
| 84 | # `version` opens no file, so its row holds `stdio` alone, and | ||||||||||||||||||||||||||||
| 85 | # `stdio` denies open(2). | ||||||||||||||||||||||||||||
| 86 | # | ||||||||||||||||||||||||||||
| 87 | # `wiki` and `worktree` run git, and no row can name each file that | ||||||||||||||||||||||||||||
| 88 | # git opens. So each row unveils nothing (CLI-SANDBOX-2). git pushes, | ||||||||||||||||||||||||||||
| 89 | # so the row of `wiki` adds the network promises. The `list` | ||||||||||||||||||||||||||||
| 90 | # subcommand of `worktree` writes no file, so it drops the write | ||||||||||||||||||||||||||||
| 91 | # promises. | ||||||||||||||||||||||||||||
| 92 | # | ||||||||||||||||||||||||||||
| 93 | # `traces` opens its files itself and runs no child, so its row | ||||||||||||||||||||||||||||
| 94 | # unveils. The list comes from the verb, because a path of it comes | ||||||||||||||||||||||||||||
| 95 | # from an option and a path of it comes from the checkout. | ||||||||||||||||||||||||||||
| 96 | # | ||||||||||||||||||||||||||||
| 97 | # `shim` and `install` open a file of their own and run no child, so | ||||||||||||||||||||||||||||
| 98 | # each row unveils as well. They are the two other verbs that unveil | ||||||||||||||||||||||||||||
| 99 | # (CLI-SANDBOX-2). `shim` reads the running file, and `install` | ||||||||||||||||||||||||||||
| 100 | # reads it and writes the copy, so each list comes from the verb | ||||||||||||||||||||||||||||
| 101 | # too. | ||||||||||||||||||||||||||||
| 102 | # | ||||||||||||||||||||||||||||
| 103 | # `hook` runs the other verbs in its own process, so its row pledges | ||||||||||||||||||||||||||||
| 104 | # the promises of `wiki` and of `worktree` together. Those verbs run | ||||||||||||||||||||||||||||
| 105 | # git, so the row unveils nothing. The `install` subcommand writes one | ||||||||||||||||||||||||||||
| 106 | # file of its own, and the write promises of the row cover that write. | ||||||||||||||||||||||||||||
| 107 | # The row names no unveil list, so no walk runs in front of the verb. | ||||||||||||||||||||||||||||
| 108 | # | ||||||||||||||||||||||||||||
| 109 | # `doctor` runs git for the library check and for the fix, so its row | ||||||||||||||||||||||||||||
| 110 | # unveils nothing too. It reads the settings file itself, and rpath | ||||||||||||||||||||||||||||
| 111 | # covers that read. It writes no file of its own: git writes every | ||||||||||||||||||||||||||||
| 112 | # byte of the fix. | ||||||||||||||||||||||||||||
| 113 | # | ||||||||||||||||||||||||||||
| 114 | # The install of `deps` runs a package manager, cpanm, and the | ||||||||||||||||||||||||||||
| 115 | # commands of an archive, and each one writes outside every path of a | ||||||||||||||||||||||||||||
| 116 | # row. So the row unveils nothing either. The file promises cover the | ||||||||||||||||||||||||||||
| 117 | # manifest read and the digest file, `proc exec` covers each child, | ||||||||||||||||||||||||||||
| 118 | # and `inet dns` covers each download. | ||||||||||||||||||||||||||||
| 119 | # | ||||||||||||||||||||||||||||
| 120 | # `fetch` runs the downloader of Fugu::Curl as a child, which writes | ||||||||||||||||||||||||||||
| 121 | # its file beside the destination and renames it. So the row holds | ||||||||||||||||||||||||||||
| 122 | # the promises of `deps`, and it unveils nothing. | ||||||||||||||||||||||||||||
| 123 | # | ||||||||||||||||||||||||||||
| 124 | # `update` runs that downloader as well, so its row unveils nothing | ||||||||||||||||||||||||||||
| 125 | # too. It replaces the running file where that file sits, so no path | ||||||||||||||||||||||||||||
| 126 | # list bounds the write. The file promises serve the replace, `fattr` | ||||||||||||||||||||||||||||
| 127 | # serves the mode of the new program, and `inet dns` serves each | ||||||||||||||||||||||||||||
| 128 | # download. | ||||||||||||||||||||||||||||
| 129 | my %SANDBOX = ( | ||||||||||||||||||||||||||||
| 130 | doctor => { promises => 'stdio rpath proc exec' }, | ||||||||||||||||||||||||||||
| 131 | hook => { | ||||||||||||||||||||||||||||
| 132 | promises => 'stdio rpath wpath cpath fattr proc exec inet dns' | ||||||||||||||||||||||||||||
| 133 | }, | ||||||||||||||||||||||||||||
| 134 | traces => { | ||||||||||||||||||||||||||||
| 135 | promises => 'stdio rpath', | ||||||||||||||||||||||||||||
| 136 | 10 | ▶ | unveil => sub ($app) { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 137 | 10 | return App::FuguBench::Traces->unveil_paths($app); | |||||||||||||||||||||||||||
| 138 | }, | ||||||||||||||||||||||||||||
| 139 | }, | ||||||||||||||||||||||||||||
| 140 | version => { promises => 'stdio' }, | ||||||||||||||||||||||||||||
| 141 | wiki => { | ||||||||||||||||||||||||||||
| 142 | promises => 'stdio rpath wpath cpath fattr proc exec inet dns' | ||||||||||||||||||||||||||||
| 143 | }, | ||||||||||||||||||||||||||||
| 144 | worktree => { | ||||||||||||||||||||||||||||
| 145 | promises => 'stdio rpath wpath cpath fattr proc exec', | ||||||||||||||||||||||||||||
| 146 | subcommands => { list => 'stdio rpath proc exec' }, | ||||||||||||||||||||||||||||
| 147 | }, | ||||||||||||||||||||||||||||
| 148 | deps => { promises => 'stdio rpath wpath cpath proc exec inet dns' }, | ||||||||||||||||||||||||||||
| 149 | fetch => { promises => 'stdio rpath wpath cpath proc exec inet dns' }, | ||||||||||||||||||||||||||||
| 150 | shim => { | ||||||||||||||||||||||||||||
| 151 | promises => 'stdio rpath', | ||||||||||||||||||||||||||||
| 152 | 0 | ▶ | unveil => sub ($app) { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||
| 153 | 0 | return App::FuguBench::Dist->shim_paths($app); | |||||||||||||||||||||||||||
| 154 | }, | ||||||||||||||||||||||||||||
| 155 | }, | ||||||||||||||||||||||||||||
| 156 | install => { | ||||||||||||||||||||||||||||
| 157 | promises => 'stdio rpath wpath cpath fattr', | ||||||||||||||||||||||||||||
| 158 | 0 | ▶ | unveil => sub ($app) { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: not called CC=1 SCAR=6.9
| |||||||||||||||||||||||||||||
| 159 | 0 | return App::FuguBench::Dist->install_paths($app); | |||||||||||||||||||||||||||
| 160 | }, | ||||||||||||||||||||||||||||
| 161 | }, | ||||||||||||||||||||||||||||
| 162 | 117 | update => { | |||||||||||||||||||||||||||
| 163 | promises => 'stdio rpath wpath cpath fattr proc exec inet dns' | ||||||||||||||||||||||||||||
| 164 | }, | ||||||||||||||||||||||||||||
| 165 | ); | ||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||
| 167 | # The global options, in the form of Fugu::CLI. new gives the table | ||||||||||||||||||||||||||||
| 168 | # to the dispatcher, and run reads the same table to find the verb. | ||||||||||||||||||||||||||||
| 169 | 117 | my %OPTIONS = ( | |||||||||||||||||||||||||||
| 170 | 'C=s' => 'the directory that a verb reads as its checkout root', | ||||||||||||||||||||||||||||
| 171 | 'verbose' => 'trace each command on standard error', | ||||||||||||||||||||||||||||
| 172 | ); | ||||||||||||||||||||||||||||
| 173 | |||||||||||||||||||||||||||||
| 174 | # App::FuguBench->new: | ||||||||||||||||||||||||||||
| 175 | # Build the dispatcher over Fugu::CLI. The global options are | ||||||||||||||||||||||||||||
| 176 | # -C <dir> and --verbose. | ||||||||||||||||||||||||||||
| 177 | 117 | ▶ | sub new ($class) | ||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 178 | { | ||||||||||||||||||||||||||||
| 179 | 117 | my $self = bless { | |||||||||||||||||||||||||||
| 180 | cli => undef, | ||||||||||||||||||||||||||||
| 181 | checkout => undef, | ||||||||||||||||||||||||||||
| 182 | walked => 0, | ||||||||||||||||||||||||||||
| 183 | missing => undef, | ||||||||||||||||||||||||||||
| 184 | quiet => 0, | ||||||||||||||||||||||||||||
| 185 | child => undef, | ||||||||||||||||||||||||||||
| 186 | error => undef, | ||||||||||||||||||||||||||||
| 187 | }, $class; | ||||||||||||||||||||||||||||
| 188 | |||||||||||||||||||||||||||||
| 189 | 117 | $self->{cli} = Fugu::CLI->new( | |||||||||||||||||||||||||||
| 190 | name => 'fugubench', | ||||||||||||||||||||||||||||
| 191 | usage => '[-C <dir>] [--verbose] <verb> [options] [arguments]', | ||||||||||||||||||||||||||||
| 192 | options => \%OPTIONS, | ||||||||||||||||||||||||||||
| 193 | commands => $self->_commands, | ||||||||||||||||||||||||||||
| 194 | ); | ||||||||||||||||||||||||||||
| 195 | |||||||||||||||||||||||||||||
| 196 | 117 | return $self; | |||||||||||||||||||||||||||
| 197 | } | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | # $self->_commands: | ||||||||||||||||||||||||||||
| 200 | # The Fugu::CLI command table. Each entry comes from the verb | ||||||||||||||||||||||||||||
| 201 | # module, and the wrapper enters the sandbox row of the verb | ||||||||||||||||||||||||||||
| 202 | # before the body runs. | ||||||||||||||||||||||||||||
| 203 | 117 | ▶ | sub _commands ($self) | ||||||||||||||||||||||||||
|
Subroutine
_commands: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||
| 204 | { | ||||||||||||||||||||||||||||
| 205 | 117 | my %table; | |||||||||||||||||||||||||||
| 206 | 117 | for my $verb (@VERBS) { | |||||||||||||||||||||||||||
| 207 | 1287 | my ( $name, $module ) = @$verb; | |||||||||||||||||||||||||||
| 208 | 1287 | ▶ | die "$name has no sandbox row" unless $SANDBOX{$name}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | 1287 | my $entry = $module->command($name); | |||||||||||||||||||||||||||
| 211 | 1287 | my $body = $entry->{run}; | |||||||||||||||||||||||||||
| 212 | 105 | ▶ | $entry->{run} = sub ( $, @argv ) { | ||||||||||||||||||||||||||
|
Subroutine
__ANON__: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 213 | 105 | $self->_sandbox( $name, $argv[0] ); | |||||||||||||||||||||||||||
| 214 | 105 | return $body->( $self, @argv ); | |||||||||||||||||||||||||||
| 215 | 1287 | }; | |||||||||||||||||||||||||||
| 216 | 1287 | $table{$name} = $entry; | |||||||||||||||||||||||||||
| 217 | } | ||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||
| 219 | 117 | return \%table; | |||||||||||||||||||||||||||
| 220 | } | ||||||||||||||||||||||||||||
| 221 | |||||||||||||||||||||||||||||
| 222 | # $self->_sandbox($verb, $subcommand): | ||||||||||||||||||||||||||||
| 223 | # Enter the sandbox row of one verb. The method unveils the | ||||||||||||||||||||||||||||
| 224 | # paths of the row, and it pledges the promises of the row, or | ||||||||||||||||||||||||||||
| 225 | # the promises that the row gives to the subcommand. On a | ||||||||||||||||||||||||||||
| 226 | # platform other than OpenBSD the calls change nothing. | ||||||||||||||||||||||||||||
| 227 | # | ||||||||||||||||||||||||||||
| 228 | # The unveil comes in front of the pledge. unveil(2) needs the | ||||||||||||||||||||||||||||
| 229 | # `unveil` promise, no row of the table holds that promise, and | ||||||||||||||||||||||||||||
| 230 | # a pledge in front of the call would stop the program. A row | ||||||||||||||||||||||||||||
| 231 | # with no list unveils nothing, and the whole filesystem stays | ||||||||||||||||||||||||||||
| 232 | # in view. | ||||||||||||||||||||||||||||
| 233 | # | ||||||||||||||||||||||||||||
| 234 | # The row resolves here, after the option parse and before the | ||||||||||||||||||||||||||||
| 235 | # verb, so a path of a row can come from an option. | ||||||||||||||||||||||||||||
| 236 | # | ||||||||||||||||||||||||||||
| 237 | # The unveil list of a row can name the checkout root, so the | ||||||||||||||||||||||||||||
| 238 | # row walks to that root here. The walk reports nothing, and | ||||||||||||||||||||||||||||
| 239 | # the verb reports a failed walk on its own call. A verb that | ||||||||||||||||||||||||||||
| 240 | # rejects its argument list then reports the usage, and no | ||||||||||||||||||||||||||||
| 241 | # configuration error (CLI-CHECKOUT-3). | ||||||||||||||||||||||||||||
| 242 | 105 | ▶ | sub _sandbox ( $self, $verb, $subcommand = undef ) | ||||||||||||||||||||||||||
|
Subroutine
_sandbox: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||
| 243 | 105 | { | |||||||||||||||||||||||||||
| 244 | 105 | my $row = $SANDBOX{$verb}; | |||||||||||||||||||||||||||
| 245 | 105 | ▶ | my $named = $row->{subcommands} // {}; | ||||||||||||||||||||||||||
|
Condition100%2/2
$row->{"subcommands"} // {}
MC/DC100%1/1
$row->{"subcommands"} // {}
$row->{"subcommands"}
Truth table100%2/2
A
A= $row->{"subcommands"}
| |||||||||||||||||||||||||||||
| 246 | 105 | my $promises = $row->{promises}; | |||||||||||||||||||||||||||
| 247 | $promises = $named->{$subcommand} | ||||||||||||||||||||||||||||
| 248 | 105 | ▶ | if defined $subcommand && defined $named->{$subcommand}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $subcommand and defined $named->{$subcommand}
MC/DC100%2/2
defined $subcommand and defined $named->{$subcommand}
defined $subcommand
defined $named->{$subcommand}
Truth table100%3/3
A and B
A= defined $subcommandB= defined $named->{$subcommand}
| |||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||
| 250 | 105 | ▶ | if ( $row->{unveil} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 251 | 10 | $self->{quiet} = 1; | |||||||||||||||||||||||||||
| 252 | 10 | Fugu::Sandbox->unveil( paths => [ $row->{unveil}->($self) ] ); | |||||||||||||||||||||||||||
| 253 | 10 | $self->{quiet} = 0; | |||||||||||||||||||||||||||
| 254 | } | ||||||||||||||||||||||||||||
| 255 | |||||||||||||||||||||||||||||
| 256 | 105 | Fugu::Sandbox->pledge( promises => $promises ); | |||||||||||||||||||||||||||
| 257 | |||||||||||||||||||||||||||||
| 258 | 105 | return $self; | |||||||||||||||||||||||||||
| 259 | } | ||||||||||||||||||||||||||||
| 260 | |||||||||||||||||||||||||||||
| 261 | # $self->run(@argv): | ||||||||||||||||||||||||||||
| 262 | # Parse, enter the sandbox, dispatch, and return the exit code. | ||||||||||||||||||||||||||||
| 263 | # | ||||||||||||||||||||||||||||
| 264 | # A command line with no verb is a usage error, and a global | ||||||||||||||||||||||||||||
| 265 | # option in front of it changes nothing. Fugu::CLI prints the | ||||||||||||||||||||||||||||
| 266 | # help for such a line and returns success, and CLI-PROGRAM-3 | ||||||||||||||||||||||||||||
| 267 | # wants the usage on standard error with exit 2. So the method | ||||||||||||||||||||||||||||
| 268 | # looks for the verb first, on a copy of the arguments and with | ||||||||||||||||||||||||||||
| 269 | # the parse rules of Fugu::CLI. | ||||||||||||||||||||||||||||
| 270 | # | ||||||||||||||||||||||||||||
| 271 | # The copy declares the global options alone. It passes an | ||||||||||||||||||||||||||||
| 272 | # unknown option, a missing option value, and a request for the | ||||||||||||||||||||||||||||
| 273 | # help through, so each one stays in the array and the guard | ||||||||||||||||||||||||||||
| 274 | # passes. Fugu::CLI meets them again, and it answers or reports | ||||||||||||||||||||||||||||
| 275 | # each one once. | ||||||||||||||||||||||||||||
| 276 | 116 | ▶ | sub run ( $self, @argv ) | ||||||||||||||||||||||||||
|
Subroutine
run: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||
| 277 | { | ||||||||||||||||||||||||||||
| 278 | 116 | my @rest = @argv; | |||||||||||||||||||||||||||
| 279 | 116 | my $parser = Getopt::Long::Parser->new; | |||||||||||||||||||||||||||
| 280 | 116 | $parser->configure( | |||||||||||||||||||||||||||
| 281 | qw(require_order bundling no_ignore_case pass_through)); | ||||||||||||||||||||||||||||
| 282 | |||||||||||||||||||||||||||||
| 283 | 116 | my %values; | |||||||||||||||||||||||||||
| 284 | 116 | $parser->getoptionsfromarray( \@rest, \%values, keys %OPTIONS ); | |||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||
| 286 | # The parse passes `--` through. It ends the options, and it | ||||||||||||||||||||||||||||
| 287 | # is no verb and no request for the help. | ||||||||||||||||||||||||||||
| 288 | 116 | ▶ | shift @rest if @rest && $rest[0] eq q{--}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
@rest and $rest[0] eq "--"
MC/DC100%2/2
@rest and $rest[0] eq "--"
@rest
$rest[0] eq "--"
Truth table100%3/3
A and B
A= @restB= $rest[0] eq "--"
| |||||||||||||||||||||||||||||
| 289 | |||||||||||||||||||||||||||||
| 290 | 116 | ▶ | return $self->{cli}->usage_error unless @rest; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 291 | |||||||||||||||||||||||||||||
| 292 | 112 | return $self->{cli}->run(@argv); | |||||||||||||||||||||||||||
| 293 | } | ||||||||||||||||||||||||||||
| 294 | |||||||||||||||||||||||||||||
| 295 | # $self->cli: | ||||||||||||||||||||||||||||
| 296 | # The Fugu::CLI dispatcher. A verb body reads its options | ||||||||||||||||||||||||||||
| 297 | # through $app->cli->option and reports through | ||||||||||||||||||||||||||||
| 298 | # $app->cli->log. | ||||||||||||||||||||||||||||
| 299 | 229 | ▶ | sub cli ($self) | ||||||||||||||||||||||||||
|
Subroutine
cli: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 300 | { | ||||||||||||||||||||||||||||
| 301 | 229 | return $self->{cli}; | |||||||||||||||||||||||||||
| 302 | } | ||||||||||||||||||||||||||||
| 303 | |||||||||||||||||||||||||||||
| 304 | # $self->error: | ||||||||||||||||||||||||||||
| 305 | # The reason of the last failure of command(), or undef. | ||||||||||||||||||||||||||||
| 306 | 6 | ▶ | sub error ($self) | ||||||||||||||||||||||||||
|
Subroutine
error: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 307 | { | ||||||||||||||||||||||||||||
| 308 | 6 | return $self->{error}; | |||||||||||||||||||||||||||
| 309 | } | ||||||||||||||||||||||||||||
| 310 | |||||||||||||||||||||||||||||
| 311 | # $self->child: | ||||||||||||||||||||||||||||
| 312 | # The pid of the running child of the group form of command(), | ||||||||||||||||||||||||||||
| 313 | # or undef. A signal handler reads it to stop the group before | ||||||||||||||||||||||||||||
| 314 | # it starts its cleanup. | ||||||||||||||||||||||||||||
| 315 | 2 | ▶ | sub child ($self) | ||||||||||||||||||||||||||
|
Subroutine
child: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||
| 316 | { | ||||||||||||||||||||||||||||
| 317 | 2 | return $self->{child}; | |||||||||||||||||||||||||||
| 318 | } | ||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||
| 320 | # $self->start: | ||||||||||||||||||||||||||||
| 321 | # The start directory of the run: the -C value, or the current | ||||||||||||||||||||||||||||
| 322 | # directory. A verb that reads a path relative to the start, and | ||||||||||||||||||||||||||||
| 323 | # that walks up to no checkout, reads it here (CLI-CHECKOUT-5). | ||||||||||||||||||||||||||||
| 324 | # `deps` is that verb, and a guest runs it out of an extracted | ||||||||||||||||||||||||||||
| 325 | # tarball that holds no .toolingrc. | ||||||||||||||||||||||||||||
| 326 | 100 | ▶ | sub start ($self) | ||||||||||||||||||||||||||
|
Subroutine
start: called CC=2 SCAR=9.2
Pod
documented
| |||||||||||||||||||||||||||||
| 327 | { | ||||||||||||||||||||||||||||
| 328 | 100 | ▶ | return $self->{cli}->option('C') // Cwd::getcwd(); | ||||||||||||||||||||||||||
|
Condition33%1/3
$self->{"cli"}->option("C") // Cwd::getcwd()
MC/DC0%0/2
$self->{"cli"}->option("C") // Cwd::getcwd()
$self->{"cli"}->option("C")
Cwd::getcwd()
Truth table33%1/3
A // B
A= $self->{"cli"}->option("C")B= Cwd::getcwd()
| |||||||||||||||||||||||||||||
| 329 | } | ||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||
| 331 | # $self->checkout($checkout): | ||||||||||||||||||||||||||||
| 332 | # The checkout of the run. Without an argument the walk runs on | ||||||||||||||||||||||||||||
| 333 | # the first call, from the start directory of start(). A verb | ||||||||||||||||||||||||||||
| 334 | # that reads no checkout never starts it, so the program runs in | ||||||||||||||||||||||||||||
| 335 | # a home with no .toolingrc. | ||||||||||||||||||||||||||||
| 336 | # | ||||||||||||||||||||||||||||
| 337 | # The method returns undef when no .toolingrc sits above the | ||||||||||||||||||||||||||||
| 338 | # start. The call of the verb names the start directory in the | ||||||||||||||||||||||||||||
| 339 | # log, and the verb then returns EXIT_CONFIG_ERROR. | ||||||||||||||||||||||||||||
| 340 | # | ||||||||||||||||||||||||||||
| 341 | # The walk runs one time, and a failed walk stays failed. A | ||||||||||||||||||||||||||||
| 342 | # sandbox row reads the checkout before the verb does, and that | ||||||||||||||||||||||||||||
| 343 | # row reports nothing. So the report waits for the call of the | ||||||||||||||||||||||||||||
| 344 | # verb, and it comes one time. | ||||||||||||||||||||||||||||
| 345 | # | ||||||||||||||||||||||||||||
| 346 | # With an argument the method sets the checkout, for a verb that | ||||||||||||||||||||||||||||
| 347 | # reads its start from a payload. The argument drops the report | ||||||||||||||||||||||||||||
| 348 | # of a failed walk, so no later call writes it. | ||||||||||||||||||||||||||||
| 349 | 176 | ▶ | sub checkout ( $self, $checkout = undef ) | ||||||||||||||||||||||||||
|
Subroutine
checkout: called CC=7 SCAR=20.0
Pod
documented
| |||||||||||||||||||||||||||||
| 350 | 176 | { | |||||||||||||||||||||||||||
| 351 | 176 | ▶ | if ( defined $checkout ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 352 | 0 | $self->{checkout} = $checkout; | |||||||||||||||||||||||||||
| 353 | 0 | $self->{walked} = 1; | |||||||||||||||||||||||||||
| 354 | 0 | delete $self->{missing}; | |||||||||||||||||||||||||||
| 355 | 0 | return $checkout; | |||||||||||||||||||||||||||
| 356 | } | ||||||||||||||||||||||||||||
| 357 | |||||||||||||||||||||||||||||
| 358 | 176 | ▶ | unless ( $self->{walked} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 359 | 100 | $self->{walked} = 1; | |||||||||||||||||||||||||||
| 360 | |||||||||||||||||||||||||||||
| 361 | 100 | my $start = $self->start; | |||||||||||||||||||||||||||
| 362 | $self->{checkout} = | ||||||||||||||||||||||||||||
| 363 | 100 | App::FuguBench::Checkout->new( start => $start ); | |||||||||||||||||||||||||||
| 364 | $self->{missing} = $start | ||||||||||||||||||||||||||||
| 365 | 100 | ▶ | unless defined $self->{checkout}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 366 | } | ||||||||||||||||||||||||||||
| 367 | |||||||||||||||||||||||||||||
| 368 | 176 | ▶ | if ( defined $self->{missing} && !$self->{quiet} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $self->{"missing"} and not $self->{"quiet"}
MC/DC100%2/2
defined $self->{"missing"} and not $self->{"quiet"}
defined $self->{"missing"}
not $self->{"quiet"}
Truth table100%3/3
A and not(B)
A= defined $self->{"missing"}B= not $self->{"quiet"}
| |||||||||||||||||||||||||||||
| 369 | $self->{cli}->log->error( 'no .toolingrc above %s', | ||||||||||||||||||||||||||||
| 370 | 1 | delete $self->{missing} ); | |||||||||||||||||||||||||||
| 371 | } | ||||||||||||||||||||||||||||
| 372 | |||||||||||||||||||||||||||||
| 373 | 176 | return $self->{checkout}; | |||||||||||||||||||||||||||
| 374 | } | ||||||||||||||||||||||||||||
| 375 | |||||||||||||||||||||||||||||
| 376 | # $self->command(\@cmd, %args): | ||||||||||||||||||||||||||||
| 377 | # Run one child command through Fugu::Process->run, as an | ||||||||||||||||||||||||||||
| 378 | # argument list and never through a shell. The remaining | ||||||||||||||||||||||||||||
| 379 | # arguments reach Fugu::Process->run, so a caller of the plain | ||||||||||||||||||||||||||||
| 380 | # form names cwd, stdin, env or timeout there. The group form | ||||||||||||||||||||||||||||
| 381 | # takes another set, and _group names it. | ||||||||||||||||||||||||||||
| 382 | # | ||||||||||||||||||||||||||||
| 383 | # The method writes the command line to standard error under | ||||||||||||||||||||||||||||
| 384 | # --verbose, before the child runs. It writes the captured | ||||||||||||||||||||||||||||
| 385 | # standard error of the child to standard error, in full. | ||||||||||||||||||||||||||||
| 386 | # | ||||||||||||||||||||||||||||
| 387 | # It returns the captured standard output, and undef with the | ||||||||||||||||||||||||||||
| 388 | # reason in error(). A child that writes nothing gives the empty | ||||||||||||||||||||||||||||
| 389 | # string, so a caller tests the return value with defined. | ||||||||||||||||||||||||||||
| 390 | # | ||||||||||||||||||||||||||||
| 391 | # With group => 1 the child leads its own session, and the | ||||||||||||||||||||||||||||
| 392 | # method keeps its pid in child() while it waits. _group holds | ||||||||||||||||||||||||||||
| 393 | # that form. | ||||||||||||||||||||||||||||
| 394 | 285 | ▶ | sub command ( $self, $cmd, %args ) | ||||||||||||||||||||||||||
|
Subroutine
command: called CC=7 SCAR=19.5
Pod
documented
| |||||||||||||||||||||||||||||
| 395 | { | ||||||||||||||||||||||||||||
| 396 | 285 | my $log = $self->{cli}->log; | |||||||||||||||||||||||||||
| 397 | 285 | $self->{error} = undef; | |||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||
| 399 | $log->info( 'run: %s', join q{ }, @$cmd ) | ||||||||||||||||||||||||||||
| 400 | 285 | ▶ | if $self->{cli}->option('verbose'); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 401 | |||||||||||||||||||||||||||||
| 402 | 285 | ▶ | return $self->_group( $cmd, %args ) if delete $args{group}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 403 | |||||||||||||||||||||||||||||
| 404 | 249 | my $result = Fugu::Process->run( cmd => $cmd, %args ); | |||||||||||||||||||||||||||
| 405 | 249 | ▶ | if ( defined $result->{error} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 406 | 1 | $self->{error} = $result->{error}; | |||||||||||||||||||||||||||
| 407 | 1 | return; | |||||||||||||||||||||||||||
| 408 | } | ||||||||||||||||||||||||||||
| 409 | |||||||||||||||||||||||||||||
| 410 | 248 | ▶ | print STDERR $result->{stderr} if length $result->{stderr}; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 411 | |||||||||||||||||||||||||||||
| 412 | 248 | ▶ | unless ( $result->{success} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 413 | $self->{error} = | ||||||||||||||||||||||||||||
| 414 | $result->{timed_out} | ||||||||||||||||||||||||||||
| 415 | 16 | ▶ | ? "$cmd->[0] timed out" | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 416 | : "$cmd->[0] exited $result->{exit_code}"; | ||||||||||||||||||||||||||||
| 417 | 16 | return; | |||||||||||||||||||||||||||
| 418 | } | ||||||||||||||||||||||||||||
| 419 | |||||||||||||||||||||||||||||
| 420 | 232 | return $result->{stdout}; | |||||||||||||||||||||||||||
| 421 | } | ||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||
| 423 | # $self->_group($cmd, %args): | ||||||||||||||||||||||||||||
| 424 | # The group form of command(). Fugu::Process->spawn_command | ||||||||||||||||||||||||||||
| 425 | # starts the child with daemonize, so the child leads its own | ||||||||||||||||||||||||||||
| 426 | # session and its own process group. The pid stays in child() | ||||||||||||||||||||||||||||
| 427 | # while the parent waits, so a signal handler stops the whole | ||||||||||||||||||||||||||||
| 428 | # tree with Fugu::Process->terminate. | ||||||||||||||||||||||||||||
| 429 | # | ||||||||||||||||||||||||||||
| 430 | # spawn_command opens each stream by its path, and two opens of | ||||||||||||||||||||||||||||
| 431 | # one path truncate that file twice. So the child writes its two | ||||||||||||||||||||||||||||
| 432 | # streams to two files of one temporary directory. The method | ||||||||||||||||||||||||||||
| 433 | # writes both files to standard error after the exit, because a | ||||||||||||||||||||||||||||
| 434 | # child writes no part of the result (CLI-PROGRAM-4). | ||||||||||||||||||||||||||||
| 435 | # | ||||||||||||||||||||||||||||
| 436 | # spawn_command takes stdin, env, and inherit, and it takes | ||||||||||||||||||||||||||||
| 437 | # neither cwd nor timeout. A caller that needs one of those two | ||||||||||||||||||||||||||||
| 438 | # uses the plain form. | ||||||||||||||||||||||||||||
| 439 | 36 | ▶ | sub _group ( $self, $cmd, %args ) | ||||||||||||||||||||||||||
|
Subroutine
_group: called CC=7 SCAR=20.2
| |||||||||||||||||||||||||||||
| 440 | { | ||||||||||||||||||||||||||||
| 441 | 36 | my $dir = File::Temp->newdir( | |||||||||||||||||||||||||||
| 442 | TEMPLATE => 'fugubench-XXXXXXXX', | ||||||||||||||||||||||||||||
| 443 | TMPDIR => 1 | ||||||||||||||||||||||||||||
| 444 | ); | ||||||||||||||||||||||||||||
| 445 | 36 | my @files = ( "$dir/stdout", "$dir/stderr" ); | |||||||||||||||||||||||||||
| 446 | |||||||||||||||||||||||||||||
| 447 | 36 | my $result = Fugu::Process->spawn_command( | |||||||||||||||||||||||||||
| 448 | cmd => $cmd, | ||||||||||||||||||||||||||||
| 449 | daemonize => 1, | ||||||||||||||||||||||||||||
| 450 | stdout => $files[0], | ||||||||||||||||||||||||||||
| 451 | stderr => $files[1], | ||||||||||||||||||||||||||||
| 452 | %args | ||||||||||||||||||||||||||||
| 453 | ); | ||||||||||||||||||||||||||||
| 454 | 36 | ▶ | unless ( $result->{success} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 455 | 0 | $self->{error} = $result->{error}; | |||||||||||||||||||||||||||
| 456 | 0 | return; | |||||||||||||||||||||||||||
| 457 | } | ||||||||||||||||||||||||||||
| 458 | |||||||||||||||||||||||||||||
| 459 | 36 | $self->{child} = $result->{pid}; | |||||||||||||||||||||||||||
| 460 | 36 | my $reaped = waitpid $result->{pid}, 0; | |||||||||||||||||||||||||||
| 461 | |||||||||||||||||||||||||||||
| 462 | # The errno of the wait, next to the wait itself. A read below | ||||||||||||||||||||||||||||
| 463 | # that fails overwrites $!, and the message of a wait that | ||||||||||||||||||||||||||||
| 464 | # reaps no child must name the errno of the wait. | ||||||||||||||||||||||||||||
| 465 | 35 | my $errno = $!; | |||||||||||||||||||||||||||
| 466 | 35 | my $code = Fugu::Process->exit_code($?); | |||||||||||||||||||||||||||
| 467 | 35 | $self->{child} = undef; | |||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||
| 469 | 35 | for my $file (@files) { | |||||||||||||||||||||||||||
| 470 | 70 | my $text = Fugu::File->read($file); | |||||||||||||||||||||||||||
| 471 | 70 | ▶ | print STDERR $text if defined $text && length $text; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $text and length $text
MC/DC50%1/2
defined $text and length $text
defined $text
length $text
Truth table66%2/3
A and B
A= defined $textB= length $text
| |||||||||||||||||||||||||||||
| 472 | } | ||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||
| 474 | # A wait that reaps no child leaves the status of an earlier | ||||||||||||||||||||||||||||
| 475 | # one in $?, so the code above belongs to no run of this | ||||||||||||||||||||||||||||
| 476 | # command. | ||||||||||||||||||||||||||||
| 477 | 35 | ▶ | if ( $reaped != $result->{pid} ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 478 | 0 | $self->{error} = "$cmd->[0] left no status: $errno"; | |||||||||||||||||||||||||||
| 479 | 0 | return; | |||||||||||||||||||||||||||
| 480 | } | ||||||||||||||||||||||||||||
| 481 | |||||||||||||||||||||||||||||
| 482 | 35 | ▶ | unless ( $code == 0 ) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 483 | 2 | $self->{error} = "$cmd->[0] exited $code"; | |||||||||||||||||||||||||||
| 484 | 2 | return; | |||||||||||||||||||||||||||
| 485 | } | ||||||||||||||||||||||||||||
| 486 | |||||||||||||||||||||||||||||
| 487 | 33 | return q{}; | |||||||||||||||||||||||||||
| 488 | } | ||||||||||||||||||||||||||||
| 489 | |||||||||||||||||||||||||||||
| 490 | 117 | 1; | |||||||||||||||||||||||||||