From 1696c19c569ce62fbe585a52ce3cf55a9bedb919 Mon Sep 17 00:00:00 2001 From: Pascal Rigaux Date: Fri, 3 Aug 2001 00:34:48 +0000 Subject: much doc added --- MDK/Common/DataStructure.pm | 2 +- MDK/Common/File.pm | 113 +++++++++++++++++++++++++++++++++----- MDK/Common/Func.pm | 130 ++++++++++++++++++++++++++++++++++++++++++- MDK/Common/String.pm | 58 ++++++++++++++++++++ MDK/Common/System.pm | 131 +++++++++++++++++++++++++++++++++++++++++++- 5 files changed, 416 insertions(+), 18 deletions(-) (limited to 'MDK') diff --git a/MDK/Common/DataStructure.pm b/MDK/Common/DataStructure.pm index d2e1367..ecdb45f 100644 --- a/MDK/Common/DataStructure.pm +++ b/MDK/Common/DataStructure.pm @@ -41,7 +41,7 @@ returns the length of the list. Useful in list (opposed to array) context: sub f { "a", "b" } my $l = listlength f(); -where C would return "b" +whereas C would return "b" =item deref(REF) diff --git a/MDK/Common/File.pm b/MDK/Common/File.pm index 834db33..a548237 100644 --- a/MDK/Common/File.pm +++ b/MDK/Common/File.pm @@ -1,3 +1,90 @@ +=head1 NAME + +MDK::Common::File - miscellaneous file/filename manipulation functions + +=head1 SYNOPSIS + + use MDK::Common::File qw(:all); + +=head1 EXPORTS + +=over + +=item dirname(FILENAME) + +=item basename(FILENAME) + +returns the dirname/basename of the file name + +=item cat_(FILENAME) + +returns the file content: in scalar context it returns a single string, in +array context it returns the lines. + +If the file doesn't exist, it returns undef + +=item cat__(FILEHANDLE REF) + +returns the file content: in scalar context it returns a single string, in +array context it returns the lines + +=item output(FILENAME, LIST) + +creates a file and outputs the list (if the file exists, it is clobbered) + +=item linkf(SOURCE, DESTINATION) + +=item symlinkf(SOURCE, DESTINATION) + +=item renamef(SOURCE, DESTINATION) + +same as link/symlink/rename but removes the destination file first + +=item touch(FILENAME) + +ensure the file exists, set the modification time to current time + +=item all(DIRNAME) + +returns all the file in directory (except "." and "..") + +=item glob_(STRING) + +simple version of C: doesn't handle wildcards in directory (eg: +*/foo.c), nor special constructs (eg: [0-9] or {a,b}) + +=item substInFile { CODE } FILENAME + +executes the code for each line of the file. You can know the end of the file +is reached using C + +=item concat_symlink(DIRNAME, RELATIVE LINK) + +concat dirname and the symlink and removes "../" if possible: +C gives "/bin/ls" + +=item expand_symlinks(FILENAME) + +expand the symlinks in the absolute filename: +C gives "/usr/X11R6/bin/XFree86" + +=item openFileMaybeCompressed(FILENAME) + +opens the file and returns the file handle. If the file is not found, tries to +gunzip the file + .gz + +=item catMaybeCompressed(FILENAME) + +cat_ alike. If the file is not found, tries to gunzip the file + .gz + +=back + +=head1 SEE ALSO + +L + +=cut + package MDK::Common::File; use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK); @@ -7,7 +94,7 @@ use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK); sub dirname { local $_ = shift; s|[^/]*/*\s*$||; s|(.)/*$|$1|; $_ || '.' } sub basename { local $_ = shift; s|/*\s*$||; s|.*/||; $_ } -sub cat_ { local *F; open F, $_[0] or $_[1] ? die "cat of file $_[0] failed: $!\n" : return; my @l = ; wantarray ? @l : join '', @l } +sub cat_ { local *F; open F, $_[0] or return; my @l = ; wantarray ? @l : join '', @l } sub cat__ { my ($f) = @_; my @l = <$f>; wantarray ? @l : join '', @l } sub output { my $f = shift; local *F; open F, ">$f" or die "output in file $f failed: $!\n"; print F foreach @_; } sub linkf { unlink $_[1]; link $_[0], $_[1] } @@ -49,19 +136,17 @@ sub glob_ { sub substInFile(&@) { - my $f = shift; - foreach my $file (@_) { - if (-e $file) { - local @ARGV = $file; - local ($^I, $_) = ''; - while (<>) { &$f($_); print } - } else { - local *F; my $old = select F; # that way eof return true - local $_ = ''; - &$f($_); - select $old; - eval { output($file, $_) }; - } + my ($f, $file) = @_; + if (-e $file) { + local @ARGV = $file; + local ($^I, $_) = ''; + while (<>) { &$f($_); print } + } else { + local *F; my $old = select F; # that way eof return true + local $_ = ''; + &$f($_); + select $old; + eval { output($file, $_) }; } } diff --git a/MDK/Common/Func.pm b/MDK/Common/Func.pm index 1b30a7e..fb7157f 100644 --- a/MDK/Common/Func.pm +++ b/MDK/Common/Func.pm @@ -1,3 +1,131 @@ +=head1 NAME + +MDK::Common::Func - miscellaneous functions + +=head1 SYNOPSIS + + use MDK::Common::Func qw(:all); + +=head1 EXPORTS + +=over + +=item may_apply(CODE REF, SCALAR) + +C is C<$f ? $f-E($v) : $v> + +=item may_apply(CODE REF, SCALAR, SCALAR) + +C is C<$f ? $f-E($v) : $otherwise> + +=item if_(BOOL, LIST) + +special constructs to workaround a missing perl feature: +C is C<$b ? ("a", "b") : ()> + +example of use: C which is not the +same as C + +=item if__(SCALAR, LIST) + +if_ alike. Test if the value is defined + +=item fold_left { CODE } LIST + +if you don't know fold_left (aka foldl), don't use it ;p + + fold_left { $::a + $::b } 1, 3, 6 + +gives 10 (aka 1+3+6) + +=item mapn { CODE } ARRAY REF, ARRAY REF, ... + +map lists in parallel: + + mapn { $_[0] + $_[1] } [1, 2], [2, 4] # gives 3, 6 + mapn { $_[0] + $_[1] + $_[2] } [1, 2], [2, 4], [3, 6] gives 6, 12 + +=item mapn_ { CODE } ARRAY REF, ARRAY REF, ... + +mapn alike. The difference is what to do when the lists have not the same +length: mapn takes the minimum common elements, mapn_ takes the maximum list +length and extend the lists with undef values + +=item map_index { CODE } LIST + +just like C, but set C<$::i> to the current index in the list: + + map_index { "$::i $_" } "a", "b" + +gives "0 a", "1 b" + +=item grep_index { CODE } LIST + +just like C, but set C<$::i> to the current index in the list: + + grep_index { $::i == $_ } 0, 2, 2, 3 + +gives (0, 2, 3) + +=item find_index { CODE } LIST + +returns the index of the first element where CODE returns true + + find_index { /foo/ } "fo", "fob", "foobar", "foobir" + +gives 2 + +=item map_each { CODE } HASH + +returns the list of results of CODE applied with $::a (key) and $::b (value) + + map_each { "$::a is $::b" } 1=>2, 3=>4 + +gives "1 is 2", "3 is 4" + +=item grep_each { CODE } HASH + +returns the hash key/value for which CODE applied with $::a (key) and $::b +(value) is true: + + grep_each { $::b == 2 } 1=>2, 3=>4, 4=>2 + +gives 1=>2, 4=>2 + +=item before_leaving { CODE } + +the code will be executed when the current block is finished + + # create $tmp_file + my $b = before_leaving { unlink $tmp_file }; + # some code that may throw an exception, the "before_leaving" ensures the + # $tmp_file will be removed + +=item cdie(SCALAR) + +aka I. If a C is catched, the execution continues +B the cdie, not where it was catched (as happens with die & eval) + +If a C is not catched, it mutates in real exception that can be catched +with C + +cdie is useful when you want to warn about something weird, but when you can +go on. In that case, you cdie "something weird happened", and the caller +decide wether to go on or not. Especially nice for libraries. + +=item catch_cdie { CODE1 } sub { CODE2 } + +If a C occurs while executing CODE1, CODE2 is executed. If CODE2 +returns true, the C is catched. + +=back + +=head1 SEE ALSO + +L + +=cut + package MDK::Common::Func; use MDK::Common::Math; @@ -29,7 +157,7 @@ sub fold_left(&@) { my ($f, $initial, @l) = @_; local ($::a, $::b); $::a = $initial; - foreach $::b (@_) { $::a = &$f() } + foreach $::b (@l) { $::a = &$f() } $::a } diff --git a/MDK/Common/String.pm b/MDK/Common/String.pm index 74b8e2b..3faa270 100644 --- a/MDK/Common/String.pm +++ b/MDK/Common/String.pm @@ -1,3 +1,61 @@ +=head1 NAME + +MDK::Common::String - formatting functions + +=head1 SYNOPSIS + + use MDK::Common::String qw(:all); + +=head1 EXPORTS + +=over + +=item bestMatchSentence(STRING, LIST) + +finds in the list the best corresponding string + +=item formatList(INT, LIST) + +if the list size is bigger than INT, replace the remaining elements with "...". + +formatList(3, qw(a b c d e)) # => "a, b, c, ..." + +=item formatError(STRING) + +the string is something like "error at foo.pl line 2" that you get when +catching an exception. formatError will remove the "at ..." so that you can +nicely display the returned string to the user + +=item formatTimeRaw(TIME) + +the TIME is an epoch as returned by C