Replaceable Attribute List

END push @d, join ' ', @a, "\n\n"; for my $name(@a) {my $d = $attributeDescription{$name}; push @d, qq(=head2 $name\n\n$d\n\n); } push @doc, @d; }

if (my @r = sort keys %replace)
 {push @doc, qq(\n), <<END;
`head1 Optional Replace Methods

The following is a list of all the optionally replaceable methods in this package. A method coded with the same name in your package will over ride the method of the same name in this package providing your preferred processing for the replaced method in place of the default processing supplied by this package. If you do not supply such an over riding method, the existing method in this package will be used instead.

Replaceable Method List

END push @doc, join ' ', @r, "\n\n"; }

if (1)                                                                        # Alphabetic listing of methods that still need examples
 {my %m = %methods;
  delete @m{$_, "$_ :lvalue"} for keys %examples;
  delete @m{$_, "$_ :lvalue"} for keys %private;
  my $n = keys %m;
  my $N = keys %methods;
  say STDERR formatTable(\%m), "\n$n of $N methods still need tests" if $n;
 }

if (keys %iUseful)                                                            # Alphabetic listing of immediately useful methods
  {my @d;
   push @d, <<END;

`head1 Immediately useful methods

These methods are the ones most likely to be of immediate use to anyone using this module for the first time:

END for my $m(sort {lc($a) cmp lc($b)} keys %iUseful) {my $c = $iUseful{$m}; push @d, "$m\n\n$c\n" } push @d, <<END;

END unshift @doc, (shift @doc, @d) # Put first after title }

push @doc, qq(\n\n=head1 Private Methods), @private if @private;              # Private methods in a separate section if there are any

if (keys %synonymTarget)                                                      # Synonyms
 {my @s;
  my $line;
  for my $source(sort keys %synonymTarget)
   {my $target  = $synonymTarget{$source};
    my $comment = $comment{$target} // confess "No comment for $target\n";
       $comment =~ s(\..*\Z) (\.)s;
    push @s, qq(B<$source> is a synonym for L<$target|/$target> - $comment);
   }
  my $s = join q(\n\n), @s;
  push @doc, qq(\n\n=head1 Synonyms\n\n$s\n);
 }

push @doc, qq(\n\n=head1 Index\n\n);
if (1)
 {my $n = 0;
  for my $s(sort {lc($a) cmp lc($b)} keys %methodParms)                       # Alphabetic listing of methods
   {my $t = $methodParms{$s};
    my $c = $comment{$s};
    if ($c and $t)
     {$c =~ s(\..*\Z) (\.)s;
      push @doc, ++$n.qq( L<$s|/$t> - $c\n);
     }
   }
 }

if (keys %exported)                                                           # Exported methods available
 {push @doc, <<"END";

`head1 Exports

All of the following methods can be imported via:

use $package qw(:all);

Or individually via:

use $package qw(<method>);

END

  my $n = 0;
  for my $s(sort {lc($a) cmp lc($b)} keys %exported)                          # Alphabetic listing of exported methods
   {push @doc, ++$n." L<$s|/$s>\n"
   }
 }

push @doc, <<END;                                                             # Standard stuff
`head1 Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:

sudo cpan install $package

`head1 Author

philiprbrenan\@gmail.com

http://www.appaapps.com

`head1 Copyright

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself. END

if (keys %collaborators)                                                      # Acknowledge any collaborators
 {push @doc,
   '\n=head1 Acknowledgements\m'.
   'Thanks to the following people for their help with this module:\m'.
   '=over\m';
  for(sort keys %collaborators)
   {my $p = "L<$_|mailto:$_>";
    my $r = $collaborators{$_};
    push @doc, "=item $p\n\n$r\n\n";
   }
  push @doc, '=back\m';
 }

push @doc, '=cut\m';                                                          # Finish documentation

if (keys %methodX)                                                            # Insert X method definitions
 {my @x;
  for my $x(sort keys %methodX)
   {push @x, ["sub ${x}X", "{&$x", "(\@_) || die '$x'}"];
   }
  push @doc, formatTableBasic(\@x);
 }

for my $name(sort keys %userFlags)                                            # Insert generated method definitions
 {if (my $doc = $userFlags{$name})
   {push @doc, $doc->[1] if $doc->[1];
   }
 }

push @doc, <<'END';                                                           # Standard test sequence

# Tests and documentation

sub test {my $p = __PACKAGE__; binmode($_, ":utf8") for *STDOUT, *STDERR; return if eval "eof(${p}::DATA)"; my $s = eval "join('', <${p}::DATA>)"; $@ and die $@; eval $s; $@ and die $@; 1 }

test unless caller; END

 for(@doc)                                                                     # Expand snippets in documentation
  {s/\\m/\n\n/gs;                                                              # Double new line
   s/\\n/\n/gs;                                                                # Single new line
   s/\\x//gs;                                                                  # Break
   s/`/=/gs;
   s(L<lvalueMethod>) (L<lvalue|http://perldoc.perl.org/perlsub.html#Lvalue-subroutines>);
   s(L<confess>)      (L<confess|http://perldoc.perl.org/Carp.html#SYNOPSIS/>);
   s(L<die>)          (L<die|http://perldoc.perl.org/functions/die.html>);
   s(L<eval>)         (L<eval|http://perldoc.perl.org/functions/eval.html>);
   s(L<\$_>)          (L<\$_|http://perldoc.perl.org/perlvar.html#General-Variables>);
   s(L<our>)          (L<our|https://perldoc.perl.org/functions/our.html>);
   s(L<Imagemagick>)  (L<Imagemagick|/https://www.imagemagick.org/script/index.php>);
   s(L<Dita>)         (L<Dita|http://docs.oasis-open.org/dita/dita/v1.3/os/part2-tech-content/dita-v1.3-os-part2-tech-content.html>);
   s(L<Xml parser>)   (L<Xml parser|https://metacpan.org/pod/XML::Parser/>);
   s(L<html table>)   (L<html table|https://www.w3.org/TR/html52/tabular-data.html#the-table-element>);
  }

 my $doc = join "\n", @doc;                                                    # Documentation

 #say STDERR "Documentation\n$doc", dump(\%examples); return $doc;             # Testing

 unless($sourceIsString)                                                       # Update source file
  {$source =~ s/\n+=head1 Description.+?\n+1;\n+/\n\n$doc\n1;\n/gs;            # Edit module source from =head1 description to final 1;

   if ($source ne $Source)                                                     # Save source only if it has changed and came from a file
    {overWriteFile(filePathExt($perlModule, qq(backup)), $source);             # Backup module source
     overWriteFile($perlModule, $source);                                      # Write updated module source
    }
  }

 $doc
} # updateDocumentation

sub docUserFlags($$$$) #P Generate documentation for a method by calling the extractDocumentationFlags method in the package being documented, passing it the flags for a method and the name of the method. The called method should return the documentation to be inserted for the named method. {my ($flags, $perlModule, $package, $name) = @_; # Flags, file containing documentation, package containing documentation, name of method to be processed my $s = <<END; ${package}::extractDocumentationFlags("$flags", "$name"); END

 use Data::Dump qw(dump);
 my $r = eval $s;
 confess "$s\n". dump($@, $!) if $@;
 $r
}

sub updatePerlModuleDocumentation($) #P Update the documentation in a perl file and show said documentation in a web browser. {my ($perlModule) = @_; # File containing the code of the perl module -e $perlModule or confess "No such file:\n$perlModule\n"; updateDocumentation($perlModule); # Update documentation

 zzz("pod2html --infile=$perlModule --outfile=zzz.html && ".                   # View documentation
     " firefox file:zzz.html && ".
     " (sleep 5 && rm zzz.html pod2htmd.tmp) &");
}

#------------------------------------------------------------------------------- # Export - eeee #-------------------------------------------------------------------------------

use Exporter qw(import);

use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);

# containingFolder

@ISA = qw(Exporter); @EXPORT = qw(formatTable); @EXPORT_OK = qw( absFromAbsPlusRel addCertificate addLValueScalarMethods adopt appendFile arrayToHash assertRef assertPackageRefs binModeAllUtf8 boldString boldStringUndo call checkFile checkFilePath checkFilePathExt checkFilePathDir checkKeys clearFolder contains containingPowerOfTwo convertDocxToFodt convertImageToJpx convertUnicodeToXml copyFile copyFolder createEmptyFile currentDirectory currentDirectoryAbove cutOutImagesInFodtFile dateStamp dateTimeStamp dateTimeStampName decodeJson decodeBase64 dumpFile dumpGZipFile enclosedString enclosedStringUndo enclosedReversedString enclosedReversedStringUndo encodeJson encodeBase64 evalFile evalGZipFile fileList fileModTime fileOutOfDate filePath filePathDir filePathExt fileSize findDirs findFiles findFileWithExtension firstFileThatExists firstNChars formatTableBasic fpd fpe fpf fp fe fn fpn fne fullFileName genClass genHash genLValueArrayMethods genLValueHashMethods genLValueScalarMethods genLValueScalarMethodsWithDefaultValues hostName htmlToc imageSize mergePackageMethods indentString ipAddressViaArp isBlank javaPackage javaPackageAsFileName keyCount loadArrayArrayFromLines loadArrayFromLines loadArrayHashFromLines loadHash loadHashArrayFromLines loadHashFromLines loadHashHashFromLines makeDieConfess makePath matchPath max microSecondsSinceEpoch min newServiceIncarnation newProcessStarter numberOfLinesInFile numberOfLinesInString nws overWriteFile owf pad parseFileName parseCommandLineArguments powerOfTwo printFullFileName printQw quoteFile readBinaryFile readFile readGZipFile readUtf16File relFromAbsAgainstAbs reloadHashes removeBOM removeFilePrefix retrieveFile saveCodeToS3 saveSourceToS3 searchDirectoryTreesForMatchingFiles setIntersectionOfTwoArraysOfWords setPackageSearchOrder setUnionOfTwoArraysOfWords startProcess storeFile stringsAreNotEqual superScriptString superScriptStringUndo subScriptString subScriptStringUndo swapFilePrefix temporaryDirectory temporaryFile temporaryFolder timeStamp trackFiles trim updateDocumentation updatePerlModuleDocumentation userId versionCode versionCodeDashed waitForAllStartedProcessesToFinish wwwEncode writeBinaryFile writeFile writeFiles writeGZipFile xxx XXX zzz Ë¢ ); %EXPORT_TAGS = (all=>[@EXPORT, @EXPORT_OK]);

#D # podDocumentation #C mim@cpan.org Testing on windows

Name

Data::Table::Text - Write data in tabular text format.

Synopsis

use Data::Table::Text;

# Print a table:

my $d =
 [[qq(a), qq(b\nbb), qq(c\ncc\nccc\n)],
  [qq(1), qq(1\n22), qq(1\n22\n333\n)],
 ];

my $t = formatTable($d, [qw(A BB CCC)]);

ok $t eq <<END;
   A  BB  CCC
1  a  b   c
      bb  cc
          ccc
2  1   1    1
      22   22
          333
END

# Print a table containing tables and make it into a report:

my $D = [[qq(See the\ntable\nopposite), $t],
         [qq(Or\nthis\none),            $t],
        ];


my $T = formatTable($D, [qw(Description Table)], head=><<END);
Table of Tables.

Table has NNNN rows each of which contains a table.
END

ok $T eq <<END;
Table of Tables.

Table has 2 rows each of which contains a table.


   Description  Table
1  See the         A  BB  CCC
   table        1  a  b   c
   opposite           bb  cc
                          ccc
                2  1   1    1
                      22   22
                          333
2  Or              A  BB  CCC
   this         1  a  b   c
   one                bb  cc
                          ccc
                2  1   1    1
                      22   22
                          333
END

# Print an array of arrays:

my $aa = formatTable
 ([[qw(A   B   C  )],
   [qw(AA  BB  CC )],
   [qw(AAA BBB CCC)],
   [qw(1   22  333)]],
   [qw (aa  bb  cc)]);

ok $aa eq <<END;
   aa   bb   cc
1  A    B    C
2  AA   BB   CC
3  AAA  BBB  CCC
4    1   22  333
END

# Print an array of hashes:

my $ah = formatTable
 ([{aa=> "A",   bb => "B",   cc => "C" },
   {aa=> "AA",  bb => "BB",  cc => "CC" },
   {aa=> "AAA", bb => "BBB", cc => "CCC" },
   {aa=> 1,     bb => 22,    cc => 333 }]);

ok $ah eq <<END;
   aa   bb   cc
1  A    B    C
2  AA   BB   CC
3  AAA  BBB  CCC
4    1   22  333
END

# Print a hash of arrays:

my $ha = formatTable
 ({""     => ["aa",  "bb",  "cc"],
   "1"    => ["A",   "B",   "C"],
   "22"   => ["AA",  "BB",  "CC"],
   "333"  => ["AAA", "BBB", "CCC"],
   "4444" => [1,      22,    333]},
   [qw(Key A B C)]
   );

ok $ha eq <<END;
Key   A    B    C
      aa   bb   cc
   1  A    B    C
  22  AA   BB   CC
 333  AAA  BBB  CCC
4444    1   22  333
END

# Print a hash of hashes:

my $hh = formatTable
 ({a    => {aa=>"A",   bb=>"B",   cc=>"C" },
   aa   => {aa=>"AA",  bb=>"BB",  cc=>"CC" },
   aaa  => {aa=>"AAA", bb=>"BBB", cc=>"CCC" },
   aaaa => {aa=>1,     bb=>22,    cc=>333 }});

ok $hh eq <<END;
      aa   bb   cc
a     A    B    C
aa    AA   BB   CC
aaa   AAA  BBB  CCC
aaaa    1   22  333
END

# Print an array of scalars:

my $a = formatTable(["a", "bb", "ccc", 4], [q(#), q(Col)]);

ok $a eq <<END;
#  Col
0  a
1  bb
2  ccc
3    4
END

# Print a hash of scalars:

my $h = formatTable({aa=>"AAAA", bb=>"BBBB", cc=>"333"}, [qw(Key Title)]);

ok $h eq <<END;
Key  Title
aa   AAAA
bb   BBBB
cc     333
END

Description

Write data in tabular text format.

Version q(20181018).

The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.

Immediately useful methods

These methods are the ones most likely to be of immediate use to anyone using this module for the first time:

clearFolder

Remove all the files and folders under and including the specified folder as long as the number of files to be removed is less than the specified limit. Sometimes the folder can be emptied but not removed - perhaps because it a link, in this case a message is produced unless suppressed by the optional $nomsg parameter.

dateTimeStamp

Year-monthNumber-day at hours:minute:seconds

filePathExt

Create a file name from an array of file name components the last of which is an extension. Identical to fpe.

Remove path and extension from file name.

formatTable

Format various data structures as a table. Optionally create a report from the table using the following optional report options:

file=>$file the name of a file to write the report to.

head=>$head a header line in which DDDD will be replaced with the data and time and NNNN will be replaced with the number of rows in the table.

zero=>$zero if true the report will be written to the specified file even if empty.

Parameters:

genHash

Return a $blessed hash with the specified $attributes accessible via lvalue method calls. updateDocumentation will generate documentation at "Hash Definitions" for the hash defined by the call to genHash if the call is laid out as in the example below.

newProcessStarter

Create a new process starter with which to start parallel processes up to a specified $maximumNumberOfProcesses maximum number of parallel processes at a time, wait for all the started processes to finish and then optionally retrieve their saved results as an array from the folder named by $transferArea.

readFile

Read a file containing unicode in utf8.

searchDirectoryTreesForMatchingFiles

Search the specified directory trees for the files (not folders) that match the specified extensions. The argument list should include at least one path name to be useful. If no file extension is supplied then all the files below the specified paths are returned.

sumAbsAndRel

Combine zero or more absolute and relative file names

writeFile

Write a unicode utf8 string to a new file that does not already exist after creating a path to the file if necessary and return the name of the file on success else confess if a problem occurred or the file does already exist.

xxx

Execute a shell command optionally checking its response. The command to execute is specified as one or more strings which are joined together after removing any new lines. Optionally the last string can be a regular expression that is used to test any non blank output generated by the execution of the command: if the regular expression fails the command and the command output are printed, else it is suppressed as being uninteresting. If such a regular expression is not supplied then the command and its non blank output lines are always printed.

Time stamps

Date and timestamps as used in logs of long running commands.

dateTimeStamp()

Year-monthNumber-day at hours:minute:seconds

Example:

ok ð�—±ð�—®ð�˜�ð�—²ð�—§ð�—¶ð�—ºð�—²ð�—¦ð�˜�ð�—®ð�—ºð�—½     =~ m(\A\d{4}-\d\d-\d\d at \d\d:\d\d:\d\d\Z);

dateTimeStampName()

Date time stamp without white space.

Example:

ok ð�—±ð�—®ð�˜�ð�—²ð�—§ð�—¶ð�—ºð�—²ð�—¦ð�˜�ð�—®ð�—ºð�—½ð�—¡ð�—®ð�—ºð�—² =~ m(\A_on_\d{4}_\d\d_\d\d_at_\d\d_\d\d_\d\d\Z);

dateStamp()

Year-monthName-day

Example:

ok ð�—±ð�—®ð�˜�ð�—²ð�—¦ð�˜�ð�—®ð�—ºð�—½         =~ m(\A\d{4}-\w{3}-\d\d\Z);

versionCode()

YYYYmmdd-HHMMSS

Example:

ok ð�˜ƒð�—²ð�—¿ð�˜€ð�—¶ð�—¼ð�—»ð�—–ð�—¼ð�—±ð�—²       =~ m(\A\d{8}-\d{6}\Z);

versionCodeDashed()

YYYY-mm-dd-HH:MM:SS

Example:

ok ð�˜ƒð�—²ð�—¿ð�˜€ð�—¶ð�—¼ð�—»ð�—–ð�—¼ð�—±ð�—²ð�——ð�—®ð�˜€ð�—µð�—²ð�—± =~ m(\A\d{4}-\d\d-\d\d-\d\d:\d\d:\d\d\Z);

timeStamp()

hours:minute:seconds

Example:

ok ð�˜�ð�—¶ð�—ºð�—²ð�—¦ð�˜�ð�—®ð�—ºð�—½         =~ m(\A\d\d:\d\d:\d\d\Z);

microSecondsSinceEpoch()

Micro seconds since unix epoch.

Example:

ok ð�—ºð�—¶ð�—°ð�—¿ð�—¼ð�—¦ð�—²ð�—°ð�—¼ð�—»ð�—±ð�˜€ð�—¦ð�—¶ð�—»ð�—°ð�—²ð�—˜ð�—½ð�—¼ð�—°ð�—µ > 47*365*24*60*60*1e6;

Command execution

Various ways of processing commands.

xxx(@)

   Parameter  Description
1  @cmd       Command to execute followed by an optional regular expression to test the results

Example:

{ok ð�˜…ð�˜…ð�˜…("echo aaa")       =~ /aaa/;

yyy($)

Execute a block of shell commands line by line after removing comments - stop if there is a non zero return code from any command.

   Parameter  Description
1  $cmd       Commands to execute separated by new lines

Example:

  ok !ð�˜†ð�˜†ð�˜† <<END;
echo aaa
echo bbb
END

zzz($$$$)

Execute lines of commands after replacing new lines with && then check that the pipeline execution results in a return code of zero and that the execution results match the optional regular expression if one has been supplied; confess() to an error if either check fails.

   Parameter    Description
1  $cmd         Commands to execute - one per line with no trailing &&
2  $success     Optional regular expression to check for acceptable results
3  $returnCode  Optional regular expression to check the acceptable return codes
4  $message     Message of explanation if any of the checks fail

Example:

ok ð�˜‡ð�˜‡ð�˜‡(<<END, qr(aaa\s*bbb)s);
echo aaa
echo bbb
END

parseCommandLineArguments(&$$)

Classify the specified array of words referred to by $args into positional and keyword parameters, call the specified sub with a reference to an array of positional parameters followed by a reference to a hash of keywords and their values then return the value returned by this sub. The keywords names will be validated if $valid is either a reference to an array of valid keywords names or a hash of valid keyword names => textual descriptions. Confess with a table of valid keywords definitions if the $valid keywords are specified and an invalid one is presented.

   Parameter  Description
1  $sub       Sub to call
2  $args      List of arguments to parse
3  $valid     Optional list of valid parameters else all parameters will be accepted

Example:

my $r = ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—–ð�—¼ð�—ºð�—ºð�—®ð�—»ð�—±ð�—Ÿð�—¶ð�—»ð�—²ð�—”ð�—¿ð�—´ð�˜‚ð�—ºð�—²ð�—»ð�˜�ð�˜€ {[@_]}

 [qw( aaa bbb -c --dd --eee=EEEE -f=F), q(--gg=g g), q(--hh=h h)];

is_deeply $r,

  [["aaa", "bbb"],

   {c=>undef, dd=>undef, eee=>"EEEE", f=>"F", gg=>"g g", hh=>"h h"},

  ];

call(&@)

Call the specified sub in a separate process, wait for it to complete, copy back the named our variables, free the memory used.

   Parameter  Description
1  $sub       Sub to call
2  @our       Our variable names with preceding sigils to copy back

Example:

Ë¢{our $a = q(1);
  our @a = qw(1);
  our %a = (a=>1);
  our $b = q(1);
  for(2..4) {
    ð�—°ð�—®ð�—¹ð�—¹ {$a = $_  x 1000; $a[0] = $_; $a{a} = $_; $b = 2;} qw($a @a %a);
    ok $a    == $_ x 1000;
    ok $a[0] == $_;
    ok $a{a} == $_;
    ok $b    == 1;
   }
 };

Files and paths

Operations on files and paths.

Statistics

Information about each file.

fileSize($)

Get the size of a file.

   Parameter  Description
1  $file      File name

Example:

my $f = writeFile("zzz.data", "aaa");

ok ð�—³ð�—¶ð�—¹ð�—²ð�—¦ð�—¶ð�˜‡ð�—²($f) == 3;

fileModTime($)

Get the modified time of a file in seconds since the epoch.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—¶ð�—¹ð�—²ð�— ð�—¼ð�—±ð�—§ð�—¶ð�—ºð�—²($0) =~ m(\A\d+\Z)s;

fileOutOfDate(&$@)

Calls the specified sub once for each source file that is missing, then calls the sub for the target if there were any missing files or if the target is older than any of the non missing source files or if the target does not exist. The file name is passed to the sub each time in $_. Returns the files to be remade in the order they should be made.

   Parameter  Description
1  $make      Make with this sub
2  $target    Target file
3  @source    Source files

Example:

if (0) {
  my @Files = qw(a b c);
  my @files = (@Files, qw(d));
  writeFile($_, $_), sleep 1 for @Files;

  my $a = '';
  my @a = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {$a .= $_} q(a), @files;
  ok $a eq 'da';
  is_deeply [@a], [qw(d a)];

  my $b = '';
  my @b = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {$b .= $_} q(b), @files;
  ok $b eq 'db';
  is_deeply [@b], [qw(d b)];

  my $c = '';
  my @c = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {$c .= $_} q(c), @files;
  ok $c eq 'dc';
  is_deeply [@c], [qw(d c)];

  my $d = '';
  my @d = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {$d .= $_} q(d), @files;
  ok $d eq 'd';
  is_deeply [@d], [qw(d)];

  my @A = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {} q(a), @Files;
  my @B = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {} q(b), @Files;
  my @C = ð�—³ð�—¶ð�—¹ð�—²ð�—¢ð�˜‚ð�˜�ð�—¢ð�—³ð�——ð�—®ð�˜�ð�—² {} q(c), @Files;
  is_deeply [@A], [qw(a)];
  is_deeply [@B], [qw(b)];
  is_deeply [@C], [];
  unlink for @Files;
 }

firstFileThatExists(@)

Returns the name of the first file that exists or undef if none of the named files exist.

   Parameter  Description
1  @files     Files to check

Example:

my $d = temporaryFolder;

ok $d eq ð�—³ð�—¶ð�—¿ð�˜€ð�˜�ð�—™ð�—¶ð�—¹ð�—²ð�—§ð�—µð�—®ð�˜�ð�—˜ð�˜…ð�—¶ð�˜€ð�˜�ð�˜€("$d/$d", $d);

Components

File names and components.

Fusion

Create file names from file name components.

filePath(@)

Create a file name from an array of file name components. If all the components are blank then a blank file name is returned. Identical to fpf.

   Parameter  Description
1  @file      File name components

Example:

if (1) {
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µ   (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok filePathDir(qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok filePathDir('', qw(aaa))              eq "aaa/";
  ok filePathDir('')                       eq "";
  ok filePathExt(qw(aaa xxx))              eq "aaa.xxx";
  ok filePathExt(qw(aaa bbb xxx))          eq "aaa/bbb.xxx";

  ok fpd        (qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok fpf        (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok fpe        (qw(aaa bbb xxx))          eq "aaa/bbb.xxx";
 }

fpf is a synonym for filePath.

filePathDir(@)

Create a directory name from an array of file name components. If all the components are blank then a blank file name is returned. Identical to fpd.

   Parameter  Description
1  @file      Directory name components

Example:

if (1) {
  ok filePath   (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µð�——ð�—¶ð�—¿(qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µð�——ð�—¶ð�—¿('', qw(aaa))              eq "aaa/";
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µð�——ð�—¶ð�—¿('')                       eq "";
  ok filePathExt(qw(aaa xxx))              eq "aaa.xxx";
  ok filePathExt(qw(aaa bbb xxx))          eq "aaa/bbb.xxx";

  ok fpd        (qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok fpf        (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok fpe        (qw(aaa bbb xxx))          eq "aaa/bbb.xxx";
 }

fpd is a synonym for filePathDir.

filePathExt(@)

Create a file name from an array of file name components the last of which is an extension. Identical to fpe.

   Parameter  Description
1  @File      File name components and extension

Example:

if (1) {
  ok filePath   (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok filePathDir(qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok filePathDir('', qw(aaa))              eq "aaa/";
  ok filePathDir('')                       eq "";
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µð�—˜ð�˜…ð�˜�(qw(aaa xxx))              eq "aaa.xxx";
  ok ð�—³ð�—¶ð�—¹ð�—²ð�—£ð�—®ð�˜�ð�—µð�—˜ð�˜…ð�˜�(qw(aaa bbb xxx))          eq "aaa/bbb.xxx";

  ok fpd        (qw(/aaa bbb ccc ddd))     eq "/aaa/bbb/ccc/ddd/";
  ok fpf        (qw(/aaa bbb ccc ddd.eee)) eq "/aaa/bbb/ccc/ddd.eee";
  ok fpe        (qw(aaa bbb xxx))          eq "aaa/bbb.xxx";
 }

fpe is a synonym for filePathExt.

Fission

Get file name components from file names.

fp($)

Get path from file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—½ (q(a/b/c.d.e))  eq q(a/b/);

fpn($)

Remove extension from file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—½ð�—»(q(a/b/c.d.e))  eq q(a/b/c.d);

fn($)

Remove path and extension from file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—» (q(a/b/c.d.e))  eq q(c.d);

fne($)

Remove path from file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—»ð�—²(q(a/b/c.d.e))  eq q(c.d.e);

fe($)

Get extension of file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—³ð�—² (q(a/b/c.d.e))  eq q(e);

checkFile($)

Return the name of the specified file if it exists, else confess the maximum extent of the path that does exist.

   Parameter  Description
1  $file      File to check

Example:

my $d = filePath   (my @d = qw(a b c d));

my $f = filePathExt(qw(a b c d e x));

my $F = filePathExt(qw(a b c e d));

createEmptyFile($f);

ok ð�—°ð�—µð�—²ð�—°ð�—¸ð�—™ð�—¶ð�—¹ð�—²($d);

ok ð�—°ð�—µð�—²ð�—°ð�—¸ð�—™ð�—¶ð�—¹ð�—²($f);

quoteFile($)

Quote a file name.

   Parameter  Description
1  $file      File name

Example:

ok ð�—¾ð�˜‚ð�—¼ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²(fpe(qw(a "b" c))) eq q("a/\"b\".c");

removeFilePrefix($@)

Removes a file prefix from an array of files.

   Parameter  Description
1  $prefix    File prefix
2  @files     Array of file names

Example:

is_deeply [qw(a b)], [&ð�—¿ð�—²ð�—ºð�—¼ð�˜ƒð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—£ð�—¿ð�—²ð�—³ð�—¶ð�˜…(qw(a/ a/a a/b))];

is_deeply [qw(b)],   [&ð�—¿ð�—²ð�—ºð�—¼ð�˜ƒð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—£ð�—¿ð�—²ð�—³ð�—¶ð�˜…("a/", "a/b")];

swapFilePrefix($$$)

Swaps the start of a file name from a known name to a new one,

   Parameter  Description
1  $file      File name
2  $known     Existing prefix
3  $new       New prefix

Example:

ok ð�˜€ð�˜„ð�—®ð�—½ð�—™ð�—¶ð�—¹ð�—²ð�—£ð�—¿ð�—²ð�—³ð�—¶ð�˜…(q(/aaa/bbb.txt), q(/aaa/), q(/AAA/)) eq q(/AAA/bbb.txt);

titleToUniqueFileName($$$$)

Create a file name from a title that is unique within the set %uniqueNames.

   Parameter         Description
1  $uniqueFileNames  Unique file names hash {} which will be updated by this method
2  $title            Title
3  $suffix           File name suffix
4  $ext              File extension

Example:

Ë¢{my $f = {};
  ok q(a_p.txt)   eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));
  ok q(a_p_2.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));
  ok q(a_p_3.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));
  ok q(a_q.txt)   eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));
  ok q(a_q_5.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));
  ok q(a_q_6.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));
 };

  ok q(a_p.txt)   eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));

  ok q(a_p_2.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));

  ok q(a_p_3.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a p txt));

  ok q(a_q.txt)   eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));

  ok q(a_q_5.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));

  ok q(a_q_6.txt) eq &ð�˜�ð�—¶ð�˜�ð�—¹ð�—²ð�—§ð�—¼ð�—¨ð�—»ð�—¶ð�—¾ð�˜‚ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f, qw(a q txt));

Position

Position in the file system.

currentDirectory()

Get the current working directory.

Example:

ð�—°ð�˜‚ð�—¿ð�—¿ð�—²ð�—»ð�˜�ð�——ð�—¶ð�—¿ð�—²ð�—°ð�˜�ð�—¼ð�—¿ð�˜†;

currentDirectoryAbove()

The path to the folder above the current working folder.

Example:

ð�—°ð�˜‚ð�—¿ð�—¿ð�—²ð�—»ð�˜�ð�——ð�—¶ð�—¿ð�—²ð�—°ð�˜�ð�—¼ð�—¿ð�˜†ð�—”ð�—¯ð�—¼ð�˜ƒð�—²;

parseFileName($)

Parse a file name into (path, name, extension).

   Parameter  Description
1  $file      File name to parse

Example:

if (1)
 {is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "/home/phil/test.data"], ["/home/phil/", "test", "data"];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "/home/phil/test"],      ["/home/phil/", "test"];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "phil/test.data"],       ["phil/",       "test", "data"];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "phil/test"],            ["phil/",       "test"];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "test.data"],            [undef,         "test", "data"];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "phil/"],                [qw(phil/)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "/phil"],                [qw(/ phil)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "/"],                    [qw(/)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "/var/www/html/translations/"], [qw(/var/www/html/translations/)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "a.b/c.d.e"],            [qw(a.b/ c.d e)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "./a.b"],                [qw(./ a b)];
  is_deeply [ð�—½ð�—®ð�—¿ð�˜€ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—² "./../../a.b"],          [qw(./../../ a b)];
 }

fullFileName()

Full name of a file.

Example:

ð�—³ð�˜‚ð�—¹ð�—¹ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²(fpe(qw(a txt)));

absFromAbsPlusRel($$)

Create an absolute file from an absolute file and a relative file.

   Parameter  Description
1  $a         Absolute file name
2  $f         Relative file name

Example:

ok "/home/la/perl/aaa.pl"   eq ð�—®ð�—¯ð�˜€ð�—™ð�—¿ð�—¼ð�—ºð�—”ð�—¯ð�˜€ð�—£ð�—¹ð�˜‚ð�˜€ð�—¥ð�—²ð�—¹("/home/la/perl/bbb",      "aaa.pl");

ok "/home/la/perl/aaa.pl"   eq ð�—®ð�—¯ð�˜€ð�—™ð�—¿ð�—¼ð�—ºð�—”ð�—¯ð�˜€ð�—£ð�—¹ð�˜‚ð�˜€ð�—¥ð�—²ð�—¹("/home/il/perl/bbb.pl",   "../../la/perl/aaa.pl");

relFromAbsAgainstAbs($$)

Derive a relative file name for the first absolute file name relative to the second absolute file name.

   Parameter  Description
1  $f         Absolute file to be made relative
2  $a         Absolute file name to make relative to.

Example:

ok "bbb.pl"                 eq ð�—¿ð�—²ð�—¹ð�—™ð�—¿ð�—¼ð�—ºð�—”ð�—¯ð�˜€ð�—”ð�—´ð�—®ð�—¶ð�—»ð�˜€ð�˜�ð�—”ð�—¯ð�˜€("/home/la/perl/bbb.pl", "/home/la/perl/aaa.pl");

ok "../perl/bbb.pl"         eq ð�—¿ð�—²ð�—¹ð�—™ð�—¿ð�—¼ð�—ºð�—”ð�—¯ð�˜€ð�—”ð�—´ð�—®ð�—¶ð�—»ð�˜€ð�˜�ð�—”ð�—¯ð�˜€("/home/la/perl/bbb.pl", "/home/la/java/aaa.jv");

sumAbsAndRel(@)

Combine zero or more absolute and relative file names

   Parameter  Description
1  @f         Absolute and relative file names

Example:

ok "aaa/bbb/ccc/ddd.txt"    eq ð�˜€ð�˜‚ð�—ºð�—”ð�—¯ð�˜€ð�—”ð�—»ð�—±ð�—¥ð�—²ð�—¹(qw(aaa/AAA/ ../bbb/bbb/BBB/ ../../ccc/ddd.txt));

Temporary

Temporary files and folders

temporaryFile()

Create a temporary file that will automatically be unlinked during END processing.

Example:

my $f = ð�˜�ð�—²ð�—ºð�—½ð�—¼ð�—¿ð�—®ð�—¿ð�˜†ð�—™ð�—¶ð�—¹ð�—²;

temporaryFolder()

Create a temporary folder that will automatically be rmdired during END processing.

Example:

my $D = ð�˜�ð�—²ð�—ºð�—½ð�—¼ð�—¿ð�—®ð�—¿ð�˜†ð�—™ð�—¼ð�—¹ð�—±ð�—²ð�—¿;

temporaryDirectory is a synonym for temporaryFolder.

Find

Find files and folders below a folder.

findFiles($$)

Find all the files under a folder and optionally filter the selected files with a regular expression.

   Parameter  Description
1  $dir       Folder to start the search with
2  $filter    Optional regular expression to filter files

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c);

is_deeply [sort map {fne $_} ð�—³ð�—¶ð�—»ð�—±ð�—™ð�—¶ð�—¹ð�—²ð�˜€($d, qr(txt\Z))], [qw(a.txt b.txt c.txt)];

findDirs($$)

Find all the folders under a folder and optionally filter the selected folders with a regular expression.

   Parameter  Description
1  $dir       Folder to start the search with
2  $filter    Optional regular expression to filter files

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c);

is_deeply [ð�—³ð�—¶ð�—»ð�—±ð�——ð�—¶ð�—¿ð�˜€($D)], [$D, $d];

fileList($)

Files that match a given search pattern handed to bsd_glob.

   Parameter  Description
1  $pattern   Search pattern

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c);

is_deeply [sort map {fne $_} ð�—³ð�—¶ð�—¹ð�—²ð�—Ÿð�—¶ð�˜€ð�˜�("$d/*.txt")],

          ["a.txt", "b.txt", "c.txt"];

searchDirectoryTreesForMatchingFiles(@)

   Parameter              Description
1  @foldersandExtensions  Mixture of folder names and extensions

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c);

is_deeply [sort map {fne $_} ð�˜€ð�—²ð�—®ð�—¿ð�—°ð�—µð�——ð�—¶ð�—¿ð�—²ð�—°ð�˜�ð�—¼ð�—¿ð�˜†ð�—§ð�—¿ð�—²ð�—²ð�˜€ð�—™ð�—¼ð�—¿ð�— ð�—®ð�˜�ð�—°ð�—µð�—¶ð�—»ð�—´ð�—™ð�—¶ð�—¹ð�—²ð�˜€($d)],

          ["a.txt", "b.txt", "c.txt"];

matchPath($)

Given an absolute path find out how much of the path actually exists.

   Parameter  Description
1  $file      File name

Example:

my $d = filePath   (my @d = qw(a b c d));

ok ð�—ºð�—®ð�˜�ð�—°ð�—µð�—£ð�—®ð�˜�ð�—µ($d) eq $d;

findFileWithExtension($@)

Find the first extension from the specified extensions that produces a file that exists when appended to the specified file.

   Parameter  Description
1  $file      File name minus extensions
2  @ext       Possible extensions

Example:

my $f = createEmptyFile(fpe(my $d = temporaryFolder, qw(a jpg)));

my $F = ð�—³ð�—¶ð�—»ð�—±ð�—™ð�—¶ð�—¹ð�—²ð�—ªð�—¶ð�˜�ð�—µð�—˜ð�˜…ð�˜�ð�—²ð�—»ð�˜€ð�—¶ð�—¼ð�—»(fpf($d, q(a)), qw(txt data jpg));

ok $F eq "jpg";

clearFolder($$$)

   Parameter    Description
1  $folder      Folder
2  $limitCount  Maximum number of files to remove to limit damage
3  $noMsg       No message if the folder cannot be completely removed.

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c);

ð�—°ð�—¹ð�—²ð�—®ð�—¿ð�—™ð�—¼ð�—¹ð�—±ð�—²ð�—¿($D, 5);

ok !-e $_ for @f;

ok !-d $D;

Read and write files

Read and write strings from and to files creating paths as needed.

readFile($)

Read a file containing unicode in utf8.

   Parameter  Description
1  $file      Name of file to read

Example:

  my $f = writeFile(undef, "aaa");

  my $s = ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²($f);

  ok $s eq "aaa";

  appendFile($f, "bbb");

  my $S = ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²($f);

  ok $S eq "aaabbb";

if (1) {
  my $f =  writeFile(undef, q(aaaa));
  ok ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²($f) eq q(aaaa);
  eval{writeFile($f, q(bbbb))};
  ok $@ =~ m(\AFile already exists)s;
  ok ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²($f) eq q(aaaa);
  overWriteFile($f,  q(bbbb));
  ok ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²($f) eq q(bbbb);
  unlink $f;
 }

evalFile($)

Read a file containing unicode in utf8, evaluate it, confess to any errors and then return any result - an improvement on do which silently ignores any problems.

   Parameter  Description
1  $file      File to read

Example:

if (1) {
  my $f = dumpFile(undef, my $d = [qw(aaa bbb ccc)]);
  my $s = ð�—²ð�˜ƒð�—®ð�—¹ð�—™ð�—¶ð�—¹ð�—²($f);
  is_deeply $s, $d;
  unlink $f;
 }

evalGZipFile($)

Read a file containing compressed utf8, evaluate it, confess to any errors or return any result. This is much slower than using Storable but does use much smaller files, see also: dumpGZipFile.

   Parameter  Description
1  $file      File to read

Example:

if (1) {
  my $d = [1, 2, 3=>{a=>4, b=>5}];
  my $file = dumpGZipFile(q(zzz.zip), $d);
  ok -e $file;
  my $D = ð�—²ð�˜ƒð�—®ð�—¹ð�—šð�—ð�—¶ð�—½ð�—™ð�—¶ð�—¹ð�—²($file);
  is_deeply $d, $D;
  unlink $file;
 }

retrieveFile($)

Retrieve a file created via Storable. This is much faster than evalFile but the stored data is not easily modified.

   Parameter  Description
1  $file      File to read

Example:

if (1) {
  my $f = storeFile(undef, my $d = [qw(aaa bbb ccc)]);
  my $s = ð�—¿ð�—²ð�˜�ð�—¿ð�—¶ð�—²ð�˜ƒð�—²ð�—™ð�—¶ð�—¹ð�—²($f);
  is_deeply $s, $d;
  unlink $f;
 }

readBinaryFile($)

Read binary file - a file whose contents are not to be interpreted as unicode.

   Parameter  Description
1  $file      File to read

Example:

my $f = writeBinaryFile(undef, 0xff x 8);

my $s = ð�—¿ð�—²ð�—®ð�—±ð�—•ð�—¶ð�—»ð�—®ð�—¿ð�˜†ð�—™ð�—¶ð�—¹ð�—²($f);

ok $s eq 0xff x 8;

readGZipFile($)

Read the specified $file, containing compressed utf8, through gzip

   Parameter  Description
1  $file      File to read.

Example:

if (1) {
  my $s = 'ð��°'x1e3;
  my $file = writeGZipFile(q(zzz.zip), $s);
  ok -e $file;
  my $S = ð�—¿ð�—²ð�—®ð�—±ð�—šð�—ð�—¶ð�—½ð�—™ð�—¶ð�—¹ð�—²($file);
  ok $s eq $S;
  ok length($s) == length($S);
  unlink $file;
 }

makePath($)

Make the path for the specified file name or folder.

   Parameter  Description
1  $file      File

Example:

my $d = fpd(my $D = temporaryDirectory, qw(a));

my $f = fpe($d, qw(bbb txt));

ok !-d $d;

ð�—ºð�—®ð�—¸ð�—²ð�—£ð�—®ð�˜�ð�—µ($f);

ok -d $d;

overWriteFile($$)

Write a unicode utf8 string to a file after creating a path to the file if necessary and return the name of the file on success else confess. If the file already exists it is overwritten.

   Parameter  Description
1  $file      File to write to or B<undef> for a temporary file
2  $string    Unicode string to write

Example:

if (1) {
  my $f =  writeFile(undef, q(aaaa));
  ok readFile($f) eq q(aaaa);
  eval{writeFile($f, q(bbbb))};
  ok $@ =~ m(\AFile already exists)s;
  ok readFile($f) eq q(aaaa);
  ð�—¼ð�˜ƒð�—²ð�—¿ð�—ªð�—¿ð�—¶ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²($f,  q(bbbb));
  ok readFile($f) eq q(bbbb);
  unlink $f;
 }

owf is a synonym for overWriteFile.

writeFile($$)

   Parameter  Description
1  $file      New file to write to or B<undef> for a temporary file
2  $string    String to write

Example:

  my $f = ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²(undef, "aaa");

  my $s = readFile($f);

  ok $s eq "aaa";

  appendFile($f, "bbb");

  my $S = readFile($f);

  ok $S eq "aaabbb";

if (1) {
  my $f =  ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²(undef, q(aaaa));
  ok readFile($f) eq q(aaaa);
  eval{ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²($f, q(bbbb))};
  ok $@ =~ m(\AFile already exists)s;
  ok readFile($f) eq q(aaaa);
  overWriteFile($f,  q(bbbb));
  ok readFile($f) eq q(bbbb);
  unlink $f;
 }

dumpFile($$)

Dump a data structure to a file

   Parameter  Description
1  $file      File to write to or B<undef> for a temporary file
2  $struct    Address of data structure to write

Example:

if (1) {
  my $f = ð�—±ð�˜‚ð�—ºð�—½ð�—™ð�—¶ð�—¹ð�—²(undef, my $d = [qw(aaa bbb ccc)]);
  my $s = evalFile($f);
  is_deeply $s, $d;
  unlink $f;
 }

storeFile($$)

Store a data structure to a file via Storable. This is much faster than dumpFile but the stored results are not easily modified.

   Parameter  Description
1  $file      File to write to or B<undef> for a temporary file
2  $struct    Address of data structure to write

Example:

if (1) {
  my $f = ð�˜€ð�˜�ð�—¼ð�—¿ð�—²ð�—™ð�—¶ð�—¹ð�—²(undef, my $d = [qw(aaa bbb ccc)]);
  my $s = retrieveFile($f);
  is_deeply $s, $d;
  unlink $f;
 }

writeGZipFile($$)

Write a unicode utf8 string through gzip to a file.

   Parameter  Description
1  $file      File to write to
2  $string    String to write

Example:

if (1) {
  my $s = 'ð��°'x1e3;
  my $file = ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—šð�—ð�—¶ð�—½ð�—™ð�—¶ð�—¹ð�—²(q(zzz.zip), $s);
  ok -e $file;
  my $S = readGZipFile($file);
  ok $s eq $S;
  ok length($s) == length($S);
  unlink $file;
 }

dumpGZipFile($$)

Write a data structure through gzip to a file. This technique produces files that are a lot more compact files than those produced by Storable, but the execution time is much longer. See also: evalGZipFile.

   Parameter  Description
1  $file      File to write
2  $data      Reference to data

Example:

if (1) {
  my $d = [1, 2, 3=>{a=>4, b=>5}];
  my $file = ð�—±ð�˜‚ð�—ºð�—½ð�—šð�—ð�—¶ð�—½ð�—™ð�—¶ð�—¹ð�—²(q(zzz.zip), $d);
  ok -e $file;
  my $D = evalGZipFile($file);
  is_deeply $d, $D;
  unlink $file;
 }

writeFiles($$)

Write the values of a hash into files identified by the key of each value using overWriteFile

   Parameter  Description
1  $hash      Hash of key value pairs representing files and data
2  $folder    Optional folder to contain files else the current folder

Example:

if (1) {
  my $h =
   {"aaa/1.txt"=>"1111",
    "aaa/2.txt"=>"2222",
   };
  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
  ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—™ð�—¶ð�—¹ð�—²ð�˜€($h);
  my $a = readFiles(q(aaa));
  is_deeply $h, $a;
  copyFolder(q(aaa), q(bbb));
  my $b = readFiles(q(bbb));
  is_deeply [sort values %$a],[sort values %$b];

  copyFile(q(aaa/1.txt), q(aaa/2.txt));
  my $A = readFiles(q(aaa));
  is_deeply(values %$A);

  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
 }

readFiles($)

Read all the files in a folder into a hash

   Parameter  Description
1  $folder    Folder to read

Example:

if (1) {
  my $h =
   {"aaa/1.txt"=>"1111",
    "aaa/2.txt"=>"2222",
   };
  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
  writeFiles($h);
  my $a = ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²ð�˜€(q(aaa));
  is_deeply $h, $a;
  copyFolder(q(aaa), q(bbb));
  my $b = ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²ð�˜€(q(bbb));
  is_deeply [sort values %$a],[sort values %$b];

  copyFile(q(aaa/1.txt), q(aaa/2.txt));
  my $A = ð�—¿ð�—²ð�—®ð�—±ð�—™ð�—¶ð�—¹ð�—²ð�˜€(q(aaa));
  is_deeply(values %$A);

  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
 }

appendFile($$)

Append a unicode utf8 string to a file, possibly creating the file and the path to the file if necessary and return the name of the file on success else confess.

   Parameter  Description
1  $file      File to append to
2  $string    String to append

Example:

my $f = writeFile(undef, "aaa");

my $s = readFile($f);

ok $s eq "aaa";

ð�—®ð�—½ð�—½ð�—²ð�—»ð�—±ð�—™ð�—¶ð�—¹ð�—²($f, "bbb");

my $S = readFile($f);

ok $S eq "aaabbb";

writeBinaryFile($$)

Write a non unicode string to a file in after creating a path to the file if necessary and return the name of the file on success else confess.

   Parameter  Description
1  $file      File to write to or B<undef> for a temporary file
2  $string    Non unicode string to write

Example:

my $f = ð�˜„ð�—¿ð�—¶ð�˜�ð�—²ð�—•ð�—¶ð�—»ð�—®ð�—¿ð�˜†ð�—™ð�—¶ð�—¹ð�—²(undef, 0xff x 8);

my $s = readBinaryFile($f);

ok $s eq 0xff x 8;

createEmptyFile($)

Create an empty file - writeFile complains if no data is written to the file - and return the name of the file on success else confess.

   Parameter  Description
1  $file      File to create or B<undef> for a temporary file

Example:

my $D = temporaryFolder;

my $d = fpd($D, q(ddd));

my @f = map {ð�—°ð�—¿ð�—²ð�—®ð�˜�ð�—²ð�—˜ð�—ºð�—½ð�˜�ð�˜†ð�—™ð�—¶ð�—¹ð�—²(fpe($d, $_, qw(txt)))} qw(a b c);

is_deeply [sort map {fne $_} findFiles($d, qr(txt\Z))], [qw(a.txt b.txt c.txt)];

numberOfLinesInFile($)

The number of lines in a file

   Parameter  Description
1  $file      File

Example:

my $f = writeFile(undef, "a
b
");

ok ð�—»ð�˜‚ð�—ºð�—¯ð�—²ð�—¿ð�—¢ð�—³ð�—Ÿð�—¶ð�—»ð�—²ð�˜€ð�—œð�—»ð�—™ð�—¶ð�—¹ð�—²($f) == 2;

Copy

Copy files and folders

copyFile($$)

Copy a file

   Parameter  Description
1  $source    Source file
2  $target    Target file

Example:

if (1) {
  my $h =
   {"aaa/1.txt"=>"1111",
    "aaa/2.txt"=>"2222",
   };
  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
  writeFiles($h);
  my $a = readFiles(q(aaa));
  is_deeply $h, $a;
  copyFolder(q(aaa), q(bbb));
  my $b = readFiles(q(bbb));
  is_deeply [sort values %$a],[sort values %$b];

  ð�—°ð�—¼ð�—½ð�˜†ð�—™ð�—¶ð�—¹ð�—²(q(aaa/1.txt), q(aaa/2.txt));
  my $A = readFiles(q(aaa));
  is_deeply(values %$A);

  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
 }

copyFolder($$)

Copy a folder

   Parameter  Description
1  $source    Source file
2  $target    Target file

Example:

if (1) {
  my $h =
   {"aaa/1.txt"=>"1111",
    "aaa/2.txt"=>"2222",
   };
  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
  writeFiles($h);
  my $a = readFiles(q(aaa));
  is_deeply $h, $a;
  ð�—°ð�—¼ð�—½ð�˜†ð�—™ð�—¼ð�—¹ð�—±ð�—²ð�—¿(q(aaa), q(bbb));
  my $b = readFiles(q(bbb));
  is_deeply [sort values %$a],[sort values %$b];

  copyFile(q(aaa/1.txt), q(aaa/2.txt));
  my $A = readFiles(q(aaa));
  is_deeply(values %$A);

  clearFolder(q(aaa), 3);
  clearFolder(q(bbb), 3);
 }

Images

Image operations.

imageSize($)

Return (width, height) of an image obtained via Imagemagick.

   Parameter  Description
1  $image     File containing image

Example:

my ($width, $height) = ð�—¶ð�—ºð�—®ð�—´ð�—²ð�—¦ð�—¶ð�˜‡ð�—²(fpe(qw(a image jpg)));

convertImageToJpx($$$)

Convert an image to jpx format using Imagemagick.

   Parameter  Description
1  $source    Source file
2  $target    Target folder (as multiple files will be created)
3  $Size      Optional size of each tile - defaults to 256

Example:

ð�—°ð�—¼ð�—»ð�˜ƒð�—²ð�—¿ð�˜�ð�—œð�—ºð�—®ð�—´ð�—²ð�—§ð�—¼ð�—�ð�—½ð�˜…(fpe(qw(a image jpg)), fpe(qw(a image jpg)), 256);

convertDocxToFodt($$)

Convert a docx file to fodt using unoconv which must not be running elsewhere at the time. Unoconv can be installed via:

sudo apt install sharutils unoconv

Parameters:

   Parameter    Description
1  $inputFile   Input file
2  $outputFile  Output file

Example:

ð�—°ð�—¼ð�—»ð�˜ƒð�—²ð�—¿ð�˜�ð�——ð�—¼ð�—°ð�˜…ð�—§ð�—¼ð�—™ð�—¼ð�—±ð�˜�(fpe(qw(a docx)), fpe(qw(a fodt)));

cutOutImagesInFodtFile($$$)

Cut out the images embedded in a fodt file, perhaps produced via convertDocxToFodt, placing them in the specified folder and replacing them in the source file with:

<image href="$imageFile" outputclass="imageType">.

This conversion requires that you have both Imagemagick and unoconv installed on your system:

sudo apt install sharutils  imagemagick unoconv

Parameters:

   Parameter      Description
1  $inputFile     Input file
2  $outputFolder  Output folder for images
3  $imagePrefix   A prefix to be added to image file names

Example:

ð�—°ð�˜‚ð�˜�ð�—¢ð�˜‚ð�˜�ð�—œð�—ºð�—®ð�—´ð�—²ð�˜€ð�—œð�—»ð�—™ð�—¼ð�—±ð�˜�ð�—™ð�—¶ð�—¹ð�—²(fpe(qw(source fodt)), fpd(qw(images)), q(image));

Encoding and Decoding

Encode and decode using Json and Mime.

encodeJson($)

Encode Perl to Json.

   Parameter  Description
1  $string    Data to encode

Example:

my $A = ð�—²ð�—»ð�—°ð�—¼ð�—±ð�—²ð�—�ð�˜€ð�—¼ð�—»(my $a = {a=>1,b=>2, c=>[1..2]});

my $b = decodeJson($A);

is_deeply $a, $b;

decodeJson($)

Decode Perl from Json.

   Parameter  Description
1  $string    Data to decode

Example:

my $A = encodeJson(my $a = {a=>1,b=>2, c=>[1..2]});

my $b = ð�—±ð�—²ð�—°ð�—¼ð�—±ð�—²ð�—�ð�˜€ð�—¼ð�—»($A);

is_deeply $a, $b;

encodeBase64($)

Encode a string in base 64.

   Parameter  Description
1  $string    String to encode

Example:

my $A = ð�—²ð�—»ð�—°ð�—¼ð�—±ð�—²ð�—•ð�—®ð�˜€ð�—²ð�Ÿ²ð�Ÿ°(my $a = "Hello World" x 10);

my $b = decodeBase64($A);

ok $a eq $b;

decodeBase64($)

Decode a string in base 64.

   Parameter  Description
1  $string    String to decode

Example:

my $A = encodeBase64(my $a = "Hello World" x 10);

my $b = ð�—±ð�—²ð�—°ð�—¼ð�—±ð�—²ð�—•ð�—®ð�˜€ð�—²ð�Ÿ²ð�Ÿ°($A);

ok $a eq $b;

convertUnicodeToXml($)

Convert a string with unicode points that are not directly representable in ascii into string that replaces these points with their representation on Xml making the string usable in Xml documents.

   Parameter  Description
1  $s         String to convert

Example:

ok ð�—°ð�—¼ð�—»ð�˜ƒð�—²ð�—¿ð�˜�ð�—¨ð�—»ð�—¶ð�—°ð�—¼ð�—±ð�—²ð�—§ð�—¼ð�—«ð�—ºð�—¹('setenta e trÃªs') eq q(setenta e tr&#234;s);

Numbers

Numeric operations,

powerOfTwo($)

Test whether a number is a power of two, return the power if it is else undef.

   Parameter  Description
1  $n         Number to check

Example:

ok  ð�—½ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(1) == 0;

ok  ð�—½ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(2) == 1;

ok !ð�—½ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(3);

ok  ð�—½ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(4) == 2;

containingPowerOfTwo($)

Find log two of the lowest power of two greater than or equal to a number.

   Parameter  Description
1  $n         Number to check

Example:

ok  ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�—¶ð�—»ð�—´ð�—£ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(1) == 0;

ok  ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�—¶ð�—»ð�—´ð�—£ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(2) == 1;

ok  ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�—¶ð�—»ð�—´ð�—£ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(3) == 2;

ok  ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�—¶ð�—»ð�—´ð�—£ð�—¼ð�˜„ð�—²ð�—¿ð�—¢ð�—³ð�—§ð�˜„ð�—¼(4) == 2;

Sets

Set operations.

setIntersectionOfTwoArraysOfWords($$)

Intersection of two arrays of words.

   Parameter  Description
1  $a         Reference to first array of words
2  $b         Reference to second array of words

Example:

is_deeply [qw(a b c)],

  [ð�˜€ð�—²ð�˜�ð�—œð�—»ð�˜�ð�—²ð�—¿ð�˜€ð�—²ð�—°ð�˜�ð�—¶ð�—¼ð�—»ð�—¢ð�—³ð�—§ð�˜„ð�—¼ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�˜€ð�—¢ð�—³ð�—ªð�—¼ð�—¿ð�—±ð�˜€([qw(e f g a b c )], [qw(a A b B c C)])];

setUnionOfTwoArraysOfWords($$)

Union of two arrays of words.

   Parameter  Description
1  $a         Reference to first array of words
2  $b         Reference to second array of words

Example:

is_deeply [qw(a b c)],

  [ð�˜€ð�—²ð�˜�ð�—¨ð�—»ð�—¶ð�—¼ð�—»ð�—¢ð�—³ð�—§ð�˜„ð�—¼ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�˜€ð�—¢ð�—³ð�—ªð�—¼ð�—¿ð�—±ð�˜€([qw(a b c )], [qw(a b)])];

contains($@)

Returns the indices at which an item matches elements of the specified array. If the item is a regular expression then it is matched as one, else it is a number it is matched as a number, else as a string.

   Parameter  Description
1  $item      Item
2  @array     Array

Example:

is_deeply [1],       [ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�˜€(1,0..1)];

is_deeply [1,3],     [ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�˜€(1, qw(0 1 0 1 0 0))];

is_deeply [0, 5],    [ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�˜€('a', qw(a b c d e a b c d e))];

is_deeply [0, 1, 5], [ð�—°ð�—¼ð�—»ð�˜�ð�—®ð�—¶ð�—»ð�˜€(qr(a+), qw(a baa c d e aa b c d e))];

Minima and Maxima

Find the smallest and largest elements of arrays.

min(@)

Find the minimum number in a list.

   Parameter  Description
1  @n         Numbers

Example:

ok ð�—ºð�—¶ð�—»(1) == 1;

ok ð�—ºð�—¶ð�—»(5,4,2,3) == 2;

max(@)

Find the maximum number in a list.

   Parameter  Description
1  @n         Numbers

Example:

ok !ð�—ºð�—®ð�˜…;

ok ð�—ºð�—®ð�˜…(1) == 1;

ok ð�—ºð�—®ð�˜…(1,4,2,3) == 4;

Format

Format data structures as tables.

maximumLineLength($)

Find the longest line in a string

   Parameter  Description
1  $string    String of lines of text

Example:

ok 3 == ð�—ºð�—®ð�˜…ð�—¶ð�—ºð�˜‚ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�—Ÿð�—²ð�—»ð�—´ð�˜�ð�—µ(<<END);
a
bb
ccc
END

formatTableBasic($)

Tabularize an array of arrays of text.

   Parameter  Description
1  $data      Reference to an array of arrays of data to be formatted as a table.

Example:

  my $d = [[qw(a 1)], [qw(bb 22)], [qw(ccc 333)], [qw(dddd 4444)]];

  ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²ð�—•ð�—®ð�˜€ð�—¶ð�—°($d) eq <<END;
a        1
bb      22
ccc    333
dddd  4444
END

formatTable($$%)

Format various data structures as a table. Optionally create a report from the table using the following optional report options:

file=>$file the name of a file to write the report to.

head=>$head a header line in which DDDD will be replaced with the data and time and NNNN will be replaced with the number of rows in the table.

zero=>$zero if true the report will be written to the specified file even if empty.

Parameters:

   Parameter  Description
1  $data      Data to be formatted
2  $title     Optional reference to an array of titles
3  %options   Options

Example:

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²

 ([[qw(A    B    C    D   )],

   [qw(AA   BB   CC   DD  )],

   [qw(AAA  BBB  CCC  DDD )],

   [qw(AAAA BBBB CCCC DDDD)],

   [qw(1    22   333  4444)]], [qw(aa bb cc)]) eq <<END;
   aa    bb    cc
1  A     B     C     D
2  AA    BB    CC    DD
3  AAA   BBB   CCC   DDD
4  AAAA  BBBB  CCCC  DDDD
5     1    22   333  4444
END

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²

 ([[qw(1     B   C)],

   [qw(22    BB  CC)],

   [qw(333   BBB CCC)],

   [qw(4444  22  333)]], [qw(aa bb cc)]) eq <<END;
   aa    bb   cc
1     1  B    C
2    22  BB   CC
3   333  BBB  CCC
4  4444   22  333
END

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²

 ([{aa=>'A',   bb=>'B',   cc=>'C'},

   {aa=>'AA',  bb=>'BB',  cc=>'CC'},

   {aa=>'AAA', bb=>'BBB', cc=>'CCC'},

   {aa=>'1',   bb=>'22',  cc=>'333'}

   ]) eq <<END;
   aa   bb   cc
1  A    B    C
2  AA   BB   CC
3  AAA  BBB  CCC
4    1   22  333
END

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²

 ({''=>[qw(aa bb cc)],

    1=>[qw(A B C)],

    22=>[qw(AA BB CC)],

    333=>[qw(AAA BBB CCC)],

    4444=>[qw(1 22 333)]}) eq <<END;
      aa   bb   cc
   1  A    B    C
  22  AA   BB   CC
 333  AAA  BBB  CCC
4444    1   22  333
END

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²

 ({1=>{aa=>'A', bb=>'B', cc=>'C'},

   22=>{aa=>'AA', bb=>'BB', cc=>'CC'},

   333=>{aa=>'AAA', bb=>'BBB', cc=>'CCC'},

   4444=>{aa=>'1', bb=>'22', cc=>'333'}}) eq <<END;
      aa   bb   cc
   1  A    B    C
  22  AA   BB   CC
 333  AAA  BBB  CCC
4444    1   22  333
END

ok ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²({aa=>'A', bb=>'B', cc=>'C'}, [qw(aaaa bbbb)]) eq <<END;
aaaa  bbbb
aa    A
bb    B
cc    C
END

if (1) {
  my $file = fpe(qw(report txt));                                               # Create a report
  my $t = ð�—³ð�—¼ð�—¿ð�—ºð�—®ð�˜�ð�—§ð�—®ð�—¯ð�—¹ð�—²
   ([["a",undef], [undef, "b0ac"]],                                           # Data - please replace 0a with a new line
    [undef, "BC"],                                                              # Column titles
    file=>$file,                                                                # Output file
    head=><<END);                                                               # Header
Sample report.

Table has NNNN rows.
END
  ok -e $file;
  ok readFile($file) eq $t;
  unlink $file;
  ok $t eq <<END;
Sample report.

Table has 2 rows.


This file: report.txt

      BC
1  a
2     b
      c
END
 }

keyCount($$)

Count keys down to the specified level.

   Parameter  Description
1  $maxDepth  Maximum depth to count to
2  $ref       Reference to an array or a hash

Example:

my $a = [[1..3],       {map{$_=>1} 1..3}];

my $h = {a=>[1..3], b=>{map{$_=>1} 1..3}};

ok ð�—¸ð�—²ð�˜†ð�—–ð�—¼ð�˜‚ð�—»ð�˜�(2, $a) == 6;

ok ð�—¸ð�—²ð�˜†ð�—–ð�—¼ð�˜‚ð�—»ð�˜�(2, $h) == 6;

Lines

Load data structures from lines.

loadArrayFromLines($)

Load an array from lines of text in a string.

   Parameter  Description
1  $string    The string of lines from which to create an array

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
a a
b b
END

  is_deeply $s, [q(a a), q(b b)];

  ok formatTable($s) eq <<END;
0  a a
1  b b
END

loadHashFromLines($)

Load a hash: first word of each line is the key and the rest is the value.

   Parameter  Description
1  $string    The string of lines from which to create a hash

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
a 10 11 12
b 20 21 22
END

  is_deeply $s, {a => q(10 11 12), b =>q(20 21 22)};

  ok formatTable($s) eq <<END;
a  10 11 12
b  20 21 22
END

loadArrayArrayFromLines($)

Load an array of arrays from lines of text: each line is an array of words.

   Parameter  Description
1  $string    The string of lines from which to create an array of arrays

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
A B C
AA BB CC
END

  is_deeply $s, [[qw(A B C)], [qw(AA BB CC)]];

  ok formatTable($s) eq <<END;
1  A   B   C
2  AA  BB  CC
END

loadHashArrayFromLines($)

Load a hash of arrays from lines of text: the first word of each line is the key, the remaining words are the array contents.

   Parameter  Description
1  $string    The string of lines from which to create a hash of arrays

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
a A B C
b AA BB CC
END

  is_deeply $s, {a =>[qw(A B C)], b => [qw(AA BB CC)] };

  ok formatTable($s) eq <<END;
a  A   B   C
b  AA  BB  CC
END

loadArrayHashFromLines($)

Load an array of hashes from lines of text: each line is an hash of words.

   Parameter  Description
1  $string    The string of lines from which to create an array of arrays

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�—›ð�—®ð�˜€ð�—µð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
A 1 B 2
AA 11 BB 22
END

  is_deeply $s, [{A=>1, B=>2}, {AA=>11, BB=>22}];

  ok formatTable($s) eq <<END;
   A  AA  B  BB
1  1      2
2     11     22
END

loadHashHashFromLines($)

Load a hash of hashes from lines of text: the first word of each line is the key, the remaining words are the sub hash contents.

   Parameter  Description
1  $string    The string of lines from which to create a hash of arrays

Example:

  my $s = ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µð�—›ð�—®ð�˜€ð�—µð�—™ð�—¿ð�—¼ð�—ºð�—Ÿð�—¶ð�—»ð�—²ð�˜€ <<END;
a A 1 B 2
b AA 11 BB 22
END

  is_deeply $s, {a=>{A=>1, B=>2}, b=>{AA=>11, BB=>22}};

  ok formatTable($s) eq <<END;
   A  AA  B  BB
a  1      2
b     11     22
END

checkKeys($$)

Check the keys in a hash.

   Parameter   Description
1  $test       The hash to test
2  $permitted  A hash of the permitted keys and their meanings

Example:

eval q{ð�—°ð�—µð�—²ð�—°ð�—¸ð�—žð�—²ð�˜†ð�˜€({a=>1, b=>2, d=>3}, {a=>1, b=>2, c=>3})};

ok nws($@) =~ m(\AInvalid options chosen: d Permitted.+?: a 1 b 2 c 3);

LVALUE methods

Replace $a->{value} = $b with $a->value = $b which reduces the amount of typing required, is easier to read and provides a hard check that {value} is spelled correctly.

genLValueScalarMethods(@)

Generate lvalue scalar methods in the current package, A method whose value has not yet been set will return a new scalar with value undef. Suffixing X to the scalar name will confess if a value has not been set.

   Parameter  Description
1  @names     List of method names

Example:

package Scalars;

my $a = bless{};

Data::Table::Text::ð�—´ð�—²ð�—»ð�—Ÿð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�—¦ð�—°ð�—®ð�—¹ð�—®ð�—¿ð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€(qw(aa bb cc));

$a->aa = 'aa';

Test::More::ok  $a->aa eq 'aa';

Test::More::ok !$a->bb;

Test::More::ok  $a->bbX eq q();

$a->aa = undef;

Test::More::ok !$a->aa;

addLValueScalarMethods(@)

Generate lvalue scalar methods in the current package if they do not already exist. A method whose value has not yet been set will return a new scalar with value undef. Suffixing X to the scalar name will confess if a value has not been set.

   Parameter  Description
1  @names     List of method names

Example:

my $class = "Data::Table::Text::Test";

my $a = bless{}, $class;

ð�—®ð�—±ð�—±ð�—Ÿð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�—¦ð�—°ð�—®ð�—¹ð�—®ð�—¿ð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€(qq(${class}::$_)) for qw(aa bb aa bb);

$a->aa = 'aa';

ok  $a->aa eq 'aa';

ok !$a->bb;

ok  $a->bbX eq q();

$a->aa = undef;

ok !$a->aa;

genLValueScalarMethodsWithDefaultValues(@)

Generate lvalue scalar methods with default values in the current package. A reference to a method whose value has not yet been set will return a scalar whose value is the name of the method.

   Parameter  Description
1  @names     List of method names

Example:

package ScalarsWithDefaults;

my $a = bless{};

Data::Table::Text::ð�—´ð�—²ð�—»ð�—Ÿð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�—¦ð�—°ð�—®ð�—¹ð�—®ð�—¿ð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€ð�—ªð�—¶ð�˜�ð�—µð�——ð�—²ð�—³ð�—®ð�˜‚ð�—¹ð�˜�ð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�˜€(qw(aa bb cc));

Test::More::ok $a->aa eq 'aa';

genLValueArrayMethods(@)

Generate lvalue array methods in the current package. A reference to a method that has no yet been set will return a reference to an empty array.

   Parameter  Description
1  @names     List of method names

Example:

package Arrays;

my $a = bless{};

Data::Table::Text::ð�—´ð�—²ð�—»ð�—Ÿð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�—”ð�—¿ð�—¿ð�—®ð�˜†ð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€(qw(aa bb cc));

$a->aa->[1] = 'aa';

Test::More::ok $a->aa->[1] eq 'aa';

genLValueHashMethods(@)

Generate lvalue hash methods in the current package. A reference to a method that has no yet been set will return a reference to an empty hash.

   Parameter  Description
1  @names     Method names

Example:

package Hashes;

my $a = bless{};

Data::Table::Text::ð�—´ð�—²ð�—»ð�—Ÿð�—©ð�—®ð�—¹ð�˜‚ð�—²ð�—›ð�—®ð�˜€ð�—µð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€(qw(aa bb cc));

$a->aa->{a} = 'aa';

Test::More::ok $a->aa->{a} eq 'aa';

genHash($%)

   Parameter    Description
1  $bless       Package name
2  %attributes  Hash of attribute names and values

Example:

if (1) {
  my $o = ð�—´ð�—²ð�—»ð�—›ð�—®ð�˜€ð�—µ(q(TestHash),                                                  # Definition of a blessed hash.
      a=>q(aa),                                                                 # Definition of attribute aa.
      b=>q(bb),                                                                 # Definition of attribute bb.
     );
  ok $o->a eq q(aa);
  is_deeply $o, {a=>"aa", b=>"bb"};
  my $p = ð�—´ð�—²ð�—»ð�—›ð�—®ð�˜€ð�—µ(q(TestHash),
    c=>q(cc),                                                                   # Definition of attribute cc.
   );
  ok $p->c eq q(cc);
  ok $p->a =  q(aa);
  ok $p->a eq q(aa);
  is_deeply $p, {a=>"aa", c=>"cc"};

  loadHash($p, a=>11, b=>22);                                                   # Load the hash
  is_deeply $p, {a=>11, b=>22, c=>"cc"};

  my $r = eval {loadHash($p, d=>44)};                                           # Try to load the hash
  ok $@ =~ m(Cannot load attribute: d);
 }

loadHash($%)

Load the specified $hash generated with genHash with %attributes. Confess to any unknown attribute names.

   Parameter    Description
1  $hash        Hash
2  %attributes  Hash of attribute names and values to be loaded

Example:

if (1) {
  my $o = genHash(q(TestHash),                                                  # Definition of a blessed hash.
      a=>q(aa),                                                                 # Definition of attribute aa.
      b=>q(bb),                                                                 # Definition of attribute bb.
     );
  ok $o->a eq q(aa);
  is_deeply $o, {a=>"aa", b=>"bb"};
  my $p = genHash(q(TestHash),
    c=>q(cc),                                                                   # Definition of attribute cc.
   );
  ok $p->c eq q(cc);
  ok $p->a =  q(aa);
  ok $p->a eq q(aa);
  is_deeply $p, {a=>"aa", c=>"cc"};

  ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µ($p, a=>11, b=>22);                                                   # Load the hash
  is_deeply $p, {a=>11, b=>22, c=>"cc"};

  my $r = eval {ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µ($p, d=>44)};                                           # Try to load the hash
  ok $@ =~ m(Cannot load attribute: d);
 }

reloadHashes($)

Ensures that all the hashes within a tower of data structures have LValue methods to get and set their current keys.

   Parameter  Description
1  $d         Data structure

Example:

if (1)
 {my $a = bless [bless {aaa=>42}, "AAAA"], "BBBB";
  eval {$a->[0]->aaa};
  ok $@ =~ m(\ACan.t locate object method .aaa. via package .AAAA.);
  ð�—¿ð�—²ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µð�—²ð�˜€($a);
  ok $a->[0]->aaa == 42;
 }

if (1)
 {my $a = bless [bless {ccc=>42}, "CCCC"], "DDDD";
  eval {$a->[0]->ccc};
  ok $@ =~ m(\ACan.t locate object method .ccc. via package .CCCC.);
  ð�—¿ð�—²ð�—¹ð�—¼ð�—®ð�—±ð�—›ð�—®ð�˜€ð�—µð�—²ð�˜€($a);
  ok $a->[0]->ccc == 42;
 }

setPackageSearchOrder($@)

Set a package search order for methods requested in the current package via AUTOLOAD.

   Parameter  Description
1  $set       Package to set
2  @search    Package names in search order.

Example:

if (1)
 {if (1)
   {package AAAA;

    sub aaaa{q(AAAAaaaa)}
    sub bbbb{q(AAAAbbbb)}
    sub cccc{q(AAAAcccc)}
   }
  if (1)
   {package BBBB;

    sub aaaa{q(BBBBaaaa)}
    sub bbbb{q(BBBBbbbb)}
    sub dddd{q(BBBBdddd)}
   }
  if (1)
   {package CCCC;

    sub aaaa{q(CCCCaaaa)}
    sub dddd{q(CCCCdddd)}
    sub eeee{q(CCCCeeee)}
   }

  ð�˜€ð�—²ð�˜�ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²ð�—¦ð�—²ð�—®ð�—¿ð�—°ð�—µð�—¢ð�—¿ð�—±ð�—²ð�—¿(__PACKAGE__, qw(CCCC BBBB AAAA));

  ok &aaaa eq q(CCCCaaaa);
  ok &bbbb eq q(BBBBbbbb);
  ok &cccc eq q(AAAAcccc);

  ok &aaaa eq q(CCCCaaaa);
  ok &bbbb eq q(BBBBbbbb);
  ok &cccc eq q(AAAAcccc);

  ok &dddd eq q(CCCCdddd);
  ok &eeee eq q(CCCCeeee);

  ð�˜€ð�—²ð�˜�ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²ð�—¦ð�—²ð�—®ð�—¿ð�—°ð�—µð�—¢ð�—¿ð�—±ð�—²ð�—¿(__PACKAGE__, qw(AAAA BBBB CCCC));

  ok &aaaa eq q(AAAAaaaa);
  ok &bbbb eq q(AAAAbbbb);
  ok &cccc eq q(AAAAcccc);

  ok &aaaa eq q(AAAAaaaa);
  ok &bbbb eq q(AAAAbbbb);
  ok &cccc eq q(AAAAcccc);

  ok &dddd eq q(BBBBdddd);
  ok &eeee eq q(CCCCeeee);
 }

mergePackageMethods($$@)

Import each of the named @methods that exist in package $from from package $from to package $to if they do not already exist in package $to, otherwise export them from package $to back to package $from in order to merge the behavior of the $from and $to packages with respect to the named methods with duplicates resolved of favour of package $from.

   Parameter  Description
1  $from      Name of package from which to import methods
2  $to        Package into which to import the methods
3  @methods   List of methods to try importing.

Example:

if (1)
 {sub AAAA::Call {q(AAAA)}

  sub BBBB::Call {q(BBBB)}
  sub BBBB::call {q(bbbb)}

  if (1)
   {package BBBB;
    use Test::More;
    *ok = *Test::More::ok;
    ok Call eq q(BBBB);
    ok call eq q(bbbb);
    &Data::Table::Text::ð�—ºð�—²ð�—¿ð�—´ð�—²ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²ð�— ð�—²ð�˜�ð�—µð�—¼ð�—±ð�˜€(qw(AAAA BBBB Call call));
    ok Call eq q(AAAA);
    ok call eq q(bbbb);
    package AAAA;
    use Test::More;
    *ok = *Test::More::ok;
    ok  Call eq q(AAAA);
    ok &call eq q(bbbb);
   }
 }

assertPackageRefs($@)

Confirm that the specified references are to the specified package

   Parameter  Description
1  $package   Package
2  @refs      References

Example:

if (1) {
  eval q{ð�—®ð�˜€ð�˜€ð�—²ð�—¿ð�˜�ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²ð�—¥ð�—²ð�—³ð�˜€(q(bbb), bless {}, q(aaa))};
  ok $@ =~ m(\AWanted reference to bbb, but got aaa);
 }

assertRef(@)

Confirm that the specified references are to the package into which this routine has been exported.

   Parameter  Description
1  @refs      References

Example:

if (1) {
  eval q{ð�—®ð�˜€ð�˜€ð�—²ð�—¿ð�˜�ð�—¥ð�—²ð�—³(bless {}, q(aaa))};
  ok $@ =~ m(\AWanted reference to Data::Table::Text, but got aaa);
 }

Ë¢(&)

Immediately executed inline sub to allow a code block before if.

   Parameter  Description
1  $sub       Sub enclosed in {} without the word "sub"

Example:

ok Ë¢{1} == 1;

ok Ë¢{1};

Ë¢{my $s =
  Ë¢{if (1)
     {return q(aa) if 1;
      q(bb);
     }
   };

  ok $s eq q(aa);
 };

arrayToHash(@)

Create a hash from an array

   Parameter  Description
1  @array     Array

Example:

is_deeply ð�—®ð�—¿ð�—¿ð�—®ð�˜†ð�—§ð�—¼ð�—›ð�—®ð�˜€ð�—µ(qw(a b c)), {a=>1, b=>1, c=>1};

Strings

Actions on strings.

indentString($$)

Indent lines contained in a string or formatted table by the specified string.

   Parameter  Description
1  $string    The string of lines to indent
2  $indent    The indenting string

Example:

  my $t = [qw(aa bb cc)];

  my $d = [[qw(A B C)], [qw(AA BB CC)], [qw(AAA BBB CCC)],  [qw(1 22 333)]];

  ok $s eq <<END;
  1  A    B    C
  2  AA   BB   CC
  3  AAA  BBB  CCC
  4    1   22  333
END

isBlank($)

Test whether a string is blank.

   Parameter  Description
1  $string    String

Example:

 ok ð�—¶ð�˜€ð�—•ð�—¹ð�—®ð�—»ð�—¸("");

 ok ð�—¶ð�˜€ð�—•ð�—¹ð�—®ð�—»ð�—¸("
");

trim($)

Remove any white space from the front and end of a string.

   Parameter  Description
1  $string    String

Example:

ok ð�˜�ð�—¿ð�—¶ð�—º(" a b ") eq join ' ', qw(a b);

pad($$$)

Pad a string with blanks or the specified padding character to a multiple of a specified length.

   Parameter  Description
1  $string    String
2  $length    Tab width
3  $pad       Padding char

Example:

ok  ð�—½ð�—®ð�—±('abc  ', 2).'='       eq "abc =";

ok  ð�—½ð�—®ð�—±('abc  ', 3).'='       eq "abc=";

ok  ð�—½ð�—®ð�—±('abc  ', 4, q(.)).'=' eq "abc.=";

firstNChars($$)

First N characters of a string.

   Parameter  Description
1  $string    String
2  $length    Length

Example:

ok ð�—³ð�—¶ð�—¿ð�˜€ð�˜�ð�—¡ð�—–ð�—µð�—®ð�—¿ð�˜€(q(abc), 2) eq q(ab);

ok ð�—³ð�—¶ð�—¿ð�˜€ð�˜�ð�—¡ð�—–ð�—µð�—®ð�—¿ð�˜€(q(abc), 4) eq q(abc);

nws($$)

Normalize white space in a string to make comparisons easier. Leading and trailing white space is removed; blocks of white space in the interior are reduced to a single space. In effect: this puts everything on one long line with never more than one space at a time. Optionally a maximum length is applied to the normalized string.

   Parameter  Description
1  $string    String to normalize
2  $length    Maximum length of result

Example:

ok ð�—»ð�˜„ð�˜€(qq(a  b    c)) eq q(a b c);

stringsAreNotEqual($$)

Return the common start followed by the two non equal tails of two non equal strings or an empty list if the strings are equal.

   Parameter  Description
1  $a         First string
2  $b         Second string

Example:

if (1) {
  ok        !ð�˜€ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�˜€ð�—”ð�—¿ð�—²ð�—¡ð�—¼ð�˜�ð�—˜ð�—¾ð�˜‚ð�—®ð�—¹(q(abc), q(abc));
  ok         ð�˜€ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�˜€ð�—”ð�—¿ð�—²ð�—¡ð�—¼ð�˜�ð�—˜ð�—¾ð�˜‚ð�—®ð�—¹(q(abc), q(abd));
  is_deeply [ð�˜€ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�˜€ð�—”ð�—¿ð�—²ð�—¡ð�—¼ð�˜�ð�—˜ð�—¾ð�˜‚ð�—®ð�—¹(q(abc), q(abd))], [qw(ab c d)];
  is_deeply [ð�˜€ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�˜€ð�—”ð�—¿ð�—²ð�—¡ð�—¼ð�˜�ð�—˜ð�—¾ð�˜‚ð�—®ð�—¹(q(ab),  q(abd))], [q(ab), '', q(d)];
 }

javaPackage($)

Extract the package name from a java string or file.

   Parameter  Description
1  $java      Java file if it exists else the string of java

Example:

  overWriteFile($f, <<END);
// Test
package com.xyz;
END

  ok ð�—·ð�—®ð�˜ƒð�—®ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²($f)           eq "com.xyz";

javaPackageAsFileName($)

Extract the package name from a java string or file and convert it to a file name.

   Parameter  Description
1  $java      Java file if it exists else the string of java

Example:

  overWriteFile($f, <<END);
// Test
package com.xyz;
END

  ok ð�—·ð�—®ð�˜ƒð�—®ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²ð�—”ð�˜€ð�—™ð�—¶ð�—¹ð�—²ð�—¡ð�—®ð�—ºð�—²($f) eq "com/xyz";

perlPackage($)

Extract the package name from a perl string or file.

   Parameter  Description
1  $perl      Perl file if it exists else the string of perl

Example:

  overWriteFile($f, <<END);
package a::b;
END

  ok ð�—½ð�—²ð�—¿ð�—¹ð�—£ð�—®ð�—°ð�—¸ð�—®ð�—´ð�—²($f)           eq "a::b";

printQw(@)

Print an array of words in qw() format.

   Parameter  Description
1  @words     Array of words

Example:

ok ð�—½ð�—¿ð�—¶ð�—»ð�˜�ð�—¤ð�˜„(qw(a b c)) eq q(qw(a b c));

numberOfLinesInString($)

The number of lines in a string.

   Parameter  Description
1  $string    String

Example:

ok ð�—»ð�˜‚ð�—ºð�—¯ð�—²ð�—¿ð�—¢ð�—³ð�—Ÿð�—¶ð�—»ð�—²ð�˜€ð�—œð�—»ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´("a
b
") == 2;

Unicode

Translate ascii alphanumerics in strings to various Unicode blocks.

boldString($)

Convert alphanumerics in a string to bold.

   Parameter  Description
1  $string    String to convert

Example:

ok ð�—¯ð�—¼ð�—¹ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´(q(zZ)) eq q(ð�˜‡ð�—);

boldStringUndo($)

Undo alphanumerics in a string to bold.

   Parameter  Description
1  $string    String to convert

Example:

if (1)
 {my $n = 1234567890;
  ok ð�—¯ð�—¼ð�—¹ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�—¨ð�—»ð�—±ð�—¼            (boldString($n))             == $n;
  ok enclosedStringUndo        (enclosedString($n))         == $n;
  ok enclosedReversedStringUndo(enclosedReversedString($n)) == $n;
  ok superScriptStringUndo     (superScriptString($n))      == $n;
  ok subScriptStringUndo       (subScriptString($n))        == $n;
 }

enclosedString($)

Convert alphanumerics in a string to enclosed alphanumerics.

   Parameter  Description
1  $string    String to convert

Example:

ok ð�—²ð�—»ð�—°ð�—¹ð�—¼ð�˜€ð�—²ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´(q(hello world 1234)) eq q(â“—â“”â“›â“›â“ž â“¦â“žâ“¡â“›â““ â‘ â‘¡â‘¢â‘£);

enclosedStringUndo($)

Undo alphanumerics in a string to enclosed alphanumerics.

   Parameter  Description
1  $string    String to convert

Example:

if (1)
 {my $n = 1234567890;
  ok boldStringUndo            (boldString($n))             == $n;
  ok ð�—²ð�—»ð�—°ð�—¹ð�—¼ð�˜€ð�—²ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�—¨ð�—»ð�—±ð�—¼        (enclosedString($n))         == $n;
  ok enclosedReversedStringUndo(enclosedReversedString($n)) == $n;
  ok superScriptStringUndo     (superScriptString($n))      == $n;
  ok subScriptStringUndo       (subScriptString($n))        == $n;
 }

enclosedReversedString($)

Convert alphanumerics in a string to enclosed reversed alphanumerics.

   Parameter  Description
1  $string    String to convert

Example:

ok ð�—²ð�—»ð�—°ð�—¹ð�—¼ð�˜€ð�—²ð�—±ð�—¥ð�—²ð�˜ƒð�—²ð�—¿ð�˜€ð�—²ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´(q(hello world 1234)) eq q(ðŸ…—ðŸ…”ðŸ…›ðŸ…›ðŸ…ž ðŸ…¦ðŸ…žðŸ…¡ðŸ…›ðŸ…“ âžŠâž‹âžŒâž�);

enclosedReversedStringUndo($)

Undo alphanumerics in a string to enclosed reversed alphanumerics.

   Parameter  Description
1  $string    String to convert

Example:

if (1)
 {my $n = 1234567890;
  ok boldStringUndo            (boldString($n))             == $n;
  ok enclosedStringUndo        (enclosedString($n))         == $n;
  ok ð�—²ð�—»ð�—°ð�—¹ð�—¼ð�˜€ð�—²ð�—±ð�—¥ð�—²ð�˜ƒð�—²ð�—¿ð�˜€ð�—²ð�—±ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�—¨ð�—»ð�—±ð�—¼(enclosedReversedString($n)) == $n;
  ok superScriptStringUndo     (superScriptString($n))      == $n;
  ok subScriptStringUndo       (subScriptString($n))        == $n;
 }

superScriptString($)

Convert alphanumerics in a string to super scripts

   Parameter  Description
1  $string    String to convert

Example:

ok ð�˜€ð�˜‚ð�—½ð�—²ð�—¿ð�—¦ð�—°ð�—¿ð�—¶ð�—½ð�˜�ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´(1234567890) eq q(Â¹Â²Â³â�´â�µâ�¶â�·â�¸â�¹â�°);

superScriptStringUndo($)

Undo alphanumerics in a string to super scripts

   Parameter  Description
1  $string    String to convert

Example:

if (1)
 {my $n = 1234567890;
  ok boldStringUndo            (boldString($n))             == $n;
  ok enclosedStringUndo        (enclosedString($n))         == $n;
  ok enclosedReversedStringUndo(enclosedReversedString($n)) == $n;
  ok ð�˜€ð�˜‚ð�—½ð�—²ð�—¿ð�—¦ð�—°ð�—¿ð�—¶ð�—½ð�˜�ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�—¨ð�—»ð�—±ð�—¼     (superScriptString($n))      == $n;
  ok subScriptStringUndo       (subScriptString($n))        == $n;
 }

subScriptString($)

Convert alphanumerics in a string to sub scripts

   Parameter  Description
1  $string    String to convert

Example:

ok ð�˜€ð�˜‚ð�—¯ð�—¦ð�—°ð�—¿ð�—¶ð�—½ð�˜�ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´(1234567890)   eq q(â‚�â‚‚â‚ƒâ‚„â‚…â‚†â‚‡â‚ˆâ‚‰â‚€);

subScriptStringUndo($)

Undo alphanumerics in a string to sub scripts

   Parameter  Description
1  $string    String to convert

Example:

if (1)
 {my $n = 1234567890;
  ok boldStringUndo            (boldString($n))             == $n;
  ok enclosedStringUndo        (enclosedString($n))         == $n;
  ok enclosedReversedStringUndo(enclosedReversedString($n)) == $n;
  ok superScriptStringUndo     (superScriptString($n))      == $n;
  ok ð�˜€ð�˜‚ð�—¯ð�—¦ð�—°ð�—¿ð�—¶ð�—½ð�˜�ð�—¦ð�˜�ð�—¿ð�—¶ð�—»ð�—´ð�—¨ð�—»ð�—±ð�—¼       (subScriptString($n))        == $n;
 }

Cloud Cover

Useful for operating across the cloud.

makeDieConfess()

Force die to confess where the death occurred.

Example:

ð�—ºð�—®ð�—¸ð�—²ð�——ð�—¶ð�—²ð�—–ð�—¼ð�—»ð�—³ð�—²ð�˜€ð�˜€

ipAddressViaArp($)

Get the ip address of a server on the local network by hostname via arp

   Parameter  Description
1  $hostName  Host name

Example:

ð�—¶ð�—½ð�—”ð�—±ð�—±ð�—¿ð�—²ð�˜€ð�˜€ð�—©ð�—¶ð�—®ð�—”ð�—¿ð�—½(q(secarias));

saveCodeToS3($$$$)

Save source code files.

   Parameter       Description
1  $saveCodeEvery  Save every seconds
2  $zipFileName    Zip file name
3  $bucket         Bucket/key
4  $S3Parms        Additional S3 parameters like profile or region as a string

Example:

ð�˜€ð�—®ð�˜ƒð�—²ð�—–ð�—¼ð�—±ð�—²ð�—§ð�—¼ð�—¦ð�Ÿ¯(1200, q(projectName), q(bucket/folder), q(--only-show-errors));

addCertificate($)

Add a certificate to the current ssh session.

   Parameter  Description
1  $file      File containing certificate

Example:

ð�—®ð�—±ð�—±ð�—–ð�—²ð�—¿ð�˜�ð�—¶ð�—³ð�—¶ð�—°ð�—®ð�˜�ð�—²(fpf(qw(.ssh cert)));

hostName()

The name of the host we are running on.

Example:

ð�—µð�—¼ð�˜€ð�˜�ð�—¡ð�—®ð�—ºð�—²;

userId()

The userid we are currently running under.

Example:

ð�˜‚ð�˜€ð�—²ð�—¿ð�—œð�—±;

wwwEncode($)

Replace spaces in a string with %20 .

   Parameter  Description
1  $string    String

Example:

ok ð�˜„ð�˜„ð�˜„ð�—˜ð�—»ð�—°ð�—¼ð�—±ð�—²(q(a  b c)) eq q(a%20%20b%20c);

startProcess(&\%$)

Start new processes while the number of child processes recorded in %$pids is less than the specified $maximum. Use waitForAllStartedProcessesToFinish to wait for all these processes to finish.

   Parameter  Description
1  $sub       Sub to start
2  $pids      Hash in which to record the process ids
3  $maximum   Maximum number of processes to run at a time

Example:

if (0) {
  my %pids;
  Ë¢{ð�˜€ð�˜�ð�—®ð�—¿ð�˜�ð�—£ð�—¿ð�—¼ð�—°ð�—²ð�˜€ð�˜€ {} %pids, 1; ok 1 >= keys %pids} for 1..8;
  waitForAllStartedProcessesToFinish(%pids);
  ok !keys(%pids)
 }

waitForAllStartedProcessesToFinish(\%)

Wait until all the processes started by startProcess have finished.

   Parameter  Description
1  $pids      Hash of started process ids

Example:

if (0) {
  my %pids;
  Ë¢{startProcess {} %pids, 1; ok 1 >= keys %pids} for 1..8;
  ð�˜„ð�—®ð�—¶ð�˜�ð�—™ð�—¼ð�—¿ð�—”ð�—¹ð�—¹ð�—¦ð�˜�ð�—®ð�—¿ð�˜�ð�—²ð�—±ð�—£ð�—¿ð�—¼ð�—°ð�—²ð�˜€ð�˜€ð�—²ð�˜€ð�—§ð�—¼ð�—™ð�—¶ð�—»ð�—¶ð�˜€ð�—µ(%pids);
  ok !keys(%pids)
 }

newProcessStarter($$)

   Parameter                  Description
1  $maximumNumberOfProcesses  Maximum number of processes to start
2  $transferArea              Optional folder to be used to save and retrieve results.

Example:

if (!$windows)

Data::Table::Text::Starter::start($$)

Start a new process to run the specified $sub.

   Parameter  Description
1  $starter   Starter
2  $sub       Sub to be run.

Example:

if (!$windows)

Data::Table::Text::Starter::finish($)

Wait for all started processes to finish and return their results as an array.

   Parameter  Description
1  $starter   Starter

Example:

if (!$windows)

newServiceIncarnation($$)

Create a new service incarnation to record the start up of a new instance of a service and return the description as a Data::Exchange::Service Definition hash.

   Parameter  Description
1  $service   Service name
2  $file      Optional details file

Example:

if (1)
 {my $s = ð�—»ð�—²ð�˜„ð�—¦ð�—²ð�—¿ð�˜ƒð�—¶ð�—°ð�—²ð�—œð�—»ð�—°ð�—®ð�—¿ð�—»ð�—®ð�˜�ð�—¶ð�—¼ð�—»("aaa", q(bbb.txt));
  is_deeply $s->check, $s;
  my $t = ð�—»ð�—²ð�˜„ð�—¦ð�—²ð�—¿ð�˜ƒð�—¶ð�—°ð�—²ð�—œð�—»ð�—°ð�—®ð�—¿ð�—»ð�—®ð�˜�ð�—¶ð�—¼ð�—»("aaa", q(bbb.txt));
  is_deeply $t->check, $t;
  ok $t->start >= $s->start+1;
  ok !$s->check(1);
  unlink q(bbb.txt);
 }

Data::Exchange::Service::check($$)

Check that we are the current incarnation of the named service with details obtained from newServiceIncarnation. If the optional $continue flag has been set then return the service details if this is the current service incarnation else undef. Otherwise if the $continue flag is false confess unless this is the current service incarnation thus bringing the earlier version of this service to an abrupt end.

   Parameter  Description
1  $s         Current service details
2  $continue  Return result if B<$continue> is true else confess if the service has been replaced

Example:

if (1)
 {my $s = newServiceIncarnation("aaa", q(bbb.txt));
  is_deeply $s->check, $s;
  my $t = newServiceIncarnation("aaa", q(bbb.txt));
  is_deeply $t->check, $t;
  ok $t->start >= $s->start+1;
  ok !$s->check(1);
  unlink q(bbb.txt);
 }

Documentation

Extract, format and update documentation for a perl module.

htmlToc($@)

Generate a table of contents for some html.

   Parameter  Description
1  $replace   Sub-string within the html to be replaced with the toc
2  $html      String of html

Example:

ok nws(ð�—µð�˜�ð�—ºð�—¹ð�—§ð�—¼ð�—°("XXXX", <<END)), 'ð�—µð�˜�ð�—ºð�—¹ð�—§ð�—¼ð�—°'
<h1 id="1" otherprops="1">Chapter 1</h1>
  <h2 id="11" otherprops="11">Section 1</h1>
<h1 id="2" otherprops="2">Chapter 2</h1>
XXXX
END

  eq nws(<<END);
<h1 id="1" otherprops="1">Chapter 1</h1>
  <h2 id="11" otherprops="11">Section 1</h1>
<h1 id="2" otherprops="2">Chapter 2</h1>
<table cellspacing=10 border=0>
<tr><td>&nbsp;
<tr><td align=right>1<td>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#1">Chapter 1</a>
<tr><td align=right>2<td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#11">Section 1</a>
<tr><td>&nbsp;
<tr><td align=right>3<td>&nbsp;&nbsp;&nbsp;&nbsp;<a href="#2">Chapter 2</a>
</table>
END

updateDocumentation($)

Update documentation for a Perl module from the comments in its source code. Comments between the lines marked with:

#Dn title # description

and:

#D

where n is either 1, 2 or 3 indicating the heading level of the section and the # is in column 1.

Methods are formatted as:

sub name(signature)      #FLAGS comment describing method
 {my ($parameters) = @_; # comments for each parameter separated by commas.

FLAGS can be chosen from:

I: method of interest to new users
P: private method
r: optionally replaceable method
R: required replaceable method
S: static method
X: die rather than received a returned undef result

Other flags will be handed to the method extractDocumentationFlags(flags to process, method name) found in the file being documented, this method should return [the additional documentation for the method, the code to implement the flag].

Text following 'Example:' in the comment (if present) will be placed after the parameters list as an example. Lines containing comments consisting of '#T'.methodName will also be aggregated and displayed as examples for that method.

Lines formatted as:

BEGIN{*source=*target}

starting in column 1 will define a synonym for a method.

Lines formatted as:

#C emailAddress text

will be aggregated in the acknowledgments section at the end of the documentation.

The character sequence \n in the comment will be expanded to one new line, \m to two new lines and L<$_>,L<confess>,L<die>,L<eval>,L<lvalueMethod> to links to the perl documentation.

Search for '#D1': in https://metacpan.org/source/PRBRENAN/Data-Table-Text-20180810/lib/Data/Table/Text.pm to see more examples of such documentation in action - although it is quite difficult to see as it looks just like normal comments placed in the code.

Parameters:

   Parameter    Description
1  $perlModule  Optional file name with caller's file being the default

Example:

 {my $s = ð�˜‚ð�—½ð�—±ð�—®ð�˜�ð�—²ð�——ð�—¼ð�—°ð�˜‚ð�—ºð�—²ð�—»ð�˜�ð�—®ð�˜�ð�—¶ð�—¼ð�—»(<<'END' =~ s(#) (#)gsr =~ s(~) ()gsr);
package Sample::Module;

#D1 Samples                                                                      # Sample methods.

sub sample($@)                                                                  #R Documentation for the:  sample() method.  See also L<Data::Table::Text::sample2|/Data::Table::Text::sample2>. #Tsample
 {my ($node, @context) = @_;                                                    # Node, optional context
  1
 }

~BEGIN{*smpl=*sample}

sub Data::Table::Text::sample2(\&@)                                             #PS Documentation for the sample2() method.
 {my ($sub, @context) = @_;                                                     # Sub to call, context.
  1
 }

ok sample(undef, qw(a b c)) == 1;                                               #Tsample

if (1)                                                                          #Tsample
 {ok sample(q(a), qw(a b c))  == 2;
  ok sample(undef, qw(a b c)) == 1;
 }

ok sample(<<END2)) == 1;                                                        #Tsample
sample data
END2

  ok $s =~ m'=head2 sample28\$\@29';

Hash Definitions

Data::Exchange::Service Definition

Service details.

file - The file in which the service start details is being recorded.

service - The name of the service.

start - The time this service was started time plus a minor hack to simplify testing.

Data::Table::Text::Starter Definition

Process starter definition.

maximumNumberOfProcesses - The maximum number of processes to start in parallel at one time. If this limit is exceeded, the start of subsequent processes will be delayed until processes started earlier have finished.

transferArea - The name of the folder in which files transferring results from the child to the parent process will be stored.

TestHash Definition

Definition of a blessed hash.

a - Definition of attribute aa.

b - Definition of attribute bb.

Private Methods

denormalizeFolderName($)

Remove any trailing folder separator from a folder name component.

   Parameter  Description
1  $name      Name

renormalizeFolderName($)

Normalize a folder name component by adding a trailing separator.

   Parameter  Description
1  $name      Name

trackFiles($@)

Track the existence of files.

   Parameter  Description
1  $label     Label
2  @files     Files

printFullFileName()

Print a file name on a separate line with escaping so it can be used easily from the command line.

readUtf16File($)

Read a file containing unicode in utf-16 format.

   Parameter  Description
1  $file      Name of file to read

binModeAllUtf8()

Set STDOUT and STDERR to accept utf8 without complaint.

Example:

ð�—¯ð�—¶ð�—»ð�— ð�—¼ð�—±ð�—²ð�—”ð�—¹ð�—¹ð�—¨ð�˜�ð�—³ð�Ÿ´;

convertImageToJpx690($$$)

Convert an image to jpx format using versions of Imagemagick version 6.9.0 and above.

   Parameter  Description
1  $source    Source file
2  $target    Target folder (as multiple files will be created)
3  $Size      Optional size of each tile - defaults to 256

formatTableMultiLine($$)

Tabularize text that has new lines in it.

   Parameter   Description
1  $data       Reference to an array of arrays of data to be formatted as a table
2  $separator  Optional line separator to use instead of new line for each row.

formatTableAA($$)

Tabularize an array of arrays.

   Parameter  Description
1  $data      Data to be formatted
2  $title     Optional reference to an array of titles

formatTableHA($$)

Tabularize a hash of arrays.

   Parameter  Description
1  $data      Data to be formatted
2  $title     Optional titles

formatTableAH($)

Tabularize an array of hashes.

   Parameter  Description
1  $data      Data to be formatted

formatTableHH($)

Tabularize a hash of hashes.

   Parameter  Description
1  $data      Data to be formatted

formatTableA($$)

Tabularize an array.

   Parameter  Description
1  $data      Data to be formatted
2  $title     Optional title

formatTableH($$)

Tabularize a hash.

   Parameter  Description
1  $data      Data to be formatted
2  $title     Optional title

reloadHashes2($$)

Ensures that all the hashes within a tower of data structures have LValue methods to get and set their current keys.

   Parameter  Description
1  $d         Data structure
2  $progress  Progress

showHashes2($$$)

Create a map of all the keys within all the hashes within a tower of data structures.

   Parameter  Description
1  $d         Data structure
2  $keys      Keys found
3  $progress  Progress

showHashes($)

Create a map of all the keys within all the hashes within a tower of data structures.

   Parameter  Description
1  $d         Data structure

saveSourceToS3($$)

Save source code.

   Parameter               Description
1  $aws                    Aws target file and keywords
2  $saveIntervalInSeconds  Save internal

Data::Table::Text::Starter::waitOne($)

Wait for one process to finish and consolidate its results.

   Parameter  Description
1  $starter   Starter

extractTest($)

Remove example markers from test code.

   Parameter  Description
1  $string    String containing test line

docUserFlags($$$$)

Generate documentation for a method by calling the extractDocumentationFlags method in the package being documented, passing it the flags for a method and the name of the method. The called method should return the documentation to be inserted for the named method.

   Parameter    Description
1  $flags       Flags
2  $perlModule  File containing documentation
3  $package     Package containing documentation
4  $name        Name of method to be processed

updatePerlModuleDocumentation($)

Update the documentation in a perl file and show said documentation in a web browser.

   Parameter    Description
1  $perlModule  File containing the code of the perl module

Synonyms

fpd is a synonym for filePathDir - Create a directory name from an array of file name components.

fpe is a synonym for filePathExt - Create a file name from an array of file name components the last of which is an extension.

fpf is a synonym for filePath - Create a file name from an array of file name components.

owf is a synonym for overWriteFile - Write a unicode utf8 string to a file after creating a path to the file if necessary and return the name of the file on success else confess.

temporaryDirectory is a synonym for temporaryFolder - Create a temporary folder that will automatically be rmdired during END processing.

Index

1 absFromAbsPlusRel - Create an absolute file from an absolute file and a relative file.

2 addCertificate - Add a certificate to the current ssh session.

3 addLValueScalarMethods - Generate lvalue scalar methods in the current package if they do not already exist.

4 appendFile - Append a unicode utf8 string to a file, possibly creating the file and the path to the file if necessary and return the name of the file on success else confess.

5 arrayToHash - Create a hash from an array

6 assertPackageRefs - Confirm that the specified references are to the specified package

7 assertRef - Confirm that the specified references are to the package into which this routine has been exported.

8 binModeAllUtf8 - Set STDOUT and STDERR to accept utf8 without complaint.

9 boldString - Convert alphanumerics in a string to bold.

10 boldStringUndo - Undo alphanumerics in a string to bold.

11 call - Call the specified sub in a separate process, wait for it to complete, copy back the named our variables, free the memory used.

12 checkFile - Return the name of the specified file if it exists, else confess the maximum extent of the path that does exist.

13 checkKeys - Check the keys in a hash.

14 clearFolder - Remove all the files and folders under and including the specified folder as long as the number of files to be removed is less than the specified limit.

15 containingPowerOfTwo - Find log two of the lowest power of two greater than or equal to a number.

16 contains - Returns the indices at which an item matches elements of the specified array.

17 convertDocxToFodt - Convert a docx file to fodt using unoconv which must not be running elsewhere at the time.

18 convertImageToJpx - Convert an image to jpx format using Imagemagick.

19 convertImageToJpx690 - Convert an image to jpx format using versions of Imagemagick version 6.

20 convertUnicodeToXml - Convert a string with unicode points that are not directly representable in ascii into string that replaces these points with their representation on Xml making the string usable in Xml documents.

21 copyFile - Copy a file

22 copyFolder - Copy a folder

23 createEmptyFile - Create an empty file - writeFile complains if no data is written to the file - and return the name of the file on success else confess.

24 currentDirectory - Get the current working directory.

25 currentDirectoryAbove - The path to the folder above the current working folder.

26 cutOutImagesInFodtFile - Cut out the images embedded in a fodt file, perhaps produced via convertDocxToFodt, placing them in the specified folder and replacing them in the source file with:

<image href="$imageFile" outputclass="imageType">.

27 Data::Exchange::Service::check - Check that we are the current incarnation of the named service with details obtained from newServiceIncarnation.

28 Data::Table::Text::Starter::finish - Wait for all started processes to finish and return their results as an array.

29 Data::Table::Text::Starter::start - Start a new process to run the specified $sub.

30 Data::Table::Text::Starter::waitOne - Wait for one process to finish and consolidate its results.

31 dateStamp - Year-monthName-day

32 dateTimeStamp - Year-monthNumber-day at hours:minute:seconds

33 dateTimeStampName - Date time stamp without white space.

34 decodeBase64 - Decode a string in base 64.

35 decodeJson - Decode Perl from Json.

36 denormalizeFolderName - Remove any trailing folder separator from a folder name component.

37 docUserFlags - Generate documentation for a method by calling the extractDocumentationFlags method in the package being documented, passing it the flags for a method and the name of the method.

38 dumpFile - Dump a data structure to a file

39 dumpGZipFile - Write a data structure through gzip to a file.

40 enclosedReversedString - Convert alphanumerics in a string to enclosed reversed alphanumerics.

41 enclosedReversedStringUndo - Undo alphanumerics in a string to enclosed reversed alphanumerics.

42 enclosedString - Convert alphanumerics in a string to enclosed alphanumerics.

43 enclosedStringUndo - Undo alphanumerics in a string to enclosed alphanumerics.

44 encodeBase64 - Encode a string in base 64.

45 encodeJson - Encode Perl to Json.

46 evalFile - Read a file containing unicode in utf8, evaluate it, confess to any errors and then return any result - an improvement on do which silently ignores any problems.

47 evalGZipFile - Read a file containing compressed utf8, evaluate it, confess to any errors or return any result.

48 extractTest - Remove example markers from test code.

49 fe - Get extension of file name.

50 fileList - Files that match a given search pattern handed to bsd_glob.

51 fileModTime - Get the modified time of a file in seconds since the epoch.

52 fileOutOfDate - Calls the specified sub once for each source file that is missing, then calls the sub for the target if there were any missing files or if the target is older than any of the non missing source files or if the target does not exist.

53 filePath - Create a file name from an array of file name components.

54 filePathDir - Create a directory name from an array of file name components.

55 filePathExt - Create a file name from an array of file name components the last of which is an extension.

56 fileSize - Get the size of a file.

57 findDirs - Find all the folders under a folder and optionally filter the selected folders with a regular expression.

58 findFiles - Find all the files under a folder and optionally filter the selected files with a regular expression.

59 findFileWithExtension - Find the first extension from the specified extensions that produces a file that exists when appended to the specified file.

60 firstFileThatExists - Returns the name of the first file that exists or undef if none of the named files exist.

61 firstNChars - First N characters of a string.

62 fn - Remove path and extension from file name.

63 fne - Remove path from file name.

64 formatTable - Format various data structures as a table.

65 formatTableA - Tabularize an array.

66 formatTableAA - Tabularize an array of arrays.

67 formatTableAH - Tabularize an array of hashes.

68 formatTableBasic - Tabularize an array of arrays of text.

69 formatTableH - Tabularize a hash.

70 formatTableHA - Tabularize a hash of arrays.

71 formatTableHH - Tabularize a hash of hashes.

72 formatTableMultiLine - Tabularize text that has new lines in it.

73 fp - Get path from file name.

74 fpn - Remove extension from file name.

75 fullFileName - Full name of a file.

76 genHash - Return a $blessed hash with the specified $attributes accessible via lvalue method calls.

77 genLValueArrayMethods - Generate lvalue array methods in the current package.

78 genLValueHashMethods - Generate lvalue hash methods in the current package.

79 genLValueScalarMethods - Generate lvalue scalar methods in the current package, A method whose value has not yet been set will return a new scalar with value undef.

80 genLValueScalarMethodsWithDefaultValues - Generate lvalue scalar methods with default values in the current package.

81 hostName - The name of the host we are running on.

82 htmlToc - Generate a table of contents for some html.

83 imageSize - Return (width, height) of an image obtained via Imagemagick.

84 indentString - Indent lines contained in a string or formatted table by the specified string.

85 ipAddressViaArp - Get the ip address of a server on the local network by hostname via arp

86 isBlank - Test whether a string is blank.

87 javaPackage - Extract the package name from a java string or file.

88 javaPackageAsFileName - Extract the package name from a java string or file and convert it to a file name.

89 keyCount - Count keys down to the specified level.

90 loadArrayArrayFromLines - Load an array of arrays from lines of text: each line is an array of words.

91 loadArrayFromLines - Load an array from lines of text in a string.

92 loadArrayHashFromLines - Load an array of hashes from lines of text: each line is an hash of words.

93 loadHash - Load the specified $hash generated with genHash with %attributes.

94 loadHashArrayFromLines - Load a hash of arrays from lines of text: the first word of each line is the key, the remaining words are the array contents.

95 loadHashFromLines - Load a hash: first word of each line is the key and the rest is the value.

96 loadHashHashFromLines - Load a hash of hashes from lines of text: the first word of each line is the key, the remaining words are the sub hash contents.

97 makeDieConfess - Force die to confess where the death occurred.

98 makePath - Make the path for the specified file name or folder.

99 matchPath - Given an absolute path find out how much of the path actually exists.

100 max - Find the maximum number in a list.

101 maximumLineLength - Find the longest line in a string

102 mergePackageMethods - Import each of the named @methods that exist in package $from from package $from to package $to if they do not already exist in package $to, otherwise export them from package $to back to package $from in order to merge the behavior of the $from and $to packages with respect to the named methods with duplicates resolved of favour of package $from.

103 microSecondsSinceEpoch - Micro seconds since unix epoch.

104 min - Find the minimum number in a list.

105 newProcessStarter - Create a new process starter with which to start parallel processes up to a specified $maximumNumberOfProcesses maximum number of parallel processes at a time, wait for all the started processes to finish and then optionally retrieve their saved results as an array from the folder named by $transferArea.

106 newServiceIncarnation - Create a new service incarnation to record the start up of a new instance of a service and return the description as a Data::Exchange::Service Definition hash.

107 numberOfLinesInFile - The number of lines in a file

108 numberOfLinesInString - The number of lines in a string.

109 nws - Normalize white space in a string to make comparisons easier.

110 overWriteFile - Write a unicode utf8 string to a file after creating a path to the file if necessary and return the name of the file on success else confess.

111 pad - Pad a string with blanks or the specified padding character to a multiple of a specified length.

112 parseCommandLineArguments - Classify the specified array of words referred to by $args into positional and keyword parameters, call the specified sub with a reference to an array of positional parameters followed by a reference to a hash of keywords and their values then return the value returned by this sub.

113 parseFileName - Parse a file name into (path, name, extension).

114 perlPackage - Extract the package name from a perl string or file.

115 powerOfTwo - Test whether a number is a power of two, return the power if it is else undef.

116 printFullFileName - Print a file name on a separate line with escaping so it can be used easily from the command line.

117 printQw - Print an array of words in qw() format.

118 quoteFile - Quote a file name.

119 readBinaryFile - Read binary file - a file whose contents are not to be interpreted as unicode.

120 readFile - Read a file containing unicode in utf8.

121 readFiles - Read all the files in a folder into a hash

122 readGZipFile - Read the specified $file, containing compressed utf8, through gzip

123 readUtf16File - Read a file containing unicode in utf-16 format.

124 relFromAbsAgainstAbs - Derive a relative file name for the first absolute file name relative to the second absolute file name.

125 reloadHashes - Ensures that all the hashes within a tower of data structures have LValue methods to get and set their current keys.

126 reloadHashes2 - Ensures that all the hashes within a tower of data structures have LValue methods to get and set their current keys.

127 removeFilePrefix - Removes a file prefix from an array of files.

128 renormalizeFolderName - Normalize a folder name component by adding a trailing separator.

129 retrieveFile - Retrieve a file created via Storable.

130 saveCodeToS3 - Save source code files.

131 saveSourceToS3 - Save source code.

132 searchDirectoryTreesForMatchingFiles - Search the specified directory trees for the files (not folders) that match the specified extensions.

133 setIntersectionOfTwoArraysOfWords - Intersection of two arrays of words.

134 setPackageSearchOrder - Set a package search order for methods requested in the current package via AUTOLOAD.

135 setUnionOfTwoArraysOfWords - Union of two arrays of words.

136 showHashes - Create a map of all the keys within all the hashes within a tower of data structures.

137 showHashes2 - Create a map of all the keys within all the hashes within a tower of data structures.

138 startProcess - Start new processes while the number of child processes recorded in %$pids is less than the specified $maximum.

139 storeFile - Store a data structure to a file via Storable.

140 stringsAreNotEqual - Return the common start followed by the two non equal tails of two non equal strings or an empty list if the strings are equal.

141 subScriptString - Convert alphanumerics in a string to sub scripts

142 subScriptStringUndo - Undo alphanumerics in a string to sub scripts

143 sumAbsAndRel - Combine zero or more absolute and relative file names

144 superScriptString - Convert alphanumerics in a string to super scripts

145 superScriptStringUndo - Undo alphanumerics in a string to super scripts

146 swapFilePrefix - Swaps the start of a file name from a known name to a new one,

147 temporaryFile - Create a temporary file that will automatically be unlinked during END processing.

148 temporaryFolder - Create a temporary folder that will automatically be rmdired during END processing.

149 timeStamp - hours:minute:seconds

150 titleToUniqueFileName - Create a file name from a title that is unique within the set %uniqueNames.

151 trackFiles - Track the existence of files.

152 trim - Remove any white space from the front and end of a string.

153 updateDocumentation - Update documentation for a Perl module from the comments in its source code.

154 updatePerlModuleDocumentation - Update the documentation in a perl file and show said documentation in a web browser.

155 userId - The userid we are currently running under.

156 versionCode - YYYYmmdd-HHMMSS

157 versionCodeDashed - YYYY-mm-dd-HH:MM:SS

158 waitForAllStartedProcessesToFinish - Wait until all the processes started by startProcess have finished.

159 writeBinaryFile - Write a non unicode string to a file in after creating a path to the file if necessary and return the name of the file on success else confess.

160 writeFile - Write a unicode utf8 string to a new file that does not already exist after creating a path to the file if necessary and return the name of the file on success else confess if a problem occurred or the file does already exist.

161 writeFiles - Write the values of a hash into files identified by the key of each value using overWriteFile

162 writeGZipFile - Write a unicode utf8 string through gzip to a file.

163 wwwEncode - Replace spaces in a string with %20 .

164 xxx - Execute a shell command optionally checking its response.

165 yyy - Execute a block of shell commands line by line after removing comments - stop if there is a non zero return code from any command.

166 zzz - Execute lines of commands after replacing new lines with && then check that the pipeline execution results in a return code of zero and that the execution results match the optional regular expression if one has been supplied; confess() to an error if either check fails.

167 Ë¢ - Immediately executed inline sub to allow a code block before if.

Installation

This module is written in 100% Pure Perl and, thus, it is easy to read, comprehend, use, modify and install via cpan:

sudo cpan install Data::Table::Text

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

Acknowledgements

Thanks to the following people for their help with this module:

mim@cpan.org: Testing on windows

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 2729:: Non-ASCII character seen before =encoding in 'Ë¢'. Assuming CP1252
Around line 2739:: Couldn't do =encoding utf-8: Encoding is already set to CP1252

To install Data::Table::Text, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::Table::Text

CPAN shell

perl -MCPAN -e shell
install Data::Table::Text

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)