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, use, modify and install.
Standard Module::Build process for building and installing modules:
perl Build.PL ./Build ./Build test ./Build install
`head1 Author
philiprbrenan\@gmail.com
http://www.appaapps.com
`head1 Copyright
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. 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 $@; }
test unless caller; END
s/\\m/\n\n/gs for @doc; # Expand \\m to two new lines in documentation s/\\n/\n/gs for @doc; # Expand \\n to one new line in documentation s/\\x//gs for @doc; # Expand \\x to '' in documentation s/`/=/gs for @doc; # Convert ` to = my $doc = join "\n", @doc; # Documentation $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 {writeFile(filePathExt($perlModule, qq(backup)), $source); # Backup module source writeFile($perlModule, $source); # Write updated module source } }
sub docUserFlags($$$$) # Generate documentation for a 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($) # 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 " google-chrome zzz.html pods2 && ". " rm zzz.html pod2htmd.tmp"); }
#------------------------------------------------------------------------------- # Examples #-------------------------------------------------------------------------------
if (0 and !caller) {say STDERR "\n","\nsay STDERR formatTable(",dump($_), ");\n# ", formatTable($_) =~ s/\n/\n# /gr for [[qw(. aa bb cc)], [qw(1 A B C)], [qw(2 AA BB CC)], [qw(3 AAA BBB CCC)], [qw(4 1 22 333)]], [{aa=>'A', bb=>'B', cc=>'C'}, {aa=>'AA', bb=>'BB', cc=>'CC'}, {aa=>'AAA', bb=>'BBB', cc=>'CCC'}, {aa=>'1', bb=>'22', cc=>'333'}], {''=>[qw(aa bb cc)], 1=>[qw(A B C)], 22=>[qw(AA BB CC)], 333=>[qw(AAA BBB CCC)], 4444=>[qw(1 22 333)]}, {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'}}, [qw(a bb ccc 4444)], {aa=>'A', bb=>'B', cc=>'C'}; }
#------------------------------------------------------------------------------- # Export #-------------------------------------------------------------------------------
use Exporter qw(import);
use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
@ISA = qw(Exporter); @EXPORT = qw(formatTable); @EXPORT_OK = qw( addCertificate appendFile binModeAllUtf8 checkFile checkFilePath checkFilePathExt checkFilePathDir checkKeys clearFolder contains containingPowerOfTwo containingFolder convertImageToJpx convertUnicodeToXml createEmptyFile currentDirectory currentDirectoryAbove dateStamp dateTimeStamp decodeJson decodeBase64 encodeJson encodeBase64 fileList fileModTime fileOutOfDate filePath filePathDir filePathExt fileSize findDirs findFiles findFileWithExtension formatTableBasic fpd fpe fpf fullFileName genLValueArrayMethods genLValueHashMethods genLValueScalarMethods genLValueScalarMethodsWithDefaultValues hostName htmlToc imageSize indentString isBlank javaPackage javaPackageAsFileName keyCount loadArrayArrayFromLines loadArrayFromLines loadHashArrayFromLines loadHashFromLines makePath matchPath max microSecondsSinceEpoch min nws pad parseFileName parseCommandLineArguments powerOfTwo printFullFileName printQw quoteFile readBinaryFile readFile removeFilePrefix saveToS3 searchDirectoryTreesForMatchingFiles setIntersectionOfTwoArraysOfWords setUnionOfTwoArraysOfWords temporaryDirectory temporaryFile temporaryFolder timeStamp trackFiles trim updateDocumentation updatePerlModuleDocumentation userId versionCode writeBinaryFile writeFile writeFiles xxx XXX zzz); %EXPORT_TAGS = (all=>[@EXPORT, @EXPORT_OK]);
# podDocumentation #C mim@cpan.org Testing on windows
Data::Table::Text - Write data in tabular text format
use Data::Table::Text;
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
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
Year-monthName-day
YYYmmdd-HHMMSS
hours:minute:seconds
Micro seconds since unix epoch
Various ways of processing commands
Execute a command checking and logging the results: the command to execute is specified as one or more strings with optionally the last string being a regular expression that is used to confirm that the command executed successfully and thus that it is safe to suppress the command output as uninteresting.
Parameter Description 1 @cmd Command to execute followed by an optional regular expression to test the results
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
Execute lines of commands as one long command string separated by added &&'s and then check that the pipeline 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
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 the 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
Operations on files and paths
Information about each file
Get the size of a file.
Parameter Description 1 $file File name
Get the modified time of a file in seconds since the epoch.
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:
fileOutOfDate {make($_)} $target, $source1, $source2, $source3;
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.
Parameter Description 1 @file File components
Directory from an array of file name components. If all the components are blank then a blank file name is returned.
File name from file name components and extension.
Parameter Description 1 @File File components and extension
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
Check a folder name constructed from its components
Check a file name constructed from its components
Quote a file name.
Removes a file prefix from an array of files.
Parameter Description 1 $prefix File prefix 2 @files Array of file names
Track the existence of files
Parameter Description 1 $label Label 2 @files Files
Position in the file system
Get the current working directory.
The path to the folder above the current working folder.
Parse a file name into (path, name, extension)
Parameter Description 1 $file File name to parse
Path to the folder that contains this file, or use "parseFileName"
Full name of a file.
Print a file name on a separate line with escaping so it can be used easily from the command line.
Temporary files and folders
Create a temporary file that will automatically be unlinked during END
Create a temporary folder that will automatically be rmdired during END
Create a temporary directory that will automatically be rmdired during END
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
Find all the folders under a folder and optionally filter the selected folders with a regular expression
Files that match a given search pattern.
Parameter Description 1 $pattern Search pattern
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
Given an absolute path find out how much of the path actually exists.
Find the first extension from teh 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
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
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
Read binary file - a file whose contents are not to be interpreted as unicode.
Parameter Description 1 $file File to read
Make the path for the specified file name or folder.
Parameter Description 1 $file File
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 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
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 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
Set STDOUT and STDERR to accept utf8 without complaint
Image operations
Return (width, height) of an image obtained via imagemagick.
Parameter Description 1 $image File containing image
Convert an image to jpx format as the latest version of ImageMagick no longer seems to tile.
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
Convert an image to jpx format - works with: Version: ImageMagick 6.8.9-9 Q16 x86_64 2017-03-14
Encode and decode using Json and Mime
Encode Perl to Json.
Parameter Description 1 $string Data to encode
Decode Perl from Json.
Parameter Description 1 $string Data to decode
Encode a string in base 64.
Parameter Description 1 $string String to encode
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
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
Use powerOfTwoX to execute powerOfTwo but die 'powerOfTwo' instead of returning undef
Find log two of the lowest power of two greater than or equal to a number.
Use containingPowerOfTwoX to execute containingPowerOfTwo but die 'containingPowerOfTwo' instead of returning undef
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
Union of two arrays of words
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
Find the smallest and largest elements of arrays
Find the minimum number in a list.
Parameter Description 1 @n Numbers
Find the maximum number in a list.
Format data structures as tables
Tabularize text
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.
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
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
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
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
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
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
Check the keys in a hash.
Parameter Description 1 $test The hash to test 2 $permitted The permitted keys and their meanings
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 spelt 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
$a->value = 1;
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.
$a->value == qq(value);
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.
$a->value->[1] = 2;
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
$a->value->{a} = 'b';
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
Test whether a string is blank.
Parameter Description 1 $string String
Trim off white space from from front and end of string.
Pad a string with blanks to a multiple of a specified length.
Parameter Description 1 $string String 2 $length Tab width
Normalize white space in a string to make comparisons easier. Leading and trailing white space is removed; blocks of whitespace 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
Extract the package name from a java string or file.
Parameter Description 1 $java Java file if it exists else the string of java
Extract the package name from a java string or file and convert it to a file name.
Extract the package name from a perl string or file.
Parameter Description 1 $perl Perl file if it exists else the string of perl
Print an array of words in qw() format
Parameter Description 1 @words Array of words
Useful for operating across the cloud
Add a certificate to the current ssh session.
Parameter Description 1 $file File containing certificate
The name of the host we are running on
The userid we are currently running under
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
Update documentation from a perl script between the lines marked with:
#n title # description
and:
#...
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 any combination of:
method of interest to new users
private 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 as an example.
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 and \m to two new lines.
Search for '#1': in https://metacpan.org/source/PRBRENAN/Data-Table-Text-20170728/lib/Data/Table/Text.pm to see examples.
Parameters:
Parameter Description 1 $perlModule Optional file name with caller's file being the default
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.
Tabularize an array of arrays.
Parameter Description 1 $data Data to be formatted 2 $title Optional referebce to an array of titles 3 $separator Optional line separator
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.
Extract a line of a test.
Parameter Description 1 $string String containing test line
1 addCertificate
2 appendFile
3 binModeAllUtf8
4 checkFile
5 checkFilePath
6 checkFilePathDir
7 checkFilePathExt
8 checkKeys
9 clearFolder
10 containingFolder
11 containingPowerOfTwo
12 containingPowerOfTwoX
13 contains
14 convertImageToJpx
15 convertImageToJpx2
16 convertUnicodeToXml
17 createEmptyFile
18 currentDirectory
19 currentDirectoryAbove
20 dateStamp
21 dateTimeStamp
22 decodeBase64
23 decodeJson
24 denormalizeFolderName
25 encodeBase64
26 encodeJson
27 extractTest
28 fileList
29 fileModTime
30 fileOutOfDate
31 filePath
32 filePathDir
33 filePathExt
34 fileSize
35 findDirs
36 findFiles
37 findFileWithExtension
38 formatTable
39 formatTableA
40 formatTableAA
41 formatTableAH
42 formatTableBasic
43 formatTableH
44 formatTableHA
45 formatTableHH
46 fullFileName
47 genLValueArrayMethods
48 genLValueHashMethods
49 genLValueScalarMethods
50 genLValueScalarMethodsWithDefaultValues
51 hostName
52 htmlToc
53 imageSize
54 indentString
55 isBlank
56 javaPackage
57 javaPackageAsFileName
58 keyCount
59 loadArrayArrayFromLines
60 loadArrayFromLines
61 loadHashArrayFromLines
62 loadHashFromLines
63 makePath
64 matchPath
65 max
66 microSecondsSinceEpoch
67 min
68 nws
69 pad
70 parseCommandLineArguments
71 parseFileName
72 perlPackage
73 powerOfTwo
74 powerOfTwoX
75 printFullFileName
76 printQw
77 quoteFile
78 readBinaryFile
79 readFile
80 removeFilePrefix
81 renormalizeFolderName
82 searchDirectoryTreesForMatchingFiles
83 setIntersectionOfTwoArraysOfWords
84 setUnionOfTwoArraysOfWords
85 temporaryDirectory
86 temporaryFile
87 temporaryFolder
88 timeStamp
89 trackFiles
90 trim
91 updateDocumentation
92 userId
93 versionCode
94 writeBinaryFile
95 writeFile
96 writeFiles
97 xxx
98 yyy
99 zzz
philiprbrenan@gmail.com
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.