/ 
Data-Table-Text-20180723
River stage two • 38 direct dependents • 38 total dependents
/ Data::Table::Text 
my $imageTarget  = fpe($imageDir, $imageNumber, $type);                 # Image file target after conversion
my $imageTargetX = fpe($imageDir, $imageNumber, $ext);                  # Image file target after intermediate conversion
my $imageTargetR = sub                                                  # Image file relative to Dita
 {fpe(qw(images), $imageNumber, $type)
 }->();

if ($project->energistics)                                              # EO21 EO22 Image naming convention for Energistics and auto convert file to run on windows
 {my $n = $projectGroup;
  my $v = $project->energisticsVersion;
  my $N = substr(('0'x6).$imageNumber, -6) =~ s((\d\d\d)(\d)) ($1-$2)gr;
  my $i = $n.q(_IMAGES);                                                # Images sub folder
  my $f = $n."-$N-0-$v";                                                # Image file name
  $imageTarget  = fpe($outDir, $n, $n.q(_TOPICS), $i, $f, $type);
  $imageTargetX = fpe($outDir, $n, $n.q(_TOPICS), $i, $f, $ext);
  makePath($imageTarget);
  $imageTargetR = fpe($i, $f, $type);                                   # Image file relative to Dita

# https://www.imagemagick.org/discourse-server/viewtopic.php?t=20611 - convert emf to png on Windows if ($ext) # External conversion script {my $dir = q(..\\).$n.q(\\).$n.q(_TOPICS); push @imageConversionsOnWindows, q("C:\Program Files\ImageMagick-7.0.7-Q16\magick.exe" ). qq(-density $imageDensity $dir\\$i\\$f.$ext $dir\\$i\\$f.$type); } }

if ($im)                                                                # Decoded intermediate via image magick running locally
 {my $f = filePathExt($imageNumber, $im);                               # Intermediate file type
  writeFile($imageUue, "begin-base64 664 $f\n$i====");                  # Uudecode to .emf
  zzz(<<"END");                                                         # Image conversion commands
cd "$imageDirTmp" && uudecode < $imageUue
convert -density 600 "$f" "$imageTarget"
END
 }
elsif ($ext)                                                            # Decoded intermediate via image magick running remotely on Windows
 {my $f = filePathExt($imageNumber, $ext);                              # Intermediate file type
  writeFile($imageUue, "begin-base64 664 $imageTargetX\n$i====");       # Uudecode to internediate type
  zzz(<<"END");                                                         # Image conversion commands
cd "$imageDirTmp" && uudecode < $imageUue
END
 }
else                                                                    # Decode directly
 {writeFile($imageUue, "begin-base64 664 $imageTarget\n$i====");        # Uudecode
  makePath($imageTarget);
  zzz(<<"END");                                                         # Image conversion commands
cd "$imageDirTmp" && uudecode < "$imageUue"
END
 }

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

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.

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

versionCodeDashed()

YYYmmdd-HHMMSS

timeStamp()

hours:minute:seconds

microSecondsSinceEpoch()

Micro seconds since unix epoch

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
4  $message     Message of explanation if any of the checks fail

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

call(&@)

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

Example:

ˢ{our @a = qw(1);

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;

firstFileThatExists(@)

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

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.

absFromAbsPlusRel($$)

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

relFromAbsAgainstAbs($$)

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

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

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 or undef for a temporary file
2  $string    Unicode string to write

writeFiles($$)

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

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

convertImageToJpx690($$$)

Convert an image to jpx format using versions of ImageMagick version 6.9.0 and above

   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.

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 spelled 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';

assertRef(@)

Confirm that the specified references are to the package into which this routine has been exported.

   Parameter  Description
1  @refs      References

ˢ(&)

Immediately executed inline sub to allow a code block before if.

   Parameter  Description
1  $sub       Sub as {} without the word "sub"

Example:

ok ˢ{1};

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

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

saveSourceToS3($$)

Save source code

   Parameter               Description
1  $aws                    Aws target file and keywords
2  $saveIntervalInSeconds  Save internal

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

extractTest($)

Extract a line of a test.

   Parameter  Description
1  $string    String containing test line

Index

1 absFromAbsPlusRel

2 addCertificate

3 appendFile

4 assertRef

5 binModeAllUtf8

6 call

7 checkFile

8 checkFilePath

9 checkFilePathDir

10 checkFilePathExt

11 checkKeys

12 clearFolder

13 containingFolder

14 containingPowerOfTwo

15 containingPowerOfTwoX

16 contains

17 convertImageToJpx690

18 convertUnicodeToXml

19 createEmptyFile

20 currentDirectory

21 currentDirectoryAbove

22 dateStamp

23 dateTimeStamp

24 decodeBase64

25 decodeJson

26 denormalizeFolderName

27 encodeBase64

28 encodeJson

29 extractTest

30 fileList

31 fileModTime

32 fileOutOfDate

33 filePath

34 filePathDir

35 filePathExt

36 fileSize

37 findDirs

38 findFiles

39 findFileWithExtension

40 firstFileThatExists

41 formatTableBasic

42 fullFileName

43 genLValueArrayMethods

44 genLValueHashMethods

45 genLValueScalarMethods

46 genLValueScalarMethodsWithDefaultValues

47 hostName

48 htmlToc

49 imageSize

50 indentString

51 isBlank

52 javaPackage

53 javaPackageAsFileName

54 loadArrayArrayFromLines

55 loadArrayFromLines

56 loadHashArrayFromLines

57 loadHashFromLines

58 makePath

59 matchPath

60 max

61 microSecondsSinceEpoch

62 min

63 nws

64 pad

65 parseCommandLineArguments

66 parseFileName

67 perlPackage

68 powerOfTwo

69 powerOfTwoX

70 printFullFileName

71 printQw

72 quoteFile

73 readBinaryFile

74 readFile

75 relFromAbsAgainstAbs

76 removeFilePrefix

77 renormalizeFolderName

78 saveSourceToS3

79 searchDirectoryTreesForMatchingFiles

80 setIntersectionOfTwoArraysOfWords

81 setUnionOfTwoArraysOfWords

82 temporaryDirectory

83 temporaryFile

84 temporaryFolder

85 timeStamp

86 trackFiles

87 trim

88 updateDocumentation

89 userId

90 versionCode

91 versionCodeDashed

92 writeBinaryFile

93 writeFile

94 writeFiles

95 xxx

96 yyy

97 zzz

98 ˢ

Installation

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

Author

philiprbrenan@gmail.com

http://www.appaapps.com

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.

Acknowledgements

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

mim@cpan.org

Testing on windows

1 POD Error

The following errors were encountered while parsing the POD:

Around line 808:

=pod directives shouldn't be over one line long! Ignoring all 6 lines of content