.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.13) .\" .\" 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 "MNI::MiscUtilities 3" .TH MNI::MiscUtilities 3 "1997-10-03" "perl v5.10.1" "User Contributed Perl Documentation" .\" 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" MNI::MiscUtilities \- miscellaneous and unclassifiable utility routines .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use MNI::MiscUtilities qw(:all); \& \& $when = timestamp ([TIME]) \& \& $whowhere = userstamp ([USER [, HOST [, DIR]]]) \& \& $cmp = lcompare (COMPARE_FN, LIST1, LIST2) \& \& $cmp = nlist_equal (LIST1, LIST2) \& \& $banner = make_banner (MSG [, CHAR [, WIDTH]]) \& \& $cmd_string = shellquote (WORDLIST) .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIMNI::MiscUtilities\fR provides a handful of otherwise unclassifiable utility routines. Don't go looking for a common thread of purpose or operation\-\-\-there isn't one! .IP "timestamp ([\s-1TIME\s0])" 4 .IX Item "timestamp ([TIME])" Formats \s-1TIME\s0 in a complete, unambiguous, ready-to-sort fashion: \&\f(CW\*(C`yyyy\-mm\-dd hh:mm:ss\*(C'\fR. \s-1TIME\s0 defaults to the current time; if it is supplied, it should be a time in the standard C/Unix representation: seconds since 1970\-01\-01 00:00:00 \s-1UTC\s0, as returned by Perl's built-in \&\f(CW\*(C`time\*(C'\fR function. .Sp Returns a string containing the formatted time. .IP "userstamp ([\s-1USER\s0 [, \s-1HOST\s0 [, \s-1DIR\s0]]])" 4 .IX Item "userstamp ([USER [, HOST [, DIR]]])" Forms a useful complement to \f(CW\*(C`timestamp\*(C'\fR; where \f(CW\*(C`timestamp\*(C'\fR tells the \&\*(L"when\*(R" of an action, \f(CW\*(C`userstamp\*(C'\fR gives the \*(L"who\*(R" and \*(L"where\*(R". That is, \&\f(CW\*(C`userstamp\*(C'\fR generates and returns a string containing the current username, host, and working directory, e.g. \f(CW\*(C`user@host:/directory\*(C'\fR. .Sp Normally, no parameters are given to \f(CW\*(C`userstamp\*(C'\fR\-\-\-it uses \f(CW$<\fR (the real uid) and \f(CW\*(C`getpwuid\*(C'\fR to get the username, \f(CW\*(C`Sys::Hostname::hostname\*(C'\fR to get the hostname, and \f(CW\*(C`Cwd::getcwd\*(C'\fR to get the current directory. If you wish to generate a bogus \*(L"userstamp\*(R", though, you may do so by overriding some or all of \f(CW\*(C`userstamp\*(C'\fR's arguments. For instance, to supply a fake directory, but use the defaults for \s-1USER\s0 and \s-1HOST:\s0 .Sp .Vb 1 \& userstamp (undef, undef, \*(Aq/fake/dir\*(Aq); .Ve .IP "lcompare (\s-1COMPARE_FN\s0, \s-1LIST1\s0, \s-1LIST2\s0)" 4 .IX Item "lcompare (COMPARE_FN, LIST1, LIST2)" Compares two lists, element-by-element, and returns \-1, 0, or 1, depending on whether \s-1LIST1\s0 is less than, equal to, or greater than \s-1LIST2\s0. \s-1COMPARE_FN\s0 must be a reference to a subroutine that compares individual elements and returns \-1, 0, or 1 appropriately. The elements to compare are passed in as \f(CW@_\fR, so the body of this subroutine will usually look like \f(CW$_[0] cmp $_[1]\fR or \f(CW$_[0] >=< $_[1]\fR, depending on whether you're dealing with lists of strings or of numbers. \s-1LIST1\s0 and \s-1LIST2\s0 must both be list references. .Sp The semantics of list comparison are identical to those for string comparison. In particular, two lists are equal if and only if they have the same length, and all corresponding pairs of elements are identical. If two lists are of the same length but have different elements at position \&\fIi\fR, then the list with the greater element at position \fIi\fR is greater, regarldess of what comes after position \fIi\fR. If \s-1LIST1\s0 and \s-1LIST2\s0 are identical up to the last element of \s-1LIST2\s0, and \s-1LIST1\s0 is longer, then \s-1LIST1\s0 is greater. If they are identical up to the last element of \s-1LIST1\s0, and \&\s-1LIST2\s0 is longer, then \s-1LIST2\s0 is greater. .Sp For example, the lists in the left-hand column are greater than the lists in the right-hand column: .Sp .Vb 3 \& (3,4,5) (3,4,4) \& (3,4,4) (3,4) \& (3,4,5) (3,4) .Ve .Sp Incidentally, the semantic equivalence of list and string comparison means that, for strings \f(CW$s1\fR and \f(CW$s2\fR, the following is always true: .Sp .Vb 2 \& lcompare (sub { $_[0] cmp $_[1] }, [split (\*(Aq\*(Aq, $s1)], [split (\*(Aq\*(Aq, $s2)]) \& == $s1 cmp $s2 .Ve .IP "nlist_equal (\s-1LIST1\s0, \s-1LIST2\s0)" 4 .IX Item "nlist_equal (LIST1, LIST2)" Uses \f(CW\*(C`lcompare\*(C'\fR to compare two lists of numbers, and returns true if they are equal. \s-1LIST1\s0 and \s-1LIST2\s0 must be list references. Note that the boolean sense of \f(CW\*(C`nlist_equal\*(C'\fR is reversed from that of \f(CW\*(C`lcompare\*(C'\fR, i.e. \f(CW\*(C`nlist_equal\*(C'\fR returns true if \f(CW\*(C`lcompare\*(C'\fR returns 0. .IP "make_banner (\s-1MSG\s0 [, \s-1CHAR\s0 [, \s-1WIDTH\s0]])" 4 .IX Item "make_banner (MSG [, CHAR [, WIDTH]])" Creates and returns a string of the form \f(CW\*(C`\-\- Hello! \-\-\-\-\-\-\-\-\-\-\*(C'\fR (assuming \s-1MSG\s0 is \f(CW\*(Aqhello!\*(Aq\fR, \s-1CHAR\s0 is \f(CW\*(Aq\-\*(Aq\fR, and \s-1WIDTH\s0 is 20. \s-1CHAR\s0 defaults to \f(CW\*(Aq\-\*(Aq\fR, and \s-1WIDTH\s0 defaults to 80 (although I may eventually change this to the width of the terminal). .IP "shellquote (\s-1WORDLIST\s0)" 4 .IX Item "shellquote (WORDLIST)" Performs the opposite of the \fIText::ParseWords\fR module, namely it joins an array of words together, with some sub-strings quoted in order to escape shell meta-characters. \s-1WORDLIST\s0 should just be a list of substrings, not a list reference. This is useful for turning a list of arguments (such as \f(CW@ARGV\fR, or something you're about to pass to Perl's \&\f(CW\*(C`system\*(C'\fR) into a string that looks like what you might type to the shell. .Sp The exact rules are as follows: if a word contains no metacharacters and is not empty, it is untouched. If it contains both single and double quotes (\f(CW\*(C`\*(Aq\*(C'\fR and \f(CW\*(C`"\*(C'\fR), all meta-characters are escaped with a backslash, and no quotes are added. If it contains just single quotes, it is encased in double quotes. Otherwise\-\-\-that is, if it is empty or contains meta-characters other than \f(CW\*(C`\*(Aq\*(C'\fR\-\-\-it is encased in single quotes. .Sp The list of shell meta-characters is taken from the Perl source code (\f(CW\*(C`do_exec()\*(C'\fR, in doio.c), and thus is specific to the Bourne shell: .Sp .Vb 1 \& $ & * ( ) { } [ ] \*(Aq " ; \e | ? < > ~ \` \en .Ve .Sp (plus whitespace). .Sp For example, if \f(CW@ARGV\fR is \f(CW\*(C`("foo", "*.bla")\*(C'\fR, then \&\f(CW\*(C`shellquote (@ARGV)\*(C'\fR will return \f(CW"foo \*(Aq*.bla\*(Aq"\fR\-\-\-thus turning a simple list of arguments into a string that could be given to the shell to re-generate that list of arguments. .SH "AUTHOR" .IX Header "AUTHOR" Greg Ward, . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1997 by Gregory P. Ward, McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. .PP This file is part of the \s-1MNI\s0 Perl Library. It is free software, and may be distributed under the same terms as Perl itself.