add documentation

4 files changed, 258 insertions, 6 deletions

diff --git a/MDK/Common.pm b/MDK/Common.pm
index dbc161c..5819b01 100644
--- a/MDK/Common.pm
+++ b/MDK/Common.pm
@@ -1,3 +1,45 @@
+=head1 NAME
+
+MDK::Common - miscellaneous functions
+
+=head1 SYNOPSIS
+
+    use MDK::Common;
+    # exports all functions, equivalent to
+
+    use MDK::Common::DataStructure qw(:all);
+    use MDK::Common::File qw(:all);
+    use MDK::Common::Func qw(:all);
+    use MDK::Common::Math qw(:all);
+    use MDK::Common::String qw(:all);
+    use MDK::Common::System qw(:all);
+    use MDK::Common::Various qw(:all);
+
+=head1 DESCRIPTION
+
+C<MDK::Common> is a collection of packages containing various simple functions:
+L<MDK::Common::DataStructure>,
+L<MDK::Common::File>,
+L<MDK::Common::Func>,
+L<MDK::Common::Globals>,
+L<MDK::Common::Math>,
+L<MDK::Common::String>,
+L<MDK::Common::System>,
+L<MDK::Common::Various>.
+
+=head1 EXPORTS
+
+C<MDK::Common> exports the functions in the package mentioned above. See their
+manpage for more.
+
+=head1 COPYRIGHT
+
+Copyright (c) 2001 MandrakeSoft <pixel@mandrakesoft.com>. All rights reserved.
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+
+=cut
+
 package MDK::Common;
 
 use MDK::Common::DataStructure qw(:all);
diff --git a/MDK/Common/Globals.pm b/MDK/Common/Globals.pm
index 32a4fc1..15ca219 100644
--- a/MDK/Common/Globals.pm
+++ b/MDK/Common/Globals.pm
@@ -4,11 +4,11 @@ Shares constant values between modules
 
 =head1 SYNOPSIS
 
-use MDK::Common::Globals "foo", qw($a $b);
-
-MDK::Common::Globals::init(a => 2, b => 3);
-
-print $a;  # 2
+    use MDK::Common::Globals "foo", qw($a $b);
+    
+    MDK::Common::Globals::init(a => 2, b => 3);
+    
+    print $a;  # 2
 
 =cut
 
diff --git a/MDK/Common/Math.pm b/MDK/Common/Math.pm
index 5b46f29..81a12ae 100644
--- a/MDK/Common/Math.pm
+++ b/MDK/Common/Math.pm
@@ -1,8 +1,119 @@
+=head1 NAME
+
+MDK::Common::Math - miscellaneous math functions
+
+=head1 SYNOPSIS
+
+    use MDK::Common::Math qw(:all);
+
+=head1 EXPORTS
+
+=over
+
+=item $PI
+
+the well-known constant 
+
+=item even(INT)
+
+=item odd(INT)
+
+is the number even or odd?
+
+=item sqr(FLOAT)
+
+C<sqr(3)> gives C<9>
+
+=item sign(FLOAT)
+
+returns a value in { -1, 0, 1 }
+
+=item round(FLOAT)
+
+C<round(1.2)> gives C<1>, C<round(1.6)> gives C<2>
+
+=item round_up(FLOAT, INT)
+
+returns the number rounded up to the modulo:
+C<round_up(11,10)> gives C<20>
+
+=item round_down(FLOAT, INT)
+
+returns the number rounded down to the modulo:
+C<round_down(11,10)> gives C<10>
+
+=item divide(INT, INT)
+
+integer division (which is lacking in perl). In array context, also returns the remainder:
+C<($a, $b) = divide(10,3)> gives C<$a is 3> and C<$b is 1>
+
+=item min(LIST)
+
+=item max(LIST)
+    
+returns the minimum/maximum number in the list
+
+=item or_(LIST)
+
+is there a true value in the list?
+
+=item and_(LIST)
+
+are all values true in the list?
+
+=item sum(LIST)
+
+=item product(LIST)
+
+returns the sum/product of all the element in the list
+
+=item factorial(INT)
+
+C<factorial(4)> gives C<24> (4*3*2)
+
+=back
+
+=head1 OTHER
+
+the following functions are provided, but not exported:
+
+=over
+
+=item factorize(INT)
+
+C<factorize(40)> gives C<([2,3], [5,1])> as S<40 = 2^3 + 5^1>
+
+=item decimal2fraction(FLOAT)
+
+C<decimal2fraction(1.3333333333)> gives C<(4, 3)> 
+($PRECISION is used to decide which precision to use)
+
+=item poly2(a,b,c)
+
+Solves the a*x2+b*x+c=0 polynomial:
+C<poly2(1,0,-1)> gives C<(1, -1)>
+
+=item permutations(n,p)
+
+A(n,p)
+
+=item combinaisons(n,p)
+
+C(n,p)
+
+=back
+
+=head1 SEE ALSO
+
+L<MDK::Common>
+
+=cut
+
 package MDK::Common::Math;
 
 use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK $PRECISION $PI);
 @ISA = qw(Exporter);
