Philip R Brenan
and 1 contributors

Name

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

Synopsis

 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

Description

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

Time stamps

Date and timestamps as used in logs of long running commands

dateTimeStamp()

Year-monthNumber-day at hours:minute:seconds

dateStamp()

Year-monthName-day

versionCode()

YYYmmdd-HHMMSS

timeStamp()

hours:minute:seconds

Command execution

Various ways of processing commands

xxx(@)

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  

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  

zzz($$$)

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  

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 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  

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    

fileModTime($)

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

     Parameter  Description  
  1  $file      File name    

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:

  fileOutOfDate {make($_)}  $target, $source1, $source2, $source3;

Components

Create file names from file name components

filePath(@)

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  

filePathDir(@)

Directory 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  

filePathExt(@)

File name from file name components and extension.

     Parameter  Description                    
  1  @File      File components and extension  

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  

checkFilePath(@)

Check a folder name constructed from its components

     Parameter  Description      
  1  @file      File components  

checkFilePathExt(@)

Check a file name constructed from its components

     Parameter  Description                    
  1  @File      File components and extension  

checkFilePathDir(@)

Check a folder name constructed from its components

     Parameter  Description      
  1  @file      File components  

quoteFile($)

Quote a file name.

     Parameter  Description  
  1  $file      File name    

removeFilePrefix($@)

Removes a file prefix from an array of files.

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

trackFiles($@)

Track the existence of files

     Parameter  Description  
  1  $label     Label        
  2  @files     Files        

Position

Position in the file system

currentDirectory()

Get the current working directory.

currentDirectoryAbove()

The path to the folder above the current working folder.

parseFileName($)

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

     Parameter  Description         
  1  $file      File name to parse  

containingFolder($)

Path to the folder that contains this file, or use "parseFileName"

     Parameter  Description  
  1  $file      File name    

fullFileName()

Full name of a file.

printFullFileName()

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

Temporary

Temporary files and folders

temporaryFile()

Create a temporary file that will automatically be unlinked during END

temporaryFolder()

Create a temporary folder that will automatically be rmdired during END

temporaryDirectory()

Create a temporary directory that will automatically be rmdired during END

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  

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  

fileList($)

Files that match a given search pattern.

     Parameter  Description     
  1  $pattern   Search pattern  

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.

     Parameter              Description                             
  1  @foldersandExtensions  Mixture of folder names and extensions  

matchPath($)

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

     Parameter  Description  
  1  $file      File name    

findFileWithExtension($@)

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         

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.

     Parameter    Description                                        
  1  $folder      Folder                                             
  2  $limitCount  Maximum number of files to remove to limit damage  

Read and write files

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

readFile($)

Read a file containing unicode.

     Parameter  Description                   
  1  $file      Name of unicode file to read  

readBinaryFile($)

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

     Parameter  Description   
  1  $file      File to read  

makePath($)

Make the path for the specified file name or folder.

     Parameter  Description  
  1  $file      File         

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.

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

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.

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

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             
  2  $string    Non unicode string to write  

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  

binModeAllUtf8()

Set STDOUT and STDERR to accept utf8 without complaint

Images

Image operations

imageSize($)

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

     Parameter  Description            
  1  $image     File containing image  

convertImageToJpx($$$)

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       

convertImageToJpx2($$$)

Convert an image to jpx format - works with: Version: ImageMagick 6.8.9-9 Q16 x86_64 2017-03-14

     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       

Encoding and Decoding

Encode and decode using Json and Mime

encodeJson($)

Encode Perl to Json.

     Parameter  Description     
  1  $string    Data to encode  

decodeJson($)

Decode Perl from Json.

     Parameter  Description     
  1  $string    Data to decode  

encodeBase64($)

Encode a string in base 64.

     Parameter  Description       
  1  $string    String to encode  

decodeBase64($)

Decode a string in base 64.

     Parameter  Description       
  1  $string    String to decode  

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  

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  

Use powerOfTwoX to execute powerOfTwo but die 'powerOfTwo' instead of returning undef

containingPowerOfTwo($)

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

     Parameter  Description      
  1  $n         Number to check  

Use containingPowerOfTwoX to execute containingPowerOfTwo but die 'containingPowerOfTwo' instead of returning undef

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  

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  

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        

Minima and Maxima

Find the smallest and largest elements of arrays

min(@)

Find the minimum number in a list.

     Parameter  Description  
  1  @n         Numbers      

max(@)

Find the maximum number in a list.

     Parameter  Description  
  1  @n         Numbers      

Format

Format data structures as tables

formatTableBasic($$)

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.    

formatTable($$$)

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                   

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  

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  

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  

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  

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  

checkKeys($$)

Check the keys in a hash.

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

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 spelt 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:

   $a->value = 1;

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:

   $a->value == qq(value);

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:

   $a->value->[1] = 2;

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:

   $a->value->{a} = 'b';

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           

isBlank($)

Test whether a string is blank.

     Parameter  Description  
  1  $string    String       

trim($)

Trim off white space from from front and end of string.

     Parameter  Description  
  1  $string    String       

pad($$)

Pad a string with blanks to a multiple of a specified length.

     Parameter  Description  
  1  $string    String       
  2  $length    Tab width    

nws($)

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  

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  

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  

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  

printQw(@)

Print an array of words in qw() format

     Parameter  Description     
  1  @words     Array of words  

Cloud Cover

Useful for operating across the cloud

addCertificate($)

Add a certificate to the current ssh session.

     Parameter  Description                  
  1  $file      File containing certificate  

hostName()

The name of the host we are running on

userId()

The userid we are currently running under

Documentation

Extract, format and update documentation for a perl module

htmlToc($@)

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                                         

updateDocumentation($)

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:

I

method of interest to new users

P

private 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 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  

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         

formatTableAA($$$)

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                   

formatTableHA($$$)

Tabularize a hash of arrays.

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

formatTableAH($$$)

Tabularize an array of hashes.

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

formatTableHH($$$)

Tabularize a hash of hashes.

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

formatTableA($$$)

Tabularize an array.

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

formatTableH($$$)

Tabularize a hash.

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

extractTest($)

Extract a line of a test.

     Parameter  Description                  
  1  $string    String containing test line  

Index

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 min

67 nws

68 pad

69 parseCommandLineArguments

70 parseFileName

71 perlPackage

72 powerOfTwo

73 powerOfTwoX

74 printFullFileName

75 printQw

76 quoteFile

77 readBinaryFile

78 readFile

79 removeFilePrefix

80 renormalizeFolderName

81 searchDirectoryTreesForMatchingFiles

82 setIntersectionOfTwoArraysOfWords

83 setUnionOfTwoArraysOfWords

84 temporaryDirectory

85 temporaryFile

86 temporaryFolder

87 timeStamp

88 trackFiles

89 trim

90 updateDocumentation

91 userId

92 versionCode

93 writeBinaryFile

94 writeFile

95 xxx

96 yyy

97 zzz

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

Author

philiprbrenan@gmail.com

http://www.appaapps.com

Copyright

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.

Acknowledgements

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

mim@cpan.org

Testing on windows