1Bio::Root::Utilities(3)User Contributed Perl DocumentatioBnio::Root::Utilities(3)
2
6 Bio::Root::Utilities - General-purpose utility module
7
9 Object Creation
10 # Using the supplied singleton object:
11 use Bio::Root::Utilities qw(:obj);
12 $Util->some_method();
13 # Create an object manually:
15 use Bio::Root::Utilities;
16 my $util = Bio::Root::Utilities->new();
17 $util->some_method();
18 $date_stamp = $Util->date_format('yyy-mm-dd');
20 $clean = $Util->untaint($dirty);
22 $compressed = $Util->compress('/home/me/myfile.txt')
24 my ($mean, $stdev) = $Util->mean_stdev( @data );
26 $Util->authority("me@example.com");
28 $Util->mail_authority("Something you should know about...");
29 ...and a host of other methods. See below.
31
33 Provides general-purpose utilities of potential interest to any Perl
34 script.
35 The ":obj" tag is a convenience that imports a $Util symbol into your
37 namespace representing a Bio::Root::Utilities object. This saves you
38 from creating your own Bio::Root::Utilities object via
39 "Bio::Root::Utilities->new()" or from prefixing all method calls with
40 "Bio::Root::Utilities", though feel free to do these things if desired.
41 Since there should normally not be a need for a script to have more
42 than one Bio::Root::Utilities object, this module thus comes with it's
43 own singleton.
44
46 This module is included with the central Bioperl distribution:
47 http://www.bioperl.org/wiki/Getting_BioPerl
49 ftp://bio.perl.org/pub/DIST
50 Follow the installation instructions included in the README file.
52
54 Inherits from Bio::Root::Root, and uses Bio::Root::IO and
55 Bio::Root::Exception.
56 Relies on external executables for file compression/uncompression and
58 sending mail. No paths to these are hard coded but are located as
59 needed.
60
62 http://bioperl.org - Bioperl Project Homepage
63
65 Mailing Lists
66 User feedback is an integral part of the evolution of this and other
67 Bioperl modules. Send your comments and suggestions preferably to one
68 of the Bioperl mailing lists. Your participation is much appreciated.
69 bioperl-l@bioperl.org - General discussion
71 http://bioperl.org/wiki/Mailing_lists - About the mailing lists
72 Support
74 Please direct usage questions or support issues to the mailing list:
75 bioperl-l@bioperl.org
77 rather than to the module maintainer directly. Many experienced and
79 reponsive experts will be able look at the problem and quickly address
80 it. Please include a thorough description of the problem with code and
81 data examples if at all possible.
82 Reporting Bugs
84 Report bugs to the Bioperl bug tracking system to help us keep track
85 the bugs and their resolution. Bug reports can be submitted via the
86 web:
87 http://bugzilla.open-bio.org/
89
91 Steve Chervitz <sac@bioperl.org>
92 See the FEEDBACK section for where to send bug reports and comments.
94
96 This module was originally developed under the auspices of the
97 Saccharomyces Genome Database: http://www.yeastgenome.org/
98
100 Copyright (c) 1996-2007 Steve Chervitz. All Rights Reserved. This
101 module is free software; you can redistribute it and/or modify it under
102 the same terms as Perl itself.
103
105 Methods beginning with a leading underscore are considered private and
106 are intended for internal use by this module. They are not considered
107 part of the public interface and are described here for documentation
108 purposes only.
109 date_format
111 Title : date_format
112 Usage : $Util->date_format( [FMT], [DATE])
113 Purpose : -- Get a string containing the formated date or time
114 : taken when this routine is invoked.
115 : -- Provides a way to avoid using `date`.
116 : -- Provides an interface to localtime().
117 : -- Interconverts some date formats.
118 :
119 : (For additional functionality, use Date::Manip or
120 : Date::DateCalc available from CPAN).
121 Example : $Util->date_format();
122 : $date = $Util->date_format('yyyy-mmm-dd', '11/22/92');
123 Returns : String (unless 'list' is provided as argument, see below)
124 :
125 : 'yyyy-mm-dd' = 1996-05-03 # default format.
126 : 'yyyy-dd-mm' = 1996-03-05
127 : 'yyyy-mmm-dd' = 1996-May-03
128 : 'd-m-y' = 3-May-1996
129 : 'd m y' = 3 May 1996
130 : 'dmy' = 3may96
131 : 'mdy' = May 3, 1996
132 : 'ymd' = 96may3
133 : 'md' = may3
134 : 'year' = 1996
135 : 'hms' = 23:01:59 # when not converting a format, 'hms' can be
136 : # tacked on to any of the above options
137 : # to add the time stamp: eg 'dmyhms'
138 : 'full' | 'unix' = UNIX-style date: Tue May 5 22:00:00 1998
139 : 'list' = the contents of localtime(time) in an array.
140 Argument : (all are optional)
141 : FMT = yyyy-mm-dd | yyyy-dd-mm | yyyy-mmm-dd |
142 : mdy | ymd | md | d-m-y | hms | hm
143 : ('hms' may be appended to any of these to
144 : add a time stamp)
145 :
146 : DATE = String containing date to be converted.
147 : Acceptable input formats:
148 : 12/1/97 (for 1 December 1997)
149 : 1997-12-01
150 : 1997-Dec-01
151 Throws :
152 Comments : If you don't care about formatting or using backticks, you can
153 : always use: $date = `date`;
154 :
155 : For more features, use Date::Manip.pm, (which I should
156 : probably switch to...)
157 See Also : file_date(), month2num()
159 month2num
161 Title : month2num
162 Purpose : Converts a string containing a name of a month to integer
163 : representing the number of the month in the year.
164 Example : $Util->month2num("march"); # returns 3
165 Argument : The string argument must contain at least the first
166 : three characters of the month's name. Case insensitive.
167 Throws : Exception if the conversion fails.
168 num2month
170 Title : num2month
171 Purpose : Does the opposite of month2num.
172 : Converts a number into a string containing a name of a month.
173 Example : $Util->num2month(3); # returns 'Mar'
174 Throws : Exception if supplied number is out of range.
175 compress
177 Title : compress
178 Usage : $Util->compress(full-path-filename);
179 : $Util->compress(<named parameters>);
180 Purpose : Compress a file.
181 Example : $Util->compress("/usr/people/me/data.txt");
182 : $Util->compress(-file=>"/usr/people/me/data.txt",
183 : -tmp=>1,
184 : -outfile=>"/usr/people/share/data.txt.gz",
185 : -exe=>"/usr/local/bin/fancyzip");
186 Returns : String containing full, absolute path to compressed file
187 Argument : Named parameters (case-insensitive):
188 : -FILE => String (name of file to be compressed, full path).
189 : If the supplied filename ends with '.gz' or '.Z',
190 : that extension will be removed before attempting to compress.
191 : Optional:
192 : -TMP => boolean. If true, (or if user is not the owner of the file)
193 : the file is compressed to a temp file. If false, file may be
194 : clobbered with the compressed version (if using a utility like
195 : gzip, which is the default)
196 : -OUTFILE => String (name of the output compressed file, full path).
197 : -EXE => Name of executable for compression utility to use.
198 : Will supercede those in @COMPRESSION_UTILS defined by
199 : this module. If the absolute path to the executable is not provided,
200 : it will be searched in the PATH env variable.
201 Throws : Exception if file cannot be compressed.
202 : If user is not owner of the file, generates a warning and compresses to
203 : a tmp file. To avoid this warning, use the -o file test operator
204 : and call this function with -TMP=>1.
205 Comments : Attempts to compress using utilities defined in the @COMPRESSION_UTILS
206 : defined by this module, in the order defined. The first utility that is
207 : found to be executable will be used. Any utility defined in optional -EXE param
208 : will be tested for executability first.
209 : To minimize security risks, the -EXE parameter value is untained using
210 : the untaint() method of this module (in 'relaxed' mode to permit path separators).
211 See Also : uncompress()
213 uncompress
215 Title : uncompress
216 Usage : $Util->uncompress(full-path-filename);
217 : $Util->uncompress(<named parameters>);
218 Purpose : Uncompress a file.
219 Example : $Util->uncompress("/usr/people/me/data.txt");
220 : $Util->uncompress(-file=>"/usr/people/me/data.txt.gz",
221 : -tmp=>1,
222 : -outfile=>"/usr/people/share/data.txt",
223 : -exe=>"/usr/local/bin/fancyzip");
224 Returns : String containing full, absolute path to uncompressed file
225 Argument : Named parameters (case-insensitive):
226 : -FILE => String (name of file to be uncompressed, full path).
227 : If the supplied filename ends with '.gz' or '.Z',
228 : that extension will be removed before attempting to uncompress.
229 : Optional:
230 : -TMP => boolean. If true, (or if user is not the owner of the file)
231 : the file is uncompressed to a temp file. If false, file may be
232 : clobbered with the uncompressed version (if using a utility like
233 : gzip, which is the default)
234 : -OUTFILE => String (name of the output uncompressed file, full path).
235 : -EXE => Name of executable for uncompression utility to use.
236 : Will supercede those in @UNCOMPRESSION_UTILS defined by
237 : this module. If the absolute path to the executable is not provided,
238 : it will be searched in the PATH env variable.
239 Throws : Exception if file cannot be uncompressed.
240 : If user is not owner of the file, generates a warning and uncompresses to
241 : a tmp file. To avoid this warning, use the -o file test operator
242 : and call this function with -TMP=>1.
243 Comments : Attempts to uncompress using utilities defined in the @UNCOMPRESSION_UTILS
244 : defined by this module, in the order defined. The first utility that is
245 : found to be executable will be used. Any utility defined in optional -EXE param
246 : will be tested for executability first.
247 : To minimize security risks, the -EXE parameter value is untained using
248 : the untaint() method of this module (in 'relaxed' mode to permit path separators).
249 See Also : compress()
251 file_date
253 Title : file_date
254 Usage : $Util->file_date( filename [,date_format])
255 Purpose : Obtains the date of a given file.
256 : Provides flexible formatting via date_format().
257 Returns : String = date of the file as: yyyy-mm-dd (e.g., 1997-10-15)
258 Argument : filename = string, full path name for file
259 : date_format = string, desired format for date (see date_format()).
260 : Default = yyyy-mm-dd
261 Thows : Exception if no file is provided or does not exist.
262 Comments : Uses the mtime field as obtained by stat().
263 untaint
265 Title : untaint
266 Purpose : To remove nasty shell characters from untrusted data
267 : and allow a script to run with the -T switch.
268 : Potentially dangerous shell meta characters: &;`'\"|*?!~<>^()[]{}$\n\r
269 : Accept only the first block of contiguous characters:
270 : Default allowed chars = "-\w.', ()"
271 : If $relax is true = "-\w.', ()\/=%:^<>*"
272 Usage : $Util->untaint($value, $relax)
273 Returns : String containing the untained data.
274 Argument: $value = string
275 : $relax = boolean
276 Comments:
277 This general untaint() function may not be appropriate for every situation.
278 To allow only a more restricted subset of special characters
279 (for example, untainting a regular expression), then using a custom
280 untainting mechanism would permit more control.
281 Note that special trusted vars (like $0) require untainting.
283 mean_stdev
285 Title : mean_stdev
286 Usage : ($mean, $stdev) = $Util->mean_stdev( @data )
287 Purpose : Calculates the mean and standard deviation given a list of numbers.
288 Returns : 2-element list (mean, stdev)
289 Argument : list of numbers (ints or floats)
290 Thows : n/a
291 count_files
293 Title : count_files
294 Purpose : Counts the number of files/directories within a given directory.
295 : Also reports the number of text and binary files in the dir
296 : as well as names of these files and directories.
297 Usage : count_files(\%data)
298 : $data{-DIR} is the directory to be analyzed. Default is ./
299 : $data{-PRINT} = 0|1; if 1, prints results to STDOUT, (default=0).
300 Argument : Hash reference (empty)
301 Returns : n/a;
302 : Modifies the hash ref passed in as the sole argument.
303 : $$href{-TOTAL} scalar
304 : $$href{-NUM_TEXT_FILES} scalar
305 : $$href{-NUM_BINARY_FILES} scalar
306 : $$href{-NUM_DIRS} scalar
307 : $$href{-T_FILE_NAMES} array ref
308 : $$href{-B_FILE_NAMES} array ref
309 : $$href{-DIRNAMES} array ref
310 create_filehandle
312 Usage : $object->create_filehandle(<named parameters>);
313 Purpose : Create a FileHandle object from a file or STDIN.
314 : Mainly used as a helper method by read() and get_newline().
315 Example : $data = $object->create_filehandle(-FILE =>'usr/people/me/data.txt')
316 Argument : Named parameters (case-insensitive):
317 : (all optional)
318 : -CLIENT => object reference for the object submitting
319 : the request. Default = $Util.
320 : -FILE => string (full path to file) or a reference
321 : to a FileHandle object or typeglob. This is an
322 : optional parameter (if not defined, STDIN is used).
323 Returns : Reference to a FileHandle object.
324 Throws : Exception if cannot open a supplied file or if supplied with a
325 : reference that is not a FileHandle ref.
326 Comments : If given a FileHandle reference, this method simply returns it.
327 : This method assumes the user wants to read ascii data. So, if
328 : the file is binary, it will be treated as a compressed (gzipped)
329 : file and access it using gzip -ce. The problem here is that not
330 : all binary files are necessarily compressed. Therefore,
331 : this method should probably have a -mode parameter to
332 : specify ascii or binary.
333 See Also : get_newline()
335 get_newline
337 Usage : $object->get_newline(<named parameters>);
338 Purpose : Determine the character(s) used for newlines in a given file or
339 : input stream. Delegates to Bio::Root::Utilities::get_newline()
340 Example : $data = $object->get_newline(-CLIENT => $anObj,
341 : -FILE =>'usr/people/me/data.txt')
342 Argument : Same arguemnts as for create_filehandle().
343 Returns : Reference to a FileHandle object.
344 Throws : Propogates any exceptions thrown by Bio::Root::Utilities::get_newline().
345 See Also : taste_file(), create_filehandle()
347 taste_file
349 Usage : $object->taste_file( <FileHandle> );
350 : Mainly a utility method for get_newline().
351 Purpose : Sample a filehandle to determine the character(s) used for a newline.
352 Example : $char = $Util->taste_file($FH)
353 Argument : Reference to a FileHandle object.
354 Returns : String containing an octal represenation of the newline character string.
355 : Unix = "\012" ("\n")
356 : Win32 = "\012\015" ("\r\n")
357 : Mac = "\015" ("\r")
358 Throws : Exception if no input is read within $TIMEOUT_SECS seconds.
359 : Exception if argument is not FileHandle object reference.
360 : Warning if cannot determine neewline char(s).
361 Comments : Based on code submitted by Vicki Brown (vlb@deltagen.com).
362 See Also : get_newline()
364 file_flavor
366 Usage : $object->file_flavor( <filename> );
367 Purpose : Returns the 'flavor' of a given file (unix, dos, mac)
368 Example : print "$file has flavor: ", $Util->file_flavor($file);
369 Argument : filename = string, full path name for file
370 Returns : String describing flavor of file and handy info about line endings.
371 : One of these is returned:
372 : unix (\n or 012 or ^J)
373 : dos (\r\n or 015,012 or ^M^J)
374 : mac (\r or 015 or ^M)
375 : unknown
376 Throws : Exception if argument is not a file
377 : Propogates any exceptions thrown by Bio::Root::Utilities::get_newline().
378 See Also : get_newline(), taste_file()
380 mail_authority
382 Title : mail_authority
383 Usage : $Util->mail_authority( $message )
384 Purpose : Syntactic sugar to send email to $Bio::Root::Global::AUTHORITY
385 See Also : send_mail()
387 authority
389 Title : authority
390 Usage : $Util->authority('admin@example.com');
391 Purpose : Set/get the email address that should be notified by mail_authority()
392 See Also : mail_authority()
394 send_mail
396 Title : send_mail
397 Usage : $Util->send_mail( named_parameters )
398 Purpose : Provides an interface to mail or sendmail, if available
399 Returns : n/a
400 Argument : Named parameters: (case-insensitive)
401 : -TO => e-mail address to send to
402 : -SUBJ => subject for message (optional)
403 : -MSG => message to be sent (optional)
404 : -CC => cc: e-mail address (optional)
405 Thows : Exception if TO: address appears bad or is missing.
406 : Exception if mail cannot be sent.
407 Comments : Based on TomC's tip at:
408 : http://www.perl.com/CPAN/doc/FMTEYEWTK/safe_shellings
409 :
410 : Using default 'From:' information.
411 : sendmail options used:
412 : -t: ignore the address given on the command line and
413 : get To:address from the e-mail header.
414 : -oi: prevents send_mail from ending the message if it
415 : finds a period at the start of a line.
416 See Also : mail_authority()
418 find_exe
420 Title : find_exe
421 Usage : $Util->find_exe(name);
422 Purpose : Locate an executable (for use in a system() call, e.g.))
423 Example : $Util->find_exe("gzip");
424 Returns : String containing executable that passes the -x test.
425 Returns undef if an executable of the supplied name cannot be found.
426 Argument : Name of executable to be found.
427 : Can be a full path. If supplied name is not executable, an executable
428 : of that name will be searched in all directories in the currently
429 : defined PATH environment variable.
430 Throws : No exceptions, but issues a warning if multiple paths are found
431 : for a given name. The first one is used.
432 Comments : TODO: Confirm functionality on all bioperl-supported platforms.
433 May get tripped up by variation in path separator character used
434 for splitting ENV{PATH}.
435 See Also :
436 yes_reply
438 Title : yes_reply()
439 Usage : $Util->yes_reply( [query_string]);
440 Purpose : To test an STDIN input value for affirmation.
441 Example : print +( $Util->yes_reply('Are you ok') ? "great!\n" : "sorry.\n" );
442 : $Util->yes_reply('Continue') || die;
443 Returns : Boolean, true (1) if input string begins with 'y' or 'Y'
444 Argument: query_string = string to be used to prompt user (optional)
445 : If not provided, 'Yes or no' will be used.
446 : Question mark is automatically appended.
447 request_data
449 Title : request_data()
450 Usage : $Util->request_data( [value_name]);
451 Purpose : To request data from a user to be entered via keyboard (STDIN).
452 Example : $name = $Util->request_data('Name');
453 : # User will see: % Enter Name:
454 Returns : String, (data entered from keyboard, sans terminal newline.)
455 Argument: value_name = string to be used to prompt user.
456 : If not provided, 'data' will be used, (not very helpful).
457 : Question mark is automatically appended.
458 verify_version
460 Purpose : Checks the version of Perl used to invoke the script.
461 : Aborts program if version is less than the given argument.
462 Usage : verify_version('5.000')
463perl v5.12.0 2010-04-29 Bio::Root::Utilities(3)