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

Uploaded
author deepakjadmin
date Wed, 20 Jan 2016 11:55:01 -0500
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:73ae111cf86f
1 .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.22)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 . ds -- \(*W-
28 . ds PI pi
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31 . ds L" ""
32 . ds R" ""
33 . ds C` ""
34 . ds C' ""
35 'br\}
36 .el\{\
37 . ds -- \|\(em\|
38 . ds PI \(*p
39 . ds L" ``
40 . ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD. Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 . de IX
53 . tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 . nr % 0
56 . rr F
57 .\}
58 .el \{\
59 . de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear. Run. Save yourself. No user-serviceable parts.
65 . \" fudge factors for nroff and troff
66 .if n \{\
67 . ds #H 0
68 . ds #V .8m
69 . ds #F .3m
70 . ds #[ \f1
71 . ds #] \fP
72 .\}
73 .if t \{\
74 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 . ds #V .6m
76 . ds #F 0
77 . ds #[ \&
78 . ds #] \&
79 .\}
80 . \" simple accents for nroff and troff
81 .if n \{\
82 . ds ' \&
83 . ds ` \&
84 . ds ^ \&
85 . ds , \&
86 . ds ~ ~
87 . ds /
88 .\}
89 .if t \{\
90 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 . \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 . \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 . \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 . ds : e
114 . ds 8 ss
115 . ds o a
116 . ds d- d\h'-1'\(ga
117 . ds D- D\h'-1'\(hy
118 . ds th \o'bp'
119 . ds Th \o'LP'
120 . ds ae ae
121 . ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "FILEUTIL 1"
127 .TH FILEUTIL 1 "2015-03-29" "perl v5.14.2" "MayaChemTools"
128 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 FileUtil
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 use FileUtil;
137 .PP
138 use FileUtil qw(:all);
139 .SH "DESCRIPTION"
140 .IX Header "DESCRIPTION"
141 \&\fBFileUtil\fR module provides the following functions:
142 .PP
143 CheckFileType, ConvertCygwinPath, ExpandFileNames, FileModificationTimeAndDate,
144 FileSize, FormatFileSize, FormattedFileModificationTimeAndDate,
145 GetMayaChemToolsLibDirName, GetUsageFromPod, ParseFileName
146 .SH "FUNCTIONS"
147 .IX Header "FUNCTIONS"
148 .IP "\fBCheckFileType\fR" 4
149 .IX Item "CheckFileType"
150 .Vb 1
151 \& $Status = CheckFileType($FileName, $FileExts);
152 .Ve
153 .Sp
154 Based on \fIFileExts\fR, decides type of \fIFileName\fR and return 1 or 0.
155 .IP "\fBConvertCygwinPath\fR" 4
156 .IX Item "ConvertCygwinPath"
157 .Vb 1
158 \& $NewPath = ConvertCygwinPath($Path);
159 .Ve
160 .Sp
161 Check to see whether \fIPath\fR contains any Cygwin drive specification and convert
162 it into Windows path.
163 .IP "\fBExpandFileNames\fR" 4
164 .IX Item "ExpandFileNames"
165 .Vb 2
166 \& @FilesList = ExpandFileNames(\e@Files, $FileExts);
167 \& @FilesList = ExpandFileNames(\e@Files, $FileExts, $IncludeDirName);
168 .Ve
169 .Sp
170 For each directory name or wild card file name in \fIFiles\fR, generate all file names which
171 correspond to the specification along with match to any extensions in \fIFileExts\fR and return an
172 array \fBFileList\fR containing these file names and other names. \fIIncludeDirName\fR controls
173 controls whether directory prefixes are included in expanded file names. Default is to always
174 append directory name before expanded file name.
175 .Sp
176 Notes:
177 .Sp
178 .Vb 10
179 \& . Multiple file extensions are delimited by spaces.
180 \& . Wild card, *, is supported in directory and file names along with file
181 \& extensions.
182 \& . For a specified directory name in the files list, all the files in the
183 \& directory are retrieved using Perl opendir function and files filtered using file
184 \& extensions. The file names "." and ".." returned by opendir are ignored.
185 \& . For file names containing wild cards with and without any explicit file
186 \& extension specification in the file name, all the files in the directory are retrieved
187 \& using Perl opendir function and files filtered using file name along with any
188 \& file extension. The file names "." and ".." returned by opendir are ignored.
189 .Ve
190 .IP "\fBFormattedFileModificationTimeAndDate\fR" 4
191 .IX Item "FormattedFileModificationTimeAndDate"
192 .Vb 2
193 \& ($TimeString, $DateString) =
194 \& FormattedFileModificationTimeAndDate($FileName);
195 .Ve
196 .Sp
197 Returns a formatted time and date string corresponding to \fIFileName\fR modification time.
198 .IP "\fBFileModificationTimeAndDate\fR" 4
199 .IX Item "FileModificationTimeAndDate"
200 .Vb 2
201 \& ($Hours, $Mins, $Secs, $DayName, $MonthName, $Month, $Year) =
202 \& FileModificationTimeAndDate($FileName);
203 .Ve
204 .Sp
205 Returns file modification time and date values for specified \fIFileName\fR.
206 .IP "\fBFormatFileSize\fR" 4
207 .IX Item "FormatFileSize"
208 .Vb 1
209 \& $FormattedSize= FormatFileSize($Size, [$Precision]);
210 .Ve
211 .Sp
212 Formats the file size in bytes to human readable value and returns a formatted file
213 size string.
214 .IP "\fBFileSize\fR" 4
215 .IX Item "FileSize"
216 .Vb 1
217 \& $Size= FileSize($FileName);
218 .Ve
219 .Sp
220 Returns size of \fIFileName\fR in bytes
221 .IP "\fBGetMayaChemToolsLibDirName\fR" 4
222 .IX Item "GetMayaChemToolsLibDirName"
223 .Vb 1
224 \& $MayaChemToolsLibDir = GetMayaChemToolsLibDirName();
225 .Ve
226 .Sp
227 Returns MayaChemTools lib directory name by parsing \fB\s-1INC\s0\fR values to extract
228 \&\fBMAYACHEMTOOLS/lib\fR directory location: first entry in \fB\s-1INC\s0\fR path should contain
229 MayaChemTools lib location.
230 .IP "\fBGetUsageFromPod\fR" 4
231 .IX Item "GetUsageFromPod"
232 .Vb 1
233 \& $ScriptUsage = GetUsageFromPod($AbsoluteScriptPath);
234 .Ve
235 .Sp
236 Generates a \fBScriptUsage\fR string from pod documentation in the script file using
237 pod2text or perdoc.bat Perl utitities.
238 .IP "\fBParseFileName\fR" 4
239 .IX Item "ParseFileName"
240 .Vb 1
241 \& ($FileDir, $FileName, $FileExt) = ParseFileName($FullFileName);
242 .Ve
243 .Sp
244 Splits \fIFullFileName\fR into directory name, file name, and extension. \fBFileDir\fR is
245 set to current directory for absent directory name in \fIFullFileName\fR. And \fIFileExt\fR
246 is set to \s-1NULL\s0 string for \fIFullFileName\fR without any extension.
247 .Sp
248 This function doesn't perform checking ragarding the presence of the directory \fIFileDir\fR
249 and \fIFullFileName\fR and the \fIFullFileName\fR without any extension is assumed to be
250 a file instead of a directory.
251 .SH "AUTHOR"
252 .IX Header "AUTHOR"
253 Manish Sud <msud@san.rr.com>
254 .SH "SEE ALSO"
255 .IX Header "SEE ALSO"
256 TextUtil.pm, TimeUtil.pm
257 .SH "COPYRIGHT"
258 .IX Header "COPYRIGHT"
259 Copyright (C) 2015 Manish Sud. All rights reserved.
260 .PP
261 This file is part of MayaChemTools.
262 .PP
263 MayaChemTools is free software; you can redistribute it and/or modify it under
264 the terms of the \s-1GNU\s0 Lesser General Public License as published by the Free
265 Software Foundation; either version 3 of the License, or (at your option)
266 any later version.