Data::Table::Text - Write data in tabular text format
Print an array of hashes:
use Data::Table::Text; 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", 4444]); # 0 a # 1 bb # 2 ccc # 3 4444
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
hours:minute:seconds
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.
1 @cmd Command to execute followed by an optional regular expression to test the results
Operations on files and paths
Information about each file
Get the size of a file.
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.
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.
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.
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.
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.
1 $prefix File prefix 2 @files Array of file names
Position in the file system
Get the current working directory.
Get the current user id via whoami
The path to the folder above the current working folder.
Parse a file name into (path, name, extension)
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.
1 $dir Folder to start the search with
Find all the folders under a folder.
File list.
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.
1 @foldersandExtensions Mixture of folder names and extensions
Given an absolute path find out how much of the path actually exists.
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.
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.
1 $file Name of unicode file to read
Read binary file - a file whose contents are not to be interpreted as unicode.
1 $file File to read
Make the path for the specified file name or folder.
1 $file File
Write a unicode string to a file after creating a path to the file if necessary.
1 $file File to write to 2 $string Unicode string to write
Append a unicode string to a file after creating a path to the file if necessary.
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.
1 $file File to write to 2 $string Non unicode string to write
Image operations
Return (width, height) of an image obtained via imagemagick.
1 $image File containing image
Convert an image to jpx format.
1 $source Source file 2 $target Target folder (as multiple files will be created) 3 $size Size of each tile
Encode and decode using Json and Mime
Encode Perl to Json.
1 $string Data to encode
Decode Perl from Json.
1 $string Data to decode
Encode a string in base 64.
1 $string String to encode
Decode a string in base 64.
1 $string String to decode
Numeric operations
Test whether a number is a power of two, return the power if it is else undef
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
Array operations
Returns the indices at which an item matches an array. If item is a regular expression then it is matched as one else it is a number it is matched as a number, else a string.
1 $item Item 2 @array Array
Find the minimum number in a list.
1 @n Numbers
Find the maximum number in a list.
Format data structures as tables
Tabularize text - basic version.
1 $data Data to be formatted 2 $separator Optional line separator
Format various data structures.
1 $data Data to be formatted 2 $title Optional title 3 $separator Optional line separator
Count keys down to the specified level.
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.
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.
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.
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.
1 $string The string of lines from which to create a hash of arrays
Check the keys in a hash.
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.
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.
1 @names Method names
$a->value->{a} = 'b';
Actions on strings
Indent lines contained in a string or formatted table by the specified string.
1 $string The string of lines to indent 2 $indent The indenting string
Test whether a string is blank.
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.
1 $string String 2 $length Tab width
Normalize white space in a string to make comparisons easier.
1 $string String to normalize
Extract the package name from a java string or file.
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.
1 $perl Perl file if it exists else the string of perl
Useful for operating across the cloud
Add a certificate to the current ssh session.
1 $file File containing certificate
Extract, format and update documentation for a perl module
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:
1 $perlModule Optional file name with caller's file being the default
Remove any trailing folder separator from a folder name component.
1 $name Name
Normalize a folder name component by adding a trailing separator.
Tabularize an array of arrays.
Tabularize a hash of arrays.
Tabularize an array of hashes.
Tabularize a hash of hashes.
Tabularize an array.
Tabularize a hash.
Extract a line of a test.
1 $string String containing test line
1 addCertificate
2 appendFile
3 checkFile
4 checkFilePath
5 checkFilePathDir
6 checkFilePathExt
7 checkKeys
8 clearFolder
9 containingFolder
10 containingPowerOfTwo
11 containingPowerOfTwoX
12 contains
13 convertImageToJpx
14 currentDirectory
15 currentDirectoryAbove
16 dateStamp
17 dateTimeStamp
18 decodeBase64
19 decodeJson
20 denormalizeFolderName
21 encodeBase64
22 encodeJson
23 extractTest
24 fileList
25 fileModTime
26 fileOutOfDate
27 filePath
28 filePathDir
29 filePathExt
30 fileSize
31 findDirs
32 findFiles
33 formatTable
34 formatTableA
35 formatTableAA
36 formatTableAH
37 formatTableBasic
38 formatTableH
39 formatTableHA
40 formatTableHH
41 fullFileName
42 genLValueArrayMethods
43 genLValueHashMethods
44 genLValueScalarMethods
45 genLValueScalarMethodsWithDefaultValues
46 imageSize
47 indentString
48 isBlank
49 javaPackage
50 javaPackageAsFileName
51 keyCount
52 loadArrayArrayFromLines
53 loadArrayFromLines
54 loadHashArrayFromLines
55 loadHashFromLines
56 makePath
57 matchPath
58 max
59 min
60 nws
61 pad
62 parseFileName
63 perlPackage
64 powerOfTwo
65 powerOfTwoX
66 printFullFileName
67 quoteFile
68 readBinaryFile
69 readFile
70 removeFilePrefix
71 renormalizeFolderName
72 searchDirectoryTreesForMatchingFiles
73 temporaryDirectory
74 temporaryFile
75 temporaryFolder
76 timeStamp
77 trim
78 updateDocumentation
79 userId
80 writeBinaryFile
81 writeFile
82 xxx
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
philiprbrenan@gmail.com
http://www.appaapps.com
Copyright (c) 2016-2017 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.