-@EXPORT_OK = qw($PI even odd sqr sign round round_up round_down divide min max or_ and_ sum product factorize decimal2fraction poly2);
+@EXPORT_OK = qw($PI even odd sqr sign round round_up round_down divide min max or_ and_ sum product factorial);
 %EXPORT_TAGS = (all => [ @EXPORT_OK ]);
 
 
@@ -62,4 +173,24 @@ sub poly2 {
     (-$b + $d) / 2 / $a, (-$b - $d) / 2 / $a
 }
 
+# A(n,p)
+sub permutations {
+    my ($n, $p) = @_;
+    my ($r, $i);
+    for ($r = 1, $i = 0; $i < $p; $i++) {
+	$r *= $n - $i;
+    }
+    $r
+}
+
+# C(n,p)
+sub combinaisons {
+    my ($n, $p) = @_;
+
+    permutations($n, $p) / factorial($p)
+}
+
+sub factorial { permutations($_[0], $_[0]) }
+
+
 1;
diff --git a/MDK/Common/Various.pm b/MDK/Common/Various.pm
index 93fbb80..a8de5fb 100644
--- a/MDK/Common/Various.pm
+++ b/MDK/Common/Various.pm
@@ -1,3 +1,82 @@
+=head1 NAME
+
+MDK::Common::Various - miscellaneous functions
+
+=head1 SYNOPSIS
+
+    use MDK::Common::Various qw(:all);
+
+=head1 EXPORTS
+
+=over 
+
+=item first(LIST)
+
+returns the first value. C<first(XXX)> is an alternative for C<((XXX)[0])>
+
+=item second(LIST)
+
+returns the second value. C<second(XXX)> is an alternative for C<((XXX)[1])>
+
+=item top(LIST)
+
+returns the last value. C<top(@l)> is an alternative for C<$l[$#l]>
+
+=item to_bool(SCALAR)
+
+returns a value in { 0, 1 }
+
+=item to_int(STRING)
+
+extracts the number from the string. You could use directly C<int "11 foo">, but
+you'll get I<Argument "11 foo" isn't numeric in int>. It also handles returns
+11 for C<"foo 11 bar">
+
+=item to_float(STRING)
+
+extract a decimal number from the string
+
+=item bool2text(SCALAR)
+
+returns a value in { "true", "false" }
+
+=item bool2yesno(SCALAR)
+
+returns a value in { "yes", "no" }
+
+=item text2bool(STRING)
+
+inverse of C<bool2text> and C<bool2yesno>
+
+=item chomp_(STRING)
+
+non-mutable version of chomp: do not modify the argument, returns the chomp'ed
+value. Also works on lists: C<chomp_($a, $b)> is equivalent to 
+C<chomp($a) ; chomp($b) ; ($a,$b)>
+
+=item backtrace()
+
+returns a string describing the backtrace. eg: 
+
+    sub g { print "oops\n", backtrace() }
+    sub f { &g }
+    f();
+
+gives
+
+    oops
+    main::g() called from /tmp/t.pl:2
+    main::f() called from /tmp/t.pl:4
+    
+=back
+
+=head1 SEE ALSO
+
+L<MDK::Common>
+
+=cut
+  
+
 package MDK::Common::Various;
 
 use vars qw(@ISA %EXPORT_TAGS @EXPORT_OK);