comparison mayachemtools/docs/modules/man3/FileUtil.3 @ 0:73ae111cf86f draft

Uploaded

0:73ae111cf86f

.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "FILEUTIL 1"
.TH FILEUTIL 1 "2015-03-29" "perl v5.14.2" "MayaChemTools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
FileUtil
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
use FileUtil;
.PP
use FileUtil qw(:all);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBFileUtil\fR module provides the following functions:
.PP
CheckFileType, ConvertCygwinPath, ExpandFileNames, FileModificationTimeAndDate,
FileSize, FormatFileSize, FormattedFileModificationTimeAndDate,
GetMayaChemToolsLibDirName, GetUsageFromPod, ParseFileName
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBCheckFileType\fR" 4
.IX Item "CheckFileType"
.Vb 1
\&    $Status = CheckFileType($FileName, $FileExts);
.Ve
.Sp
Based on \fIFileExts\fR, decides type of \fIFileName\fR and return 1 or 0.
.IP "\fBConvertCygwinPath\fR" 4
.IX Item "ConvertCygwinPath"
.Vb 1
\&    $NewPath = ConvertCygwinPath($Path);
.Ve
.Sp
Check to see whether \fIPath\fR contains any Cygwin drive specification and convert
it into Windows path.
.IP "\fBExpandFileNames\fR" 4
.IX Item "ExpandFileNames"
.Vb 2
\&    @FilesList = ExpandFileNames(\e@Files, $FileExts);
\&    @FilesList = ExpandFileNames(\e@Files, $FileExts, $IncludeDirName);
.Ve
.Sp
For each directory name or wild card file name in \fIFiles\fR, generate all file names which
correspond to the specification along with match to any extensions in \fIFileExts\fR and return an
array \fBFileList\fR containing these file names and other names. \fIIncludeDirName\fR controls
controls whether directory prefixes are included in expanded file names. Default is to always
append directory name before expanded file name.
.Sp
Notes:
.Sp
.Vb 10
\&    . Multiple file extensions are delimited by spaces.
\&    . Wild card, *, is supported in directory and file names along with file
\&      extensions.
\&    . For a specified directory name in the files list, all the files in the
\&      directory are retrieved using Perl opendir function and files filtered using file
\&      extensions. The file names "." and ".." returned by opendir are ignored.
\&    . For file names containing wild cards with and without any explicit file
\&      extension specification in the file name, all the files in the directory are retrieved
\&      using Perl opendir function and files filtered using file name along with any
\&      file extension. The file names "." and ".." returned by opendir are ignored.
.Ve
.IP "\fBFormattedFileModificationTimeAndDate\fR" 4
.IX Item "FormattedFileModificationTimeAndDate"
.Vb 2
\&    ($TimeString, $DateString) =
\&         FormattedFileModificationTimeAndDate($FileName);
.Ve
.Sp
Returns a formatted time and date string corresponding to \fIFileName\fR modification time.
.IP "\fBFileModificationTimeAndDate\fR" 4
.IX Item "FileModificationTimeAndDate"
.Vb 2
\&    ($Hours, $Mins, $Secs, $DayName, $MonthName, $Month, $Year) =
\&         FileModificationTimeAndDate($FileName);
.Ve
.Sp
Returns file modification time and date values for specified \fIFileName\fR.
.IP "\fBFormatFileSize\fR" 4
.IX Item "FormatFileSize"
.Vb 1
\&    $FormattedSize= FormatFileSize($Size, [$Precision]);
.Ve
.Sp
Formats the file size in bytes to human readable value and returns a formatted file
size string.
.IP "\fBFileSize\fR" 4
.IX Item "FileSize"
.Vb 1
\&    $Size= FileSize($FileName);
.Ve
.Sp
Returns size of \fIFileName\fR in bytes
.IP "\fBGetMayaChemToolsLibDirName\fR" 4
.IX Item "GetMayaChemToolsLibDirName"
.Vb 1
\&    $MayaChemToolsLibDir = GetMayaChemToolsLibDirName();
.Ve
.Sp
Returns MayaChemTools lib directory name by parsing \fB\s-1INC\s0\fR values to extract
\&\fBMAYACHEMTOOLS/lib\fR directory location: first entry in \fB\s-1INC\s0\fR path should contain
MayaChemTools lib location.
.IP "\fBGetUsageFromPod\fR" 4
.IX Item "GetUsageFromPod"
.Vb 1
\&    $ScriptUsage = GetUsageFromPod($AbsoluteScriptPath);
.Ve
.Sp
Generates a \fBScriptUsage\fR string from pod documentation in the script file using
pod2text or perdoc.bat Perl utitities.
.IP "\fBParseFileName\fR" 4
.IX Item "ParseFileName"
.Vb 1
\&    ($FileDir, $FileName, $FileExt) = ParseFileName($FullFileName);
.Ve
.Sp
Splits \fIFullFileName\fR into directory name, file name, and extension. \fBFileDir\fR is
set to current directory for absent directory name in \fIFullFileName\fR. And \fIFileExt\fR
is set to \s-1NULL\s0 string for \fIFullFileName\fR without any extension.
.Sp
This function doesn't perform checking ragarding the presence of the directory \fIFileDir\fR
and \fIFullFileName\fR and the \fIFullFileName\fR without any extension is assumed to be
a file instead of a directory.
.SH "AUTHOR"
.IX Header "AUTHOR"
Manish Sud <[e-mail]>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
TextUtil.pm, TimeUtil.pm
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2015 Manish Sud. All rights reserved.
.PP
This file is part of MayaChemTools.
.PP
MayaChemTools is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option)
any later version.