Name

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

Synopsis

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

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

timeStamp()

hours:minute:seconds

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.

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

Files and paths

Operations on files and paths

Statistics

Information about each file

fileSize($)

Get the size of a file.

1  $file  File name

fileModTime($)

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

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.

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.

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.

1  @file  File components

filePathExt(@)

File name from file name components and extension.

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.

1  $file  File to check

checkFilePath(@)

Check a folder name constructed from its components

1  @file  File components

checkFilePathExt(@)

Check a file name constructed from its components

1  @File  File components and extension

checkFilePathDir(@)

Check a folder name constructed from its components

1  @file  File components

quoteFile($)

Quote a file name.

1  $file  File name

removeFilePrefix($@)

Removes a file prefix from an array of files.

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

Position

Position in the file system

currentDirectory()

Get the current working directory.

userId()

Get the current user id via whoami

currentDirectoryAbove()

The path to the folder above the current working folder.

parseFileName($)

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

1  $file  File name to parse

containingFolder($)

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

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.

1  $dir  Folder to start the search with

findDirs($)

Find all the folders under a folder.

1  $dir  Folder to start the search with

fileList($)

File list.

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.

1  @foldersandExtensions  Mixture of folder names and extensions

matchPath($)

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

1  $file  File name

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.

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.

1  $file  Name of unicode file to read

readBinaryFile($)

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

1  $file  File to read

makePath($)

Make the path for the specified file name or folder.

1  $file  File

writeFile($$)

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

appendFile($$)

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

writeBinaryFile($$)

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

Images

Image operations

imageSize($)

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

1  $image  File containing image

convertImageToJpx($$$)

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

Encoding and Decoding

Encode and decode using Json and Mime

encodeJson($)

Encode Perl to Json.

1  $string  Data to encode

decodeJson($)

Decode Perl from Json.

1  $string  Data to decode

encodeBase64($)

Encode a string in base 64.

1  $string  String to encode

decodeBase64($)

Decode a string in base 64.

1  $string  String to decode

Numbers

Numeric operations

powerOfTwo($)

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

containingPowerOfTwo($)

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

1  $n  Number to check

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

Arrays

Array operations

contains($@)

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

min(@)

Find the minimum number in a list.

1  @n  Numbers

max(@)

Find the maximum number in a list.

1  @n  Numbers

Format

Format data structures as tables

formatTableBasic($$)

Tabularize text - basic version.

1  $data       Data to be formatted
2  $separator  Optional line separator

formatTable($$$)

Format various data structures.

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

keyCount($$)

Count keys down to the specified level.

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.

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.

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.

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.

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

checkKeys($$)

Check the keys in a hash.

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.

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.

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.

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.

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.

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

isBlank($)

Test whether a string is blank.

1  $string  String

trim($)

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

1  $string  String

pad($$)

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

1  $string  String
2  $length  Tab width

nws($)

Normalize white space in a string to make comparisons easier.

1  $string  String to normalize

javaPackage($)

Extract the package name from a java string or file.

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.

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

perlPackage($)

Extract the package name from a perl string or file.

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

Cloud Cover

Useful for operating across the cloud

addCertificate($)

Add a certificate to the current ssh session.

1  $file  File containing certificate

Documentation

Extract, format and update documentation for a perl module

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:

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.

1  $name  Name

renormalizeFolderName($)

Normalize a folder name component by adding a trailing separator.

1  $name  Name

formatTableAA($$$)

Tabularize an array of arrays.

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

formatTableHA($$$)

Tabularize a hash of arrays.

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

formatTableAH($$$)

Tabularize an array of hashes.

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

formatTableHH($$$)

Tabularize a hash of hashes.

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

formatTableA($$$)

Tabularize an array.

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

formatTableH($$$)

Tabularize a hash.

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

extractTest($)

Extract a line of a test.

1  $string  String containing test line

Index

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

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

cpanm Data::Table::Text

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