| 1 | #!/usr/bin/perl -I/home/phil/perl/cpan/DataTableText/lib | ||
| 2 | #------------------------------------------------------------------------------- | ||
| 3 | # Exchange files and update issues with your colleagues via an S3 bucket or rsync. | ||
| 4 | # Philip R Brenan at gmail dot com, Appa Apps Ltd Inc., 2018 | ||
| 5 | #------------------------------------------------------------------------------- | ||
| 6 | # podDocumentation | ||
| 7 | # rsync remote requires we create the target nexus folder | ||
| 8 | |||
| 9 | package Data::Exchange; | ||
| 10 | our $VERSION = q(20181002); | ||
| 11 | require v5.16; | ||
| 12 | use warnings FATAL => qw(all); | ||
| 13 | use strict; | ||
| 14 | use Carp; | ||
| 15 | use Data::Dump qw(dump); | ||
| 16 | use Data::Table::Text qw(:all); | ||
| 17 | use POSIX qw(strftime); # http://www.cplusplus.com/reference/ctime/strftime/ | ||
| 18 | use utf8; | ||
| 19 | |||
| 20 | sub debug {0} # 0 - distribution, 1 - test, 2 - production | ||
| 21 | sub testTransport{2} # 0 - S3, 1 - rsync locally, 2 - rsync remote | ||
| 22 | |||
| 23 | sub lll(@) # Log messages | ||
| 24 | {my $m = join '', @_; | ||
| 25 | return unless $m =~ m(\S)s; # Blank messages | ||
| 26 | say STDERR $m; | ||
| 27 | if (userId =~ m(\Aphil\Z)s) | ||
| 28 | {appendFile(q(/home/phil/zzz2.txt), dateTimeStamp." $m\n"); | ||
| 29 | } | ||
| 30 | } | ||
| 31 | |||
| 32 | lll "Exchange Start version $VERSION"; | ||
| 33 | |||
| 34 | if (@ARGV) # Process any command line arguments | ||
| 35 | {parseCommandLineArguments | ||
| 36 | {my ($pos, $key) = @_; | ||
| 37 | lll "Exchange parse ", dump(\@ARGV); | ||
| 38 | if (my $f = $$key{file}) | ||
| 39 | {lll "Evaluate: $f"; | ||
| 40 | my $p = evalFile($f); | ||
| 41 | my $x = new(%$p); | ||
| 42 | lll "Exchange go\n", dump($x); | ||
| 43 | $x->go(); | ||
| 44 | exit; | ||
| 45 | } | ||
| 46 | } \@ARGV, | ||
| 47 | {file=>q(The file from which to read parameters), | ||
| 48 | } | ||
| 49 | } | ||
| 50 | |||
| 51 | sub boldFilesWithChanges #P Bold file names with changed contents # Bold file names with changed contents | ||
| 52 | {0 | ||
| 53 | } | ||
| 54 | sub bucket #P Default bucket used for exchanges | ||
| 55 | {q(ryffine.exchange) | ||
| 56 | } | ||
| 57 | |||
| 58 | sub issueFileExtension #P Default extension that identifies issue files | ||
| 59 | {q(txt) | ||
| 60 | } | ||
| 61 | |||
| 62 | sub nexus #P Default nexus folder every-one can reach | ||
| 63 | {return fpf(q(phil@13.58.60.171:/home/phil/perl/xxx/)) if testTransport == 2; | ||
| 64 | fpf(q(/home/phil/perl/xxxNexus/)); | ||
| 65 | } | ||
| 66 | |||
| 67 | sub quiet #P Quiet S3/rsync if true | ||
| 68 | {0 | ||
| 69 | } | ||
| 70 | |||
| 71 | sub rsyncOptions #P Rsync options | ||
| 72 | {q(-mpqrt) | ||
| 73 | } | ||
| 74 | |||
| 75 | sub sep #P Time section separator | ||
| 76 | {q(At \d\d\d\d\.\d\d\.\d\d \d\d:\d\d:\d\d \d{7} from \w+); | ||
| 77 | } | ||
| 78 | |||
| 79 | sub transport #P Default file transferm can be q(s3) or q(rsync) | ||
| 80 | {q(rsync) | ||
| 81 | } | ||
| 82 | |||
| 83 | sub writeLine #P Write line | ||
| 84 | {q(Write below then remove this line when done); | ||
| 85 | } | ||
| 86 | |||
| 87 | #D1 File and Issue Exchanger # Exchange files and update issues with your colleagues via an S3 bucket or rsync. | ||
| 88 | |||
| 89 | sub new(@) # Create a new exchanger for a specified user allowing them to exchange files and issues with their colleagues via an S3 bucket or rsync - see: L<Data::Exchange Definition|/Data::Exchange Definition> for the attributes that can be set by this constructor. | ||
| 90 | {my (@parms) = @_; # Optional parameters | ||
| 91 | genHash(q(Data::Exchange::Details), # Exchanger attributes. | ||
| 92 | boldFilesWithChanges => boldFilesWithChanges, # Bold file names with changed contents | ||
| 93 | bucket => bucket, # The meeting point expressed as bucket/optionalPrefix for S3 transport | ||
| 94 | exchange => undef, # Folder containing files locally | ||
| 95 | ext => issueFileExtension, # Extension of issue files | ||
| 96 | interval => q(120), # Interval between exchanges | ||
| 97 | nexus => nexus, # The meeting point expressed as a target for rsync transport | ||
| 98 | quiet => quiet, # Quiet S3/rsync if true | ||
| 99 | rsyncOptions => rsyncOptions, # Rsync options | ||
| 100 | s3Parms => q(--profile fmc), # Additional S3 parms | ||
| 101 | service => undef, #P Service incarnation | ||
| 102 | start => time, # Time this exchanger was started | ||
| 103 | transport => transport, # Default file transfer | ||
| 104 | user => undef, # User who owns this instance | ||
| 105 | version => $VERSION, #P Version of this software | ||
| 106 | inProgressFiles => {}, #P Files that are in progress and so cannot be updated | ||
| 107 | @_, | ||
| 108 | ); | ||
| 109 | } | ||
| 110 | |||
| 111 | my $stampCount = 0; # Separate otherwise identical time stamps with one second resolution | ||
| 112 | |||
| 113 | sub Data::Exchange::Details::stamp($) #P Match files that have the same file name. | ||
| 114 | {my ($x) = @_; # Exchanger | ||
| 115 | my $c = sprintf("%07d", ++$stampCount); # Sequence number | ||
| 116 | my $u = $x->user; # User | ||
| 117 | strftime(qq(At %Y.%m.%d %H:%M:%S $c from $u\n), gmtime) # Stamp | ||
| 118 | } | ||
| 119 | |||
| 120 | sub replaceWriteLine($$) #P Replace the write line in a file | ||
| 121 | {my ($file, $line) = @_; # File, new line | ||
| 122 | my $w = writeLine; # Write line | ||
| 123 | my $s = my $S = readFile($file); # Read file | ||
| 124 | $s =~ s(\A\+$w\n) ($line\n)s; # Change write line to add message and release | ||
| 125 | owf($file, $s) unless $s eq $S; # Rewrite file | ||
| 126 | } | ||
| 127 | |||
| 128 | sub cutByTime($) #P Cut a single file into time sections. | ||
| 129 | {my ($file) = @_; # File | ||
| 130 | |||
| 131 | my $t = readFile($file); # Read file | ||
| 132 | my $s = sep; | ||
| 133 | my $w = writeLine; | ||
| 134 | my @a = split /(?=^$s$)/m, $t; # Split into time sections | ||
| 135 | my @b; | ||
| 136 | for(@a) | ||
| 137 | {if (/\A\s*($s\s*)?(\+$w\s*)+\Z/s) # Ignore empty sections | ||
| 138 | {lll "cutByTime ignored $_"; | ||
| 139 | } | ||
| 140 | else | ||
| 141 | {lll "cutByTime saved $_"; | ||
| 142 | push @b, $_; | ||
| 143 | } | ||
| 144 | } | ||
| 145 | @b | ||
| 146 | } | ||
| 147 | |||
| 148 | sub Data::Exchange::Details::findIssueFiles($) #P Find all the files that are issues | ||
| 149 | {my ($x) = @_; # Exchanger | ||
| 150 | searchDirectoryTreesForMatchingFiles | ||
| 151 | ($x->exchange, | ||
| 152 | $x->ext); | ||
| 153 | } | ||
| 154 | |||
| 155 | sub inProgressFile($) #P Check whether a file is a work in progress depending on whether it has a plus sign in column 1 of line 1 or not. | ||
| 156 | {my ($file) = @_; # File | ||
| 157 | return 0 unless -e $file; | ||
| 158 | my $s = readFile($file); | ||
| 159 | my $r = $s =~ m(\A\+)s ? 1 : 0; # Plus sign present or not | ||
| 160 | $r | ||
| 161 | } | ||
| 162 | |||
| 163 | sub Data::Exchange::Details::findInProgressFiles($) #P Find all the files that are in progress. | ||
| 164 | {my ($x) = @_; # Exchanger | ||
| 165 | |||
| 166 | my %files; | ||
| 167 | for my $file($x->findIssueFiles) # Find all issue files in progress | ||
| 168 | {if (inProgressFile($file)) | ||
| 169 | {$files{$file}++ | ||
| 170 | } | ||
| 171 | } | ||
| 172 | |||
| 173 | $x->inProgressFiles = \%files | ||
| 174 | } | ||
| 175 | |||
| 176 | sub Data::Exchange::Details::assemble($@) #P Assemble the time sections in multiple files into one file. | ||
| 177 | {my ($x, @files) = @_; # Exchanger, Files | ||
| 178 | |||
| 179 | my %times; | ||
| 180 | for my $file(@files) # Time sections | ||
| 181 | {for my $s(cutByTime($file)) | ||
| 182 | {$times{substr($s, 0, length($x->stamp))} = $s; # Hash of sections by time | ||
| 183 | } | ||
| 184 | } | ||
| 185 | |||
| 186 | my @t = map {$times{$_}} # Sections in reverse time order | ||
| 187 | reverse sort keys %times; | ||
| 188 | |||
| 189 | my $t = join '', @t; # Text of new file | ||
| 190 | $t | ||
| 191 | } | ||
| 192 | |||
| 193 | sub Data::Exchange::Details::matchFiles($) #P Match files that have the same file name. | ||
| 194 | {my ($x) = @_; # Exchanger | ||
| 195 | my %files; | ||
| 196 | $x->exchange or confess; | ||
| 197 | my $user = $x->user; | ||
| 198 | |||
| 199 | for my $file($x->findIssueFiles) # Files that can be matched | ||
| 200 | {my $f = fne $file; | ||
| 201 | $files{$f}{$file}++; | ||
| 202 | } | ||
| 203 | |||
| 204 | for my $file(sort keys %files) # Do not match files that are in progress | ||
| 205 | {if ($x->inProgressFiles->{fpe($x->localFolder, $file, $x->ext)}) | ||
| 206 | {delete $files{$file}; | ||
| 207 | } | ||
| 208 | } | ||
| 209 | |||
| 210 | if (!keys %files) | ||
| 211 | {lll "Match files: no files to match"; | ||
| 212 | return; | ||
| 213 | } | ||
| 214 | else | ||
| 215 | {lll "Match files ", dump(\%files); | ||
| 216 | } | ||
| 217 | |||
| 218 | for my $file(sort keys %files) # Assemble issue files | ||
| 219 | {my $subFiles = $files{$file}; | ||
| 220 | lll "Match file $file with ", dump($subFiles); | ||
| 221 | my $f = fpf($x->exchange, $x->user, $file); # User's copy of issue | ||
| 222 | if (-e $f and inProgressFile($f)) | ||
| 223 | {lll "Match file $file with in progress file $f"; | ||
| 224 | next; | ||
| 225 | } | ||
| 226 | my $w = writeLine; | ||
| 227 | my @F = sort keys %$subFiles; | ||
| 228 | if (@F == 1) # A single file is already assembled | ||
| 229 | {lll "Match file for user $user: ", dump([@F]); | ||
| 230 | my $F = $F[0]; | ||
| 231 | if ($F =~ m(/$user/)s) | ||
| 232 | {lll "Match file $f is a single user file and so does not need to be reassembled"; | ||
| 233 | } | ||
| 234 | elsif (!-e $f) | ||
| 235 | {lll "Match file create $f from $F"; | ||
| 236 | writeFile($f, qq(+$w\n\n\n).readFile($F)); | ||
| 237 | } | ||
| 238 | else | ||
| 239 | {lll "Match file cannot create file $f from $F"; | ||
| 240 | } | ||
| 241 | } | ||
| 242 | else # Assemble files | ||
| 243 | {my $a = $x->assemble(keys %$subFiles); | ||
| 244 | if (-e $f) | ||
| 245 | {my $b = readFile($f); | ||
| 246 | if ($a ne $b) | ||
| 247 | {my $c = qq(+$w\n\n\n).$a; | ||
| 248 | lll "Match files update $f\n$a"; | ||
| 249 | if (!inProgressFile($f)) # Last minute check that the file is not in progress | ||
| 250 | {$x->service->check; # Check that we are still the update service | ||
| 251 | owf($f, $c); | ||
| 252 | } | ||
| 253 | } | ||
| 254 | } | ||
| 255 | } | ||
| 256 | } | ||
| 257 | } | ||
| 258 | |||
| 259 | sub Data::Exchange::Details::listFiles($) #P List user files | ||
| 260 | {my ($x) = @_; # Exchanger | ||
| 261 | my @files; | ||
| 262 | |||
| 263 | my @f = searchDirectoryTreesForMatchingFiles # Find files to match | ||
| 264 | ($x->exchange, | ||
| 265 | $x->ext); | ||
| 266 | |||
| 267 | my $sep = sep; | ||
| 268 | |||
| 269 | for my $file(@f) # Match files | ||
| 270 | {my $t = readFile($file); # Read file | ||
| 271 | my @t = split /(?=^$sep$)/m, $t; # Split into time sections | ||
| 272 | for my $t(keys @t) | ||
| 273 | {$t[$t] =~ s($sep) (At $t\n)gs; | ||
| 274 | } | ||
| 275 | push @files, [$file, @t]; | ||
| 276 | } | ||
| 277 | |||
| 278 | [@files] | ||
| 279 | } | ||
| 280 | |||
| 281 | sub boldFileName($) #P Create a bold file name | ||
| 282 | {my ($file) = @_; # File name | ||
| 283 | my $p = fp $file; | ||
| 284 | my $f = fn $file; | ||
| 285 | my $x = fe $file; | ||
| 286 | fpe($p, boldString($f), $x) | ||
| 287 | } | ||
| 288 | |||
| 289 | sub unBoldFileName($) #P Remove bolding from file name | ||
| 290 | {my ($file) = @_; # File name | ||
| 291 | boldStringUndo($file) | ||
| 292 | } | ||
| 293 | |||
| 294 | sub Data::Exchange::Details::unBoldFiles($) #P Make all issue files non bold. | ||
| 295 | {my ($x) = @_; # Exchanger | ||
| 296 | my @files = searchDirectoryTreesForMatchingFiles # Issue files | ||
| 297 | ($x->exchange, | ||
| 298 | $x->ext); | ||
| 299 | |||
| 300 | for my $File(@files) # Each file | ||
| 301 | {if (!inProgressFile($File)) | ||
| 302 | {my $file = boldStringUndo($File); | ||
| 303 | qx(cp $File $file; rm $File) if $file ne $File; # Unbold file name | ||
| 304 | } | ||
| 305 | } | ||
| 306 | } | ||
| 307 | |||
| 308 | sub Data::Exchange::Details::localFolder($) #P The local folder containing the users own files. | ||
| 309 | {my ($x) = @_; # Exchanger | ||
| 310 | fpd($x->exchange, $x->user); | ||
| 311 | } | ||
| 312 | |||
| 313 | sub Data::Exchange::Details::stampUnstampedFiles($) #P Add a time stamp to files that are no longer in progress | ||
| 314 | {my ($x) = @_; # Exchanger | ||
| 315 | my $sep = sep; | ||
| 316 | my $ipf = $x->inProgressFiles; | ||
| 317 | for my $file($x->findIssueFiles) # Each issue file | ||
| 318 | {if (!$ipf->{$file}) # Each updateable issue file | ||
| 319 | {my $s = readFile($file); # Read file | ||
| 320 | if ($s !~ m(\A$sep)s) # Add stamp if not stamped and not in progress | ||
| 321 | {owf($file, $x->stamp.$s); # Write stamp | ||
| 322 | } | ||
| 323 | } | ||
| 324 | } | ||
| 325 | } | ||
| 326 | |||
| 327 | sub Data::Exchange::Details::exchangeUp($) #P Send one set of files. | ||
| 328 | {my ($x) = @_; # Exchanger | ||
| 329 | if ($x->transport =~ m(\Arsync\Z)i) # Empty folder reached by rsync | ||
| 330 | {my $o = $x->rsyncOptions; # Rsync options | ||
| 331 | my $s = fpd($x->exchange, $x->user); # User's own files locally | ||
| 332 | my $t = fpd($x->nexus, $x->user); # User's own files on nexus | ||
| 333 | makePath($_) for $s, $t; | ||
| 334 | my $c = qq(rsync $o $s $t); # Command | ||
| 335 | qx($c 2>&1); # Execute | ||
| 336 | } | ||
| 337 | else # Use S3 as default transport | ||
| 338 | {my $s = fpd($x->localFolder); # User's own files | ||
| 339 | my $t = fpd($x->bucket, $x->user); # User's own files on S3 | ||
| 340 | my $p = $x->s3Parms; # Additional parameters for s3 | ||
| 341 | my $q = $x->quiet ? q(--quiet) : q(); # Quiet S3 | ||
| 342 | lll my $c = qq(aws s3 sync $s s3://$t $q --delete $p); # Command | ||
| 343 | lll qx($c 2>&1); # Execute | ||
| 344 | } | ||
| 345 | } | ||
| 346 | |||
| 347 | sub Data::Exchange::Details::exchangeDown($) #P Receive one set of files. | ||
| 348 | {my ($x) = @_; # Exchanger | ||
| 349 | if ($x->transport =~ m(\Arsync\Z)i) # Empty folder reached by rsync | ||
| 350 | {my $o = $x->rsyncOptions; # Rsync options | ||
| 351 | my $u = $x->user; # User | ||
| 352 | my $s = fpd($x->nexus); # Nexus | ||
| 353 | my $t = fpd($x->exchange); # Local files | ||
| 354 | makePath($_) for $s, $t; | ||
| 355 | my $c = qq(rsync $o --exclude="*/$u/*" $s $t); # Command | ||
| 356 | qx($c 2>&1); # Execute | ||
| 357 | } | ||
| 358 | else # Use S3 as default transport | ||
| 359 | {my $u = $x->user; # Receiver | ||
| 360 | my $s = fpd($x->bucket); # User's own files on S3 | ||
| 361 | my $t = fpd($x->exchange); # All possible exchange files | ||
| 362 | my $p = $x->s3Parms; # Additional parameters for s3 | ||
| 363 | my $q = $x->quiet ? q(--quiet) : q(); # Quiet S3 | ||
| 364 | lll my $c = qq(aws s3 sync s3://$s $t $q --exclude "$u/*" $p); # Command | ||
| 365 | lll qx($c 2>&1); # Execute | ||
| 366 | } | ||
| 367 | } | ||
| 368 | |||
| 369 | sub Data::Exchange::Details::exchangeOneSet($) #P Exchange one set of files. | ||
| 370 | {my ($x) = @_; # Exchanger | ||
| 371 | makePath(fpd($x->exchange, $x->user)); # Otherwise no issues will be created for this user | ||
| 372 | lll "\nExchangeOneSet"; | ||
| 373 | # $x->unBoldFiles; # Unbold file names | ||
| 374 | $x->findInProgressFiles; # Issue files not in progress which can, therefore, be updated | ||
| 375 | $x->stampUnstampedFiles; # Stamp unstampted files | ||
| 376 | $x->exchangeUp; # Send files | ||
| 377 | $x->exchangeDown; # Receive files | ||
| 378 | $x->matchFiles; # Match files | ||
| 379 | } | ||
| 380 | |||
| 381 | sub Data::Exchange::Details::go($) #P Run until forcibly stopped. | ||
| 382 | {my ($x) = @_; # Exchanger | ||
| 383 | lll "Go"; | ||
| 384 | my $s = newServiceIncarnation(q(exchange).$x->user); # Service representing exchanger | ||
| 385 | makePath($x->localFolder); # Make the folder for the user | ||
| 386 | $x->service = $s->check; # Assigns service | ||
| 387 | for(;;) # Exchange and sleep | ||
| 388 | {$x->service->check; # Check we should continue | ||
| 389 | $x->exchangeOneSet; # Exchange | ||
| 390 | sleep $x->interval unless hostName =~ m(\A(pousadouros|secarias)\Z)s; # Testing | ||
| 391 | sleep 10; # Stop runaways | ||
| 392 | } | ||
| 393 | } | ||
| 394 | |||
| 395 | sub Data::Exchange::Details::start # Start a new exchanger as a service via atq. | ||
| 396 | {my ($x) = @_; # Exchanger | ||
| 397 | my $e = dumpFile(undef, $x); # Temporary file with exchange parameters | ||
| 398 | my $p = qq(perl $0 --file=$e); # Perl command to start exchanger | ||
| 399 | my $f = writeFile(undef, $p); # Temporary file with perl command | ||
| 400 | if ($^O =~ m(MSWin32)is) # Run windows directly from command line | ||
| 401 | {lll "Execute ", $p; | ||
| 402 | say STDERR $_ for qx($p); # Execute from command line | ||
| 403 | } | ||
| 404 | else # Unix - run as atq | ||
| 405 | {my $c = qq(at now -f $f); | ||
| 406 | say STDERR $c; | ||
| 407 | say STDERR $_ for qx($c); # Execute from at queue | ||
| 408 | } | ||
| 409 | } | ||
| 410 | |||
| 411 | #D | ||
| 412 | # podDocumentation | ||
| 413 | |||
| 414 | =pod | ||
| 415 | |||
| 416 | =encoding utf-8 | ||
| 417 | |||
| 418 | =head1 Name | ||
| 419 | |||
| 420 | Exchange files and update issues with your colleagues via an S3 bucket or rsync. | ||
| 421 | |||
| 422 | =head1 Synopsis | ||
| 423 | |||
| 424 | Configure and run an exchanger: | ||
| 425 | |||
| 426 | use Data::Exchange; | ||
| 427 | my $x = Data::Exchange::new(); | ||
| 428 | $x->user = q(phil); | ||
| 429 | $x->bucket = q(com.appaapps.exchange); | ||
| 430 | $x->exchange = q(/home/phil/exchange); | ||
| 431 | $x->start; | ||
| 432 | |||
| 433 | Files that end in .txt no matter where they are located below the exchange | ||
| 434 | folder: | ||
| 435 | |||
| 436 | $x->exchange | ||
| 437 | |||
| 438 | will be merged with files of the same name from your colleagues whose files | ||
| 439 | show up in other folders under the exchange folder, allowing you to share files | ||
| 440 | and update issues with your colleagues. | ||
| 441 | |||
| 442 | Issue files that start with a plus sign B<+> in column one of line one are | ||
| 443 | assumed to be work in progress and will be ignored until the initial plus sign | ||
| 444 | is removed. | ||
| 445 | |||
| 446 | Lines which start with defined keywords in column one have special meanings if | ||
| 447 | the occur in the first section of an issues file: | ||
| 448 | |||
| 449 | to: user | ||
| 450 | |||
| 451 | The name of the user to which this issue is addressed otherwise B<all> users will | ||
| 452 | see copies of this issue. | ||
| 453 | |||
| 454 | =head1 Description | ||
| 455 | |||
| 456 | files and update issues with your colleagues via an S3 bucket or rsync. | ||
| 457 | |||
| 458 | The following sections describe the methods in each functional area of this | ||
| 459 | module. For an alphabetic listing of all methods by name see L<Index|/Index>. | ||
| 460 | |||
| 461 | |||
| 462 | |||
| 463 | =head1 File and Issue Exchanger | ||
| 464 | |||
| 465 | Exchange files and update issues with your colleagues via an S3 bucket or rsync. | ||
| 466 | |||
| 467 | =head2 new(@) | ||
| 468 | |||
| 469 | Create a new exchanger for a specified user allowing them to exchange files and issues with their colleagues via an S3 bucket or rsync - see: L<Data::Exchange Definition|/Data::Exchange Definition> for the attributes that can be set by this constructor. | ||
| 470 | |||
| 471 | Parameter Description | ||
| 472 | 1 @parms Optional parameters | ||
| 473 | |||
| 474 | Example: | ||
| 475 | |||
| 476 | |||
| 477 | my $x = Data::Exchange::𝗻𝗲𝘄(); | ||
| 478 | |||
| 479 | |||
| 480 | =head2 Data::Exchange::Details::start() | ||
| 481 | |||
| 482 | Start a new exchanger as a service via atq. | ||
| 483 | |||
| 484 | |||
| 485 | Example: | ||
| 486 | |||
| 487 | |||
| 488 | $x->start; | ||
| 489 | |||
| 490 | |||
| 491 | |||
| 492 | =head1 Hash Definitions | ||
| 493 | |||
| 494 | |||
| 495 | |||
| 496 | |||
| 497 | =head2 Data::Exchange::Details Definition | ||
| 498 | |||
| 499 | |||
| 500 | Exchanger attributes. | ||
| 501 | |||
| 502 | |||
| 503 | B<boldFilesWithChanges> - Bold file names with changed contents | ||
| 504 | |||
| 505 | B<bucket> - The meeting point expressed as bucket/optionalPrefix for S3 transport | ||
| 506 | |||
| 507 | B<exchange> - Folder containing files locally | ||
| 508 | |||
| 509 | B<ext> - Extension of issue files | ||
| 510 | |||
| 511 | B<interval> - Interval between exchanges | ||
| 512 | |||
| 513 | B<nexus> - The meeting point expressed as a target for rsync transport | ||
| 514 | |||
| 515 | B<quiet> - Quiet S3/rsync if true | ||
| 516 | |||
| 517 | B<rsyncOptions> - Rsync options | ||
| 518 | |||
| 519 | B<s3Parms> - Additional S3 parms | ||
| 520 | |||
| 521 | B<start> - Time this exchanger was started | ||
| 522 | |||
| 523 | B<transport> - Default file transfer | ||
| 524 | |||
| 525 | B<user> - User who owns this instance | ||
| 526 | |||
| 527 | |||
| 528 | |||
| 529 | =head1 Private Methods | ||
| 530 | |||
| 531 | =head2 Data::Exchange::Details::stamp($) | ||
| 532 | |||
| 533 | Match files that have the same file name. | ||
| 534 | |||
| 535 | Parameter Description | ||
| 536 | 1 $x Exchanger | ||
| 537 | |||
| 538 | =head2 replaceWriteLine($$) | ||
| 539 | |||
| 540 | Replace the write line in a file | ||
| 541 | |||
| 542 | Parameter Description | ||
| 543 | 1 $file File | ||
| 544 | 2 $line New line | ||
| 545 | |||
| 546 | =head2 cutByTime($) | ||
| 547 | |||
| 548 | Cut a single file into time sections. | ||
| 549 | |||
| 550 | Parameter Description | ||
| 551 | 1 $file File | ||
| 552 | |||
| 553 | =head2 Data::Exchange::Details::findIssueFiles($) | ||
| 554 | |||
| 555 | Find all the files that are issues | ||
| 556 | |||
| 557 | Parameter Description | ||
| 558 | 1 $x Exchanger | ||
| 559 | |||
| 560 | =head2 inProgressFile($) | ||
| 561 | |||
| 562 | Check whether a file is a work in progress depending on whether it has a plus sign in column 1 of line 1 or not. | ||
| 563 | |||
| 564 | Parameter Description | ||
| 565 | 1 $file File | ||
| 566 | |||
| 567 | =head2 Data::Exchange::Details::findInProgressFiles($) | ||
| 568 | |||
| 569 | Find all the files that are in progress. | ||
| 570 | |||
| 571 | Parameter Description | ||
| 572 | 1 $x Exchanger | ||
| 573 | |||
| 574 | =head2 Data::Exchange::Details::assemble($@) | ||
| 575 | |||
| 576 | Assemble the time sections in multiple files into one file. | ||
| 577 | |||
| 578 | Parameter Description | ||
| 579 | 1 $x Exchanger | ||
| 580 | 2 @files Files | ||
| 581 | |||
| 582 | =head2 Data::Exchange::Details::matchFiles($) | ||
| 583 | |||
| 584 | Match files that have the same file name. | ||
| 585 | |||
| 586 | Parameter Description | ||
| 587 | 1 $x Exchanger | ||
| 588 | |||
| 589 | =head2 Data::Exchange::Details::listFiles($) | ||
| 590 | |||
| 591 | List user files | ||
| 592 | |||
| 593 | Parameter Description | ||
| 594 | 1 $x Exchanger | ||
| 595 | |||
| 596 | =head2 boldFileName($) | ||
| 597 | |||
| 598 | Create a bold file name | ||
| 599 | |||
| 600 | Parameter Description | ||
| 601 | 1 $file File name | ||
| 602 | |||
| 603 | =head2 unBoldFileName($) | ||
| 604 | |||
| 605 | Remove bolding from file name | ||
| 606 | |||
| 607 | Parameter Description | ||
| 608 | 1 $file File name | ||
| 609 | |||
| 610 | =head2 Data::Exchange::Details::unBoldFiles($) | ||
| 611 | |||
| 612 | Make all issue files non bold. | ||
| 613 | |||
| 614 | Parameter Description | ||
| 615 | 1 $x Exchanger | ||
| 616 | |||
| 617 | =head2 Data::Exchange::Details::localFolder($) | ||
| 618 | |||
| 619 | The local folder containing the users own files. | ||
| 620 | |||
| 621 | Parameter Description | ||
| 622 | 1 $x Exchanger | ||
| 623 | |||
| 624 | =head2 Data::Exchange::Details::stampUnstampedFiles($) | ||
| 625 | |||
| 626 | Add a time stamp to files that are no longer in progress | ||
| 627 | |||
| 628 | Parameter Description | ||
| 629 | 1 $x Exchanger | ||
| 630 | |||
| 631 | =head2 Data::Exchange::Details::exchangeUp($) | ||
| 632 | |||
| 633 | Send one set of files. | ||
| 634 | |||
| 635 | Parameter Description | ||
| 636 | 1 $x Exchanger | ||
| 637 | |||
| 638 | =head2 Data::Exchange::Details::exchangeDown($) | ||
| 639 | |||
| 640 | Receive one set of files. | ||
| 641 | |||
| 642 | Parameter Description | ||
| 643 | 1 $x Exchanger | ||
| 644 | |||
| 645 | =head2 Data::Exchange::Details::exchangeOneSet($) | ||
| 646 | |||
| 647 | Exchange one set of files. | ||
| 648 | |||
| 649 | Parameter Description | ||
| 650 | 1 $x Exchanger | ||
| 651 | |||
| 652 | =head2 Data::Exchange::Details::go($) | ||
| 653 | |||
| 654 | Run until forcibly stopped. | ||
| 655 | |||
| 656 | Parameter Description | ||
| 657 | 1 $x Exchanger | ||
| 658 | |||
| 659 | |||
| 660 | =head1 Index | ||
| 661 | |||
| 662 | |||
| 663 | 1 L<boldFileName|/boldFileName> - Create a bold file name | ||
| 664 | |||
| 665 | 2 L<cutByTime|/cutByTime> - Cut a single file into time sections. | ||
| 666 | |||
| 667 | 3 L<Data::Exchange::Details::assemble|/Data::Exchange::Details::assemble> - Assemble the time sections in multiple files into one file. | ||
| 668 | |||
| 669 | 4 L<Data::Exchange::Details::exchangeDown|/Data::Exchange::Details::exchangeDown> - Receive one set of files. | ||
| 670 | |||
| 671 | 5 L<Data::Exchange::Details::exchangeOneSet|/Data::Exchange::Details::exchangeOneSet> - Exchange one set of files. | ||
| 672 | |||
| 673 | 6 L<Data::Exchange::Details::exchangeUp|/Data::Exchange::Details::exchangeUp> - Send one set of files. | ||
| 674 | |||
| 675 | 7 L<Data::Exchange::Details::findInProgressFiles|/Data::Exchange::Details::findInProgressFiles> - Find all the files that are in progress. | ||
| 676 | |||
| 677 | 8 L<Data::Exchange::Details::findIssueFiles|/Data::Exchange::Details::findIssueFiles> - Find all the files that are issues | ||
| 678 | |||
| 679 | 9 L<Data::Exchange::Details::go|/Data::Exchange::Details::go> - Run until forcibly stopped. | ||
| 680 | |||
| 681 | 10 L<Data::Exchange::Details::listFiles|/Data::Exchange::Details::listFiles> - List user files | ||
| 682 | |||
| 683 | 11 L<Data::Exchange::Details::localFolder|/Data::Exchange::Details::localFolder> - The local folder containing the users own files. | ||
| 684 | |||
| 685 | 12 L<Data::Exchange::Details::matchFiles|/Data::Exchange::Details::matchFiles> - Match files that have the same file name. | ||
| 686 | |||
| 687 | 13 L<Data::Exchange::Details::stamp|/Data::Exchange::Details::stamp> - Match files that have the same file name. | ||
| 688 | |||
| 689 | 14 L<Data::Exchange::Details::stampUnstampedFiles|/Data::Exchange::Details::stampUnstampedFiles> - Add a time stamp to files that are no longer in progress | ||
| 690 | |||
| 691 | 15 L<Data::Exchange::Details::start|/Data::Exchange::Details::start> - Start a new exchanger as a service via atq. | ||
| 692 | |||
| 693 | 16 L<Data::Exchange::Details::unBoldFiles|/Data::Exchange::Details::unBoldFiles> - Make all issue files non bold. | ||
| 694 | |||
| 695 | 17 L<inProgressFile|/inProgressFile> - Check whether a file is a work in progress depending on whether it has a plus sign in column 1 of line 1 or not. | ||
| 696 | |||
| 697 | 18 L<new|/new> - Create a new exchanger for a specified user allowing them to exchange files and issues with their colleagues via an S3 bucket or rsync - see: L<Data::Exchange Definition|/Data::Exchange Definition> for the attributes that can be set by this constructor. | ||
| 698 | |||
| 699 | 19 L<replaceWriteLine|/replaceWriteLine> - Replace the write line in a file | ||
| 700 | |||
| 701 | 20 L<unBoldFileName|/unBoldFileName> - Remove bolding from file name | ||
| 702 | |||
| 703 | =head1 Installation | ||
| 704 | |||
| 705 | This module is written in 100% Pure Perl and, thus, it is easy to read, | ||
| 706 | comprehend, use, modify and install via B<cpan>: | ||
| 707 | |||
| 708 | sudo cpan install Data::Exchange | ||
| 709 | |||
| 710 | =head1 Author | ||
| 711 | |||
| 712 | L<philiprbrenan@gmail.com|mailto:philiprbrenan@gmail.com> | ||
| 713 | |||
| 714 | L<http://www.appaapps.com|http://www.appaapps.com> | ||
| 715 | |||
| 716 | =head1 Copyright | ||
| 717 | |||
| 718 | Copyright (c) 2016-2018 Philip R Brenan. | ||
| 719 | |||
| 720 | This module is free software. It may be used, redistributed and/or modified | ||
| 721 | under the same terms as Perl itself. | ||
| 722 | |||
| 723 | =cut | ||
| 724 | |||
| 725 | |||
| 726 | |||
| 727 | # Tests and documentation | ||
| 728 | |||
| 729 | sub test | ||
| 730 | {my $p = __PACKAGE__; | ||
| 731 | binmode($_, ":utf8") for *STDOUT, *STDERR; | ||
| 732 | return if eval "eof(${p}::DATA)"; | ||
| 733 | my $s = eval "join('', <${p}::DATA>)"; | ||
| 734 | $@ and die $@; | ||
| 735 | eval $s; | ||
| 736 | $@ and die $@; | ||
| 737 | 1 | ||
| 738 | } | ||
| 739 | |||
| 740 | test unless caller; | ||
| 741 | |||
| 742 | 1; | ||
| 743 | # podDocumentation | ||
| 744 | __DATA__ |