Data::Table::Text - Write data in tabular text format.
use Data::Table::Text;
Print a table:
my $d = [[qw(a b c)], [qq(A), qq(B\nBB), qq(C\nCC\nCCC\n)], [qq(1), qq(1\n22), qq(1\n22\n333\n)], ]; my $t = formatTableBasic($d); ok $t eq <<END; a b c A B C BB CC CCC 1 1 1 22 22 333 END
Print a table containing tables:
my $D = [[qq(See the\ntable\nopposite), $t], [qq(Or\nthis\none), $t], ]; ok formatTable($D) eq <<END; 1 See the a b c table A B C opposite BB CC CCC 1 1 1 22 22 333 2 Or a b c this A B C one BB CC CCC 1 1 1 22 22 333 END
Print an array of arrays:
say STDERR formatTable ([[qw(A B C )], [qw(AA BB CC )], [qw(AAA BBB CCC)], [qw(1 22 333)]], [qw (aa bb cc)]); # aa bb cc # 1 A B C # 2 AA BB CC # 3 AAA BBB CCC # 4 1 22 333
Print an array of hashes:
say STDERR 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 }]); # aa bb cc # 1 A B C # 2 AA BB CC # 3 AAA BBB CCC # 4 1 22 333
Print a hash of arrays:
say STDERR formatTable({ "" => ["aa", "bb", "cc"], "1" => ["A", "B", "C"], "22" => ["AA", "BB", "CC"], "333" => ["AAA", "BBB", "CCC"], "4444" => [1, 22, 333]}); # aa bb cc # 1 A B C # 22 AA BB CC # 333 AAA BBB CCC # 4444 1 22 333
Print a hash of hashes:
say STDERR 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 }}); # aa bb cc # a A B C # aa AA BB CC # aaa AAA BBB CCC # aaaa 1 22 333
Print an array of scalars:
say STDERR formatTable(["a", "bb", "ccc", 4]); # 0 a # 1 bb # 2 ccc # 3 4
Print a hash of scalars:
say STDERR formatTable({ aa => "A", bb => "B", cc => "C" }); # aa A # bb B # cc C
Write data in tabular text format.
The following sections describe the methods in each functional area of this module. For an alphabetic listing of all methods by name see Index.
Date and timestamps as used in logs of long running commands.
Year-monthNumber-day at hours:minute:seconds
Example:
ok dateTimeStamp =~ m(\A\d{4}-\d\d-\d\d at \d\d:\d\d:\d\d\Z);
Year-monthName-day
ok dateStamp =~ m(\A\d{4}-\w{3}-\d\d\Z);
YYYYmmdd-HHMMSS
ok versionCode =~ m(\A\d{8}-\d{6}\Z);
YYYY-mm-dd-HH:MM:SS
ok versionCodeDashed =~ m(\A\d{4}-\d\d-\d\d-\d\d:\d\d:\d\d\Z);
hours:minute:seconds
ok timeStamp =~ m(\A\d\d:\d\d:\d\d\Z);
Micro seconds since unix epoch.
ok microSecondsSinceEpoch > 47*365*24*60*60*1e6;
Various ways of processing commands.
Execute a shell command. 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 the output generated by the execution the command: if the regular expression fails the command output is printed, else it is suppressed as being uninteresting.
Parameter Description 1 @cmd Command to execute followed by an optional regular expression to test the results
{ok xxx("echo aaa") =~ /aaa/;
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
ok !yyy <<END; echo aaa echo bbb END
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
ok zzz(<<END, qr(aaa\s*bbb)s); echo aaa echo bbb END
Classify the specified array of words into positional parameters and keyword parameters, then 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 and return the value returned by this sub.
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
my $r = parseCommandLineArguments {[@_]} [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"}, ], 'parse valid 1';
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
ˢ{our $a = q(1); our @a = qw(1); our %a = (a=>1); our $b = q(1); for(2..4) { call {$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; } };
Operations on files and paths.
Information about each file.
Get the size of a file.
Parameter Description 1 $file File name
my $f = writeFile("zzz.data", "aaa"); ok fileSize($f) == 3;
Get the modified time of a file in seconds since the epoch.
ok fileModTime($0) =~ m(\A\d+\Z)s;
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
if (0) { my @Files = qw(a b c); my @files = (@Files, qw(d)); writeFile($_, $_), sleep 1 for @Files; my $a = ''; my @a = fileOutOfDate {$a .= $_} q(a), @files; ok $a eq 'da', "outOfDate a"; is_deeply [@a], [qw(d a)]; my $b = ''; my @b = fileOutOfDate {$b .= $_} q(b), @files; ok $b eq 'db', "outOfDate b"; is_deeply [@b], [qw(d b)]; my $c = ''; my @c = fileOutOfDate {$c .= $_} q(c), @files; ok $c eq 'dc', "outOfDate c"; is_deeply [@c], [qw(d c)]; my $d = ''; my @d = fileOutOfDate {$d .= $_} q(d), @files; ok $d eq 'd', "outOfDate d"; is_deeply [@d], [qw(d)]; my @A = fileOutOfDate {} q(a), @Files; my @B = fileOutOfDate {} q(b), @Files; my @C = fileOutOfDate {} q(c), @Files; is_deeply [@A], [qw(a)], 'aaa'; is_deeply [@B], [qw(b)], 'bbb'; is_deeply [@C], [], 'ccc'; unlink for @Files; }
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
my $d = temporaryFolder; ok $d eq firstFileThatExists("$d/$d", $d);
Create file names from file name components.
Create a file path 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
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 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.
Directory 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
fpd is a synonym for filePathDir.
File name from file name components and extension. Identical to fpe.
Parameter Description 1 @File File name components and extension
fpe is a synonym for filePathExt.
Get path from file name.
ok fp (q(a/b/c.d.e)) eq q(a/b/);
Remove extension from file name.
ok fpn(q(a/b/c.d.e)) eq q(a/b/c.d);
Remove path and extension from file name.
ok fn (q(a/b/c.d.e)) eq q(c.d);
Remove path from file name.
ok fne(q(a/b/c.d.e)) eq q(c.d.e);
Get extension of file name.
ok fe (q(a/b/c.d.e)) eq q(e);
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
{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 checkFile($d), $d; ok checkFile($f), $f;
Quote a file name.
ok quoteFile(fpe(qw(a b c))) eq q("a/b.c");
Removes a file prefix from an array of files.
Parameter Description 1 $prefix File prefix 2 @files Array of file names
is_deeply [qw(a b)], [&removeFilePrefix(qw(a/ a/a a/b))]; is_deeply [qw(b)], [&removeFilePrefix("a/", "a/b")];
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
ˢ{my $f = {}; ok q(a_p.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_p_2.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_p_3.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_q.txt) eq &titleToUniqueFileName($f, qw(a q txt)); ok q(a_q_5.txt) eq &titleToUniqueFileName($f, qw(a q txt)); ok q(a_q_6.txt) eq &titleToUniqueFileName($f, qw(a q txt)); }; ok q(a_p.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_p_2.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_p_3.txt) eq &titleToUniqueFileName($f, qw(a p txt)); ok q(a_q.txt) eq &titleToUniqueFileName($f, qw(a q txt)); ok q(a_q_5.txt) eq &titleToUniqueFileName($f, qw(a q txt)); ok q(a_q_6.txt) eq &titleToUniqueFileName($f, qw(a q txt));
Position in the file system.
Get the current working directory.
currentDirectory;
The path to the folder above the current working folder.
currentDirectoryAbove;
Parse a file name into (path, name, extension).
Parameter Description 1 $file File name to parse
is_deeply [parseFileName "a.b/c.d.e"], [qw(a.b/ c.d e)];
Full name of a file.
fullFileName(fpe(qw(a txt)));
Create an absolute file from a an absolute file and a following relative file.
Parameter Description 1 $a Absolute file name 2 $f Relative file name
ok "/home/la/perl/aaa.pl" eq absFromAbsPlusRel("/home/la/perl/bbb", "aaa.pl"); ok "/home/la/perl/aaa.pl" eq absFromAbsPlusRel("/home/il/perl/bbb.pl", "../../la/perl/aaa.pl");
Derive a relative file name for the first absolute file relative to the second absolute file name.
Parameter Description 1 $f Absolute file to be made relative 2 $a Absolute file to compare against
ok "bbb.pl" eq relFromAbsAgainstAbs("/home/la/perl/bbb.pl", "/home/la/perl/aaa.pl"); ok "../perl/bbb.pl" eq relFromAbsAgainstAbs("/home/la/perl/bbb.pl", "/home/la/java/aaa.jv");
Temporary files and folders
Create a temporary file that will automatically be unlinked during END processing.
{my $f = temporaryFile;
Create a temporary folder that will automatically be rmdired during END processing.
my $D = temporaryFolder;
temporaryDirectory is a synonym for temporaryFolder.
Find files and folders below a folder.
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
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 $_} findFiles($d, qr(txt\Z))], [qw(a.txt b.txt c.txt)];
Find all the folders under a folder and optionally filter the selected folders with a regular expression.
my $D = temporaryFolder; my $d = fpd($D, q(ddd)); my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c); is_deeply [findDirs($D)], [$D, $d];
Files that match a given search pattern.
Parameter Description 1 $pattern Search pattern
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 $_} fileList("$d/*.txt")], ["a.txt", "b.txt", "c.txt"];
Search the specified directory trees for files that match the specified extensions - the argument list should include at least one folder and one extension to be useful.
Parameter Description 1 @foldersandExtensions Mixture of folder names and extensions
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 $_} searchDirectoryTreesForMatchingFiles($d)], ["a.txt", "b.txt", "c.txt"];
Given an absolute path find out how much of the path actually exists.
{my $d = filePath (my @d = qw(a b c d)); ok matchPath($d) eq $d;
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
my $f = createEmptyFile(fpe(my $d = temporaryFolder, qw(a jpg))); my $F = findFileWithExtension(fpf($d, q(a)), qw(txt data jpg)); ok $F eq "jpg";
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.
Parameter Description 1 $folder Folder 2 $limitCount Maximum number of files to remove to limit damage
my $D = temporaryFolder; my $d = fpd($D, q(ddd)); my @f = map {createEmptyFile(fpe($d, $_, qw(txt)))} qw(a b c); clearFolder($D, 5); ok !-e $_ for @f; ok !-d $D;
Read and write strings from and to files creating paths as needed.
Read a file containing unicode.
Parameter Description 1 $file Name of unicode file to read
{my $f = writeFile(undef, "aaa"); my $s = readFile($f); ok $s eq "aaa"; appendFile($f, "bbb"); my $S = readFile($f); ok $S eq "aaabbb";
Read a file containing unicode, 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
if (1) {my $f = writeFile(undef, q([qw(aaa bbb ccc)])); my $s = evalFile($f); is_deeply $s, [qw(aaa bbb ccc)]; writeFile($f, q({qw(aaa bbb ccc)])); $s = eval { evalFile($f) }; ok $@ =~ m(\Asyntax error); unlink $f; }
Read binary file - a file whose contents are not to be interpreted as unicode.
my $f = writeBinaryFile(undef, 0xff x 8); my $s = readBinaryFile($f); ok $s eq 0xff x 8;
Make the path for the specified file name or folder.
Parameter Description 1 $file File
{my $d = fpd(my $D = temporaryDirectory, qw(a)); my $f = fpe($d, qw(bbb txt)); ok !-e $d; makePath($f); ok -e $d;
Write a unicode string to a file 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 undef for a temporary file 2 $string Unicode string to write
Write the values of a hash as a file identified by the key of the value
Parameter Description 1 $hash Hash of key value pairs representing files and data 2 $folder Optional folder to contain files else the current folder
{my $h = {"aaa/1.txt"=>"1111", "aaa/2.txt"=>"2222", }; writeFiles($h); for(sort keys %$h) {ok -e $_; ok readFile($_) eq $h->{$_};
Append a unicode string to a file 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 append to 2 $string Unicode string to append
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 undef for a temporary file 2 $string Non unicode string to write
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 undef for a temporary file
Image operations.
Return (width, height) of an image obtained via Imagemagick.
Parameter Description 1 $image File containing image
my ($width, $height) = imageSize(fpe(qw(a image jpg)));
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
convertImageToJpx(fpe(qw(a image jpg)), fpe(qw(a image jpg)), 256);
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
convertDocxToFodt(fpe(qw(a docx)), fpe(qw(a fodt)));
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
Parameter Description 1 $inputFile Input file 2 $outputFolder Output folder for images 3 $imagePrefix A prefix to be added to image file names
cutOutImagesInFodtFile(fpe(qw(source fodt)), fpd(qw(images)), q(image));
Encode and decode using Json and Mime.
Encode Perl to Json.
Parameter Description 1 $string Data to encode
my $A = encodeJson(my $a = {a=>1,b=>2, c=>[1..2]}); my $b = decodeJson($A); is_deeply $a, $b;
Decode Perl from Json.
Parameter Description 1 $string Data to decode
Encode a string in base 64.
Parameter Description 1 $string String to encode
my $A = encodeBase64(my $a = "Hello World" x 10); my $b = decodeBase64($A); ok $a eq $b;
Decode a string in base 64.
Parameter Description 1 $string String to decode
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
ok convertUnicodeToXml('setenta e três') eq q(setenta e três);
Numeric operations,
Test whether a number is a power of two, return the power if it is else undef.
Parameter Description 1 $n Number to check
ok powerOfTwo(1) == 0; ok powerOfTwo(2) == 1; ok !powerOfTwo(3); ok powerOfTwo(4) == 2;
Find log two of the lowest power of two greater than or equal to a number.
ok containingPowerOfTwo(1) == 0; ok containingPowerOfTwo(2) == 1; ok containingPowerOfTwo(3) == 2; ok containingPowerOfTwo(4) == 2;
Set operations.
Intersection of two arrays of words.
Parameter Description 1 $a Reference to first array of words 2 $b Reference to second array of words
is_deeply [qw(a b c)], [setIntersectionOfTwoArraysOfWords([qw(e f g a b c )], [qw(a A b B c C)])];
Union of two arrays of words.
is_deeply [qw(a b c)], [setUnionOfTwoArraysOfWords([qw(a b c )], [qw(a b)])];
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
is_deeply [1], [contains(1,0..1)]; is_deeply [1,3], [contains(1, qw(0 1 0 1 0 0))]; is_deeply [0, 5], [contains('a', qw(a b c d e a b c d e))]; is_deeply [0, 1, 5], [contains(qr(a+), qw(a baa c d e aa b c d e))];
Find the smallest and largest elements of arrays.
Find the minimum number in a list.
Parameter Description 1 @n Numbers
ok min(1) == 1; ok min(5,4,2,3) == 2;
Find the maximum number in a list.
ok !max; ok max(1) == 1; ok max(1,4,2,3) == 4;
Format data structures as tables.
Find the longest line in a string
Parameter Description 1 $string String of lines of text
ok 3 == maximumLineLength(<<END); a bb ccc END
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.
Tabularize text that does not have new lines in it.
my $d = [[qw(a 1)], [qw(bb 22)], [qw(ccc 333)], [qw(dddd 4444)]]; ok formatTableBasic($d) eq <<END; a 1 bb 22 ccc 333 dddd 4444 END
Format various data structures as a table.
Parameter Description 1 $data Data to be formatted 2 $title Optional reference to an array of titles 3 $separator Optional line separator
ok formatTable ([[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 formatTable ([[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 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'} ]) eq <<END; aa bb cc 1 A B C 2 AA BB CC 3 AAA BBB CCC 4 1 22 333 END ok formatTable ({''=>[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 say STDERR formatTable ({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 formatTable({aa=>'A', bb=>'B', cc=>'C'}, [qw(aaaa bbbb)]) eq <<END; aaaa bbbb aa A bb B cc C END
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
{my $a = [[1..3], {map{$_=>1} 1..3}]; my $h = {a=>[1..3], b=>{map{$_=>1} 1..3}}; ok keyCount(2, $a) == 6; ok keyCount(2, $h) == 6;
Load data structures from lines.
Load an array from lines of text in a string.
Parameter Description 1 $string The string of lines from which to create an array
{my $s = loadArrayFromLines <<END; a a b b END ok dump($s) eq '["a a", "b b"]';
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
{my $s = loadHashFromLines <<END; a 10 11 12 b 20 21 22 END ok dump($s) eq '{ a => "10 11 12", b => "20 21 22" }';
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
{my $s = loadArrayArrayFromLines <<END; A B C AA BB CC END ok dump($s) eq '[["A", "B", "C"], ["AA", "BB", "CC"]]';
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
{my $s = loadHashArrayFromLines <<END; a A B C b AA BB CC END ok dump($s) eq '{ a => ["A", "B", "C"], b => ["AA", "BB", "CC"] }';
Check the keys in a hash.
Parameter Description 1 $test The hash to test 2 $permitted The permitted keys and their meanings
eval {checkKeys({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);
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.
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
package Scalars; my $a = bless{}; Data::Table::Text::genLValueScalarMethods(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;
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.
my $class = "Data::Table::Text::Test"; my $a = bless{}, $class; addLValueScalarMethods(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;
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.
package ScalarsWithDefaults; my $a = bless{}; Data::Table::Text::genLValueScalarMethodsWithDefaultValues(qw(aa bb cc)); Test::More::ok $a->aa eq 'aa';
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.
package Arrays; my $a = bless{}; Data::Table::Text::genLValueArrayMethods(qw(aa bb cc)); $a->aa->[1] = 'aa'; Test::More::ok $a->aa->[1] eq 'aa';
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
package Hashes; my $a = bless{}; Data::Table::Text::genLValueHashMethods(qw(aa bb cc)); $a->aa->{a} = 'aa'; Test::More::ok $a->aa->{a} eq 'aa';
Confirm that the specified references are to the package into which this routine has been exported.
Parameter Description 1 @refs References
eval {assertRef(my $r = 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 as {} without the word "sub"
ok ˢ{1}; ok ˢ{1} == 1;
Build classes of attributes
Copy attributes definitions from the $source class to the $target class.
Parameter Description 1 $targetClass Target class 2 $sourceClass Source class
if (1) {my $c = genClass(q(Test::Class1), aa=>q(aa attribute), bb=>q(bb attribute)); # Define first class ok defined(&Test::Class1::aa); ok defined(&Test::Class1::bb); ok !defined(&Test::Class1::cc); my $d = genClass(q(Test::Class2), cc=>q(cc attribute), bb=>q(bb attribute)); # Define second class ok !defined(&Test::Class2::aa); ok defined(&Test::Class2::bb); ok defined(&Test::Class2::cc); $c->addClass($d); # Add second class to first class $c->cc = "cc"; # Set attribute in first class copied from first class ok defined(&Test::Class1::cc); ok $c->cc eq q(cc); ok $c->printClass eq <<END; # Print class attributes available Attribute Value 1 aa aa attribute 2 bb bb attribute 3 cc cc attribute END ok $c->print eq <<END; # Print current values of attributes in an instance of a class Attribute Value 1 aa 2 bb 3 cc cc END }
Generate a class $class with the specified %Attributes. Each class will also have a new method which creates a new instance of the class with the specified attributes, an addClass method which adds attribute definitions from another class to the specified class, printClass which prints the definition of the class and print which prints the attributes of scalar attributes in an instance of the class.
Parameter Description 1 $class Class name 2 %Attributes Hash of attribute names to attribute descriptions.
if (1) {my $c = genClass(q(Test::Class), aa=>q(aa attribute), bb=>q(bb attribute)); # Define a class my $a = $c->new(aa=>q(aa)); # Create an object in the class is_deeply $a, bless({ aa => "aa", class => "Test::Class", attributes => { aa => "aa attribute", bb => "bb attribute" }, }, "Test::Class"); $a->aa = q(bb); # Modify object is_deeply $a, bless({ aa => "bb", class => "Test::Class", attributes => { aa => "aa attribute", bb => "bb attribute" }, }, "Test::Class"); my $b = $a->new(bb=>q(bb)); # Create an object is_deeply $b, bless({ bb => "bb", class => "Test::Class", attributes => { aa => "aa attribute", bb => "bb attribute" }, }, "Test::Class"); $b->aa = q(aa); # Modify object is_deeply $b, bless({ aa => "aa", bb => "bb", class => "Test::Class", attributes => { aa => "aa attribute", bb => "bb attribute" }, }, "Test::Class"); }
Actions on strings.
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
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
Test whether a string is blank.
Parameter Description 1 $string String
ok isBlank(""); ok isBlank(" ");
Trim off white space from from front and end of string.
ok trim(" a b ") eq join ' ', qw(a b);
Pad a string with blanks to a multiple of a specified length.
Parameter Description 1 $string String 2 $length Tab width
ok pad('abc ', 2).'=' eq "abc ="; ok pad('abc ', 3).'=' eq "abc="; ok pad('abc ', 4).'=' eq "abc =";
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 singe space. In effect: this puts everything on one long line with never more than a space at a time.
Parameter Description 1 $string String to normalize
ok nws(qq(a b c)) eq q(a b c);
Extract the package name from a java string or file.
Parameter Description 1 $java Java file if it exists else the string of java
writeFile($f, <<END); // Test package com.xyz; END ok javaPackage($f) eq "com.xyz";
Extract the package name from a java string or file and convert it to a file name.
writeFile($f, <<END); // Test package com.xyz; END ok javaPackageAsFileName($f) eq "com/xyz";
Extract the package name from a perl string or file.
Parameter Description 1 $perl Perl file if it exists else the string of perl
writeFile($f, <<END); package a::b; END ok perlPackage($f) eq "a::b";
Print an array of words in qw() format.
Parameter Description 1 @words Array of words
ok printQw(qw(a b c)) eq q(qw(a b c));
Useful for operating across the cloud.
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
saveCodeToS3(1200, q(projectName), q(bucket/folder), q(--only-show-errors));
Add a certificate to the current ssh session.
Parameter Description 1 $file File containing certificate
addCertificate(fpf(qw(.ssh cert)));
The name of the host we are running on.
hostName;
The userid we are currently running under.
userId;
Replace spaces in a string with %20 .
ok wwwEncode(q(a b c)) eq q(a%20%20b%20c);
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
if (0) { my %pids; ˢ{startProcess {} %pids, 1; ok 1 >= keys %pids} for 1..8; waitForAllStartedProcessesToFinish(%pids); ok !keys(%pids) }
Wait until all the processes started by startProcess have finished.
Parameter Description 1 $pids Hash of started process ids
Extract, format and update documentation for a perl module.
Generate a table of contents for some html.
Parameter Description 1 $replace Substring within the html to be replaced with the toc 2 $html String of html
ok nws(htmlToc("XXXX", <<END)) <h1 id="1">Chapter 1</h1> <h2 id="11">Section 1</h1> <h1 id="2">Chapter 2</h1> XXXX END eq nws(<<END); <h1 id="1">Chapter 1</h1> <h2 id="11">Section 1</h1> <h1 id="2">Chapter 2</h1> <table cellspacing=10 border=0> <tr><td> <tr><td align=right>1<td> <a href="#1">Chapter 1</a> <tr><td align=right>2<td> <a href="#11">Section 1</a> <tr><td> <tr><td align=right>3<td> <a href="#2">Chapter 2</a> </table> END
Update documentation from the comments in a perl script. 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:
method of interest to new users
private method
optionally replaceable method
required replaceable method
static method
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.
#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-20180801/lib/Data/Table/Text.pm to see more examples of such documentation in action.
Parameter Description 1 $perlModule Optional file name with caller's file being the default
{my $s = updateDocumentation(<<'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';
Remove any trailing folder separator from a folder name component.
Parameter Description 1 $name Name
Normalize a folder name component by adding a trailing separator.
Track the existence of files.
Parameter Description 1 $label Label 2 @files Files
Print a file name on a separate line with escaping so it can be used easily from the command line.
Read a file containing unicode in utf-16 format.
Parameter Description 1 $file Name of file to read
Set STDOUT and STDERR to accept utf8 without complaint.
binModeAllUtf8;
Convert an image to jpx format using versions of Imagemagick version 6.9.0 and above.
Tabularize an array of arrays.
Tabularize a hash of arrays.
Parameter Description 1 $data Data to be formatted 2 $title Optional title 3 $separator Optional line separator
Tabularize an array of hashes.
Tabularize a hash of hashes.
Tabularize an array.
Tabularize a hash.
Save source code.
Parameter Description 1 $aws Aws target file and keywords 2 $saveIntervalInSeconds Save internal
Extract a line of a test.
Parameter Description 1 $string String containing test line
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
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
fpd is a synonym for filePathDir - Directory from an array of file name components.
fpe is a synonym for filePathExt - File name from file name components and extension.
fpf is a synonym for filePath - Create a file path from an array of file name components.
temporaryDirectory is a synonym for temporaryFolder - Create a temporary folder that will automatically be rmdired during END processing.
1 absFromAbsPlusRel - Create an absolute file from a an absolute file and a following relative file.
2 addCertificate - Add a certificate to the current ssh session.
3 addClass - Copy attributes definitions from the $source class to the $target class.
4 addLValueScalarMethods - Generate lvalue scalar methods in the current package if they do not already exist.
5 appendFile - Append a unicode string to a file after creating a path to the file if necessary and return the name of the file on success else confess.
6 assertRef - Confirm that the specified references are to the package into which this routine has been exported.
7 binModeAllUtf8 - Set STDOUT and STDERR to accept utf8 without complaint.
8 call - Call the specified sub in a separate process, wait for it to complete, copy back the named our variables, free the memory used.
9 checkFile - Return the name of the specified file if it exists, else confess the maximum extent of the path that does exist.
10 checkKeys - Check the keys in a hash.
11 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.
12 containingPowerOfTwo - Find log two of the lowest power of two greater than or equal to a number.
13 contains - Returns the indices at which an item matches elements of the specified array.
14 convertDocxToFodt - Convert a .
15 convertImageToJpx - Convert an image to jpx format using Imagemagick.
16 convertImageToJpx690 - Convert an image to jpx format using versions of Imagemagick version 6.
17 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.
18 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.
19 currentDirectory - Get the current working directory.
20 currentDirectoryAbove - The path to the folder above the current working folder.
21 cutOutImagesInFodtFile - Cut out the images embedded in a .
22 dateStamp - Year-monthName-day
23 dateTimeStamp - Year-monthNumber-day at hours:minute:seconds
24 decodeBase64 - Decode a string in base 64.
25 decodeJson - Decode Perl from Json.
26 denormalizeFolderName - Remove any trailing folder separator from a folder name component.
27 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.
28 encodeBase64 - Encode a string in base 64.
29 encodeJson - Encode Perl to Json.
30 evalFile - Read a file containing unicode, evaluate it, confess to any errors and then return any result - an improvement on do which silently ignores any problems.
31 extractTest - Extract a line of a test.
32 fe - Get extension of file name.
33 fileList - Files that match a given search pattern.
34 fileModTime - Get the modified time of a file in seconds since the epoch.
35 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.
36 filePath - Create a file path from an array of file name components.
37 filePathDir - Directory from an array of file name components.
38 filePathExt - File name from file name components and extension.
39 fileSize - Get the size of a file.
40 findDirs - Find all the folders under a folder and optionally filter the selected folders with a regular expression.
41 findFiles - Find all the files under a folder and optionally filter the selected files with a regular expression.
42 findFileWithExtension - Find the first extension from the specified extensions that produces a file that exists when appended to the specified file.
43 firstFileThatExists - Returns the name of the first file that exists or undef if none of the named files exist.
44 fn - Remove path and extension from file name.
45 fne - Remove path from file name.
46 formatTable - Format various data structures as a table.
47 formatTableA - Tabularize an array.
48 formatTableAA - Tabularize an array of arrays.
49 formatTableAH - Tabularize an array of hashes.
50 formatTableBasic - Tabularize text that does not have new lines in it.
51 formatTableH - Tabularize a hash.
52 formatTableHA - Tabularize a hash of arrays.
53 formatTableHH - Tabularize a hash of hashes.
54 formatTableMultiLine - Tabularize text that has new lines in it.
55 fp - Get path from file name.
56 fpn - Remove extension from file name.
57 fullFileName - Full name of a file.
58 genClass - Generate a class $class with the specified %Attributes.
59 genLValueArrayMethods - Generate lvalue array methods in the current package.
60 genLValueHashMethods - Generate lvalue hash methods in the current package.
61 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.
62 genLValueScalarMethodsWithDefaultValues - Generate lvalue scalar methods with default values in the current package.
63 hostName - The name of the host we are running on.
64 htmlToc - Generate a table of contents for some html.
65 imageSize - Return (width, height) of an image obtained via Imagemagick.
66 indentString - Indent lines contained in a string or formatted table by the specified string.
67 isBlank - Test whether a string is blank.
68 javaPackage - Extract the package name from a java string or file.
69 javaPackageAsFileName - Extract the package name from a java string or file and convert it to a file name.
70 keyCount - Count keys down to the specified level.
71 loadArrayArrayFromLines - Load an array of arrays from lines of text: each line is an array of words.
72 loadArrayFromLines - Load an array from lines of text in a string.
73 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.
74 loadHashFromLines - Load a hash: first word of each line is the key and the rest is the value.
75 makePath - Make the path for the specified file name or folder.
76 matchPath - Given an absolute path find out how much of the path actually exists.
77 max - Find the maximum number in a list.
78 maximumLineLength - Find the longest line in a string
79 microSecondsSinceEpoch - Micro seconds since unix epoch.
80 min - Find the minimum number in a list.
81 nws - Normalize white space in a string to make comparisons easier.
82 pad - Pad a string with blanks to a multiple of a specified length.
83 parseCommandLineArguments - Classify the specified array of words into positional parameters and keyword parameters, then 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 and return the value returned by this sub.
84 parseFileName - Parse a file name into (path, name, extension).
85 perlPackage - Extract the package name from a perl string or file.
86 powerOfTwo - Test whether a number is a power of two, return the power if it is else undef.
87 printFullFileName - Print a file name on a separate line with escaping so it can be used easily from the command line.
88 printQw - Print an array of words in qw() format.
89 quoteFile - Quote a file name.
90 readBinaryFile - Read binary file - a file whose contents are not to be interpreted as unicode.
91 readFile - Read a file containing unicode.
92 readUtf16File - Read a file containing unicode in utf-16 format.
93 relFromAbsAgainstAbs - Derive a relative file name for the first absolute file relative to the second absolute file name.
94 removeFilePrefix - Removes a file prefix from an array of files.
95 renormalizeFolderName - Normalize a folder name component by adding a trailing separator.
96 saveCodeToS3 - Save source code files.
97 saveSourceToS3 - Save source code.
98 searchDirectoryTreesForMatchingFiles - Search the specified directory trees for files that match the specified extensions - the argument list should include at least one folder and one extension to be useful.
99 setIntersectionOfTwoArraysOfWords - Intersection of two arrays of words.
100 setUnionOfTwoArraysOfWords - Union of two arrays of words.
101 startProcess - Start new processes while the number of child processes recorded in %$pids is less than the specified $maximum.
102 temporaryFile - Create a temporary file that will automatically be unlinked during END processing.
103 temporaryFolder - Create a temporary folder that will automatically be rmdired during END processing.
104 timeStamp - hours:minute:seconds
105 titleToUniqueFileName - Create a file name from a title that is unique within the set %uniqueNames.
106 trackFiles - Track the existence of files.
107 trim - Trim off white space from from front and end of string.
108 updateDocumentation - Update documentation from the comments in a perl script.
109 updatePerlModuleDocumentation - Update the documentation in a perl file and show said documentation in a web browser.
110 userId - The userid we are currently running under.
111 versionCode - YYYYmmdd-HHMMSS
112 versionCodeDashed - YYYY-mm-dd-HH:MM:SS
113 waitForAllStartedProcessesToFinish - Wait until all the processes started by startProcess have finished.
114 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.
115 writeFile - Write a unicode string to a file after creating a path to the file if necessary and return the name of the file on success else confess.
116 writeFiles - Write the values of a hash as a file identified by the key of the value
117 wwwEncode - Replace spaces in a string with %20 .
118 xxx - Execute a shell command.
119 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.
120 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.
121 ˢ - Immediately executed inline sub to allow a code block before if.
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
philiprbrenan@gmail.com
http://www.appaapps.com
Copyright (c) 2016-2018 Philip R Brenan.
This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.
Thanks to the following people for their help with this module:
Testing on windows
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.