first alpha pre version of beta of the first draft of a tutorial

author: Guillaume Cottenceau <gc@mandriva.com> 2003-04-18 20:08:14 +0000
committer: Guillaume Cottenceau <gc@mandriva.com> 2003-04-18 20:08:14 +0000
commit: d90ca16fcbe79ec2889ac33ec339606d84eb8830 (patch)
tree: 352895e17a5225c5f2c643754ae26b0ddc03ab81
parent: b4c7d5388840d617fba30d3a3d3cba97e826f6b4 (diff)
download: perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar
perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.gz
perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.bz2
perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.xz
perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.zip
2 files changed, 332 insertions, 2 deletions
diff --git a/perl-MDK-Common.spec b/perl-MDK-Common.spec
index 67d8f6f..8fc1906 100644
--- a/perl-MDK-Common.spec
+++ b/perl-MDK-Common.spec
@@ -2,7 +2,7 @@
 
 # do not change the version here, change in MDK/Common.pm.pl
 %define version THEVERSION
-%define release 1mdk
+%define release 2mdk
 
 Summary: Various simple functions
 Name: perl-MDK-Common
@@ -45,12 +45,15 @@ rm -rf $RPM_BUILD_ROOT
 
 %files devel
 %defattr(-,root,root)
-%doc index.html
+%doc index.html tutorial.html
 %{_bindir}/*
 %{perl_vendorlib}/perl_checker_fake_packages
 
 # MODIFY IN THE CVS: cvs.mandrakesoft.com:/cooker soft/perl-MDK-Common
 %changelog
+* Fri Apr 18 2003 Guillaume Cottenceau <gc@mandrakesoft.com> 1.1.0-2mdk
+- add the tutorial to the -devel package
+
 * Thu Apr 17 2003 Pixel <pixel@mandrakesoft.com> 1.1.0-1mdk
 - MDK::Common::Func: map_index, each_index and grep_index do not pass $::i as
 a parameter anymore (this breaks backward compatibility, but it is cleaner and
diff --git a/tutorial.html b/tutorial.html
new file mode 100644
index 0000000..841472f
--- /dev/null
+++ b/tutorial.html
@@ -0,0 +1,327 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+
+<!--
+     (local-set-key [(meta return)] 
+        	    (ilam (shell-command-on-region (point) (mark) "perl -MMDK::Common")))
+-->
+
+<head>
+  <title>perl-MDK-Common tutorial</title>
+  <link rev="made" href="mailto:gc at mandrake_nospam_soft.com" />
+  <meta name="keywords" content="perl mandrakesoft pixel library functional" />
+</head>
+
+<body bgcolor="#FFFFFF" text="#000000" link="#0000ee" vlink="#551a8b">
+
+  <h1 align="center">perl-MDK-Common tutorial v0.1</h1>
+
+<p><a href="mailto:gc at mandrake_nospam_soft.com">Guillaume Cottenceau</a></p>
+
+<hr />
+
+
+  <h2>Introduction</h2>
+  
+  <p>This document aims at helping people interested in learning
+  more on <tt>perl-MDK-Common</tt>, a Perl library which is intensively
+  used in MandrakeSoft in-house software development.</p>
+
+  <p>The library adds some convenient "basic" functions to Perl,
+  allows easier functional-style programming, and also provides
+  some better system-related operations. It can be seen as an
+  extension to the standard Perl library, adding missing helpful
+  functions. It is divided as follows:</p>
+
+  <ul>
+    <li><tt>MDK::Common::File</tt>: some useful list/hash functions</li>
+    <li><tt>MDK::Common::Func</tt>: functions suited to functional-style programming</li>
+    <li><tt>MDK::Common::Globals</tt>: allows to share constant values between packages</li>
+    <li><tt>MDK::Common::Math</tt>: some math functions</li>
+    <li><tt>MDK::Common::String</tt>: functions to perform various formatting on strings</li>
+    <li><tt>MDK::Common::System</tt>: system-related useful functions</li>
+    <li><tt>MDK::Common::Various</tt>: other useful functions</li>
+  </ul>
+
+  <p>Thanks to <tt>perl-MDK-Common</tt>'s own documentation, an
+  easy way to directly access information about the provided
+  functions, you can use <tt>perldoc</tt>, for example
+  <tt>perldoc MDK::Common::Func</tt> will explain the functions
+  of the Func module. Use <tt>perldoc MDK::Common</tt> to view
+  information on all the available functions.</p>
+
+  <p>Additionally, <tt>perl-MDK-Common</tt> provides a binary
+  called <tt>perl_checker</tt>, which is a Perl compiler aiming
+  at enforcing the use of a subset of Perl, so that all
+  MandrakeSoft Perl programs roughly follow the same code style.
+  It will also help the programmer to remove unneeded parentheses
+  and conditionals.</p>
+
+<hr />
+
+
+  <h2>Prerequisites</h2>
+
+  <p>Of course, a first look at the Perl language will be
+  necessary for the reader. The following can be a good Perl
+  Tutorial (though there are many of them on the web): <a
+  href="http://www.comp.leeds.ac.uk/Perl/">http://www.comp.leeds.ac.uk/Perl/</a>.</p>
+
+  <p>Programming with <tt>perl-MDK-Common</tt> also emphasizes
+  the following quality properties on your code:</p>
+
+  <ul>
+  <li><b>no code duplication:</b> at the grassroots, this library
+  aims at helping you with simple operations you have to deal
+  with so many times in usual programs; this includes reading the
+  contents of a file, finding the maximum numeric element of an
+  array, etc; in order to be efficient with
+  <tt>perl-MDK-Common</tt>, you need to always keep in mind to
+  not duplicate code to perform a single action</li>
+  <br>
+
+  <li><b>functional style programming:</b> this is not a so
+  common technique among programmers, and maybe it's even worse
+  with Perl programmers; but functional-style programs are often
+  clearer, more expressive, more reusable, and more
+  maintainable</li>
+  <br>
+
+  <li><b>strict code style:</b> Perl is known to be a language
+  with which "there is more than one way to do it"; actually,
+  nearly every Perl program uses a different code-style; that's
+  nice for the programmer's freedom, and that's awful for code
+  maintainance; <tt>perl_checker</tt> will ask you to follow a
+  specific code style</li>
+
+  </ul>
+
+  <p>We can't discuss Perl programming without referring to two
+  excellent books from O'Reilly. The first one is called "The
+  Perl Cookbook", and covers many daily problems a Perl
+  programmer will face, in a recipe-like fashion. All Perl
+  programmers should own this book :). The second one can be a
+  good resource for more skillful programmers, and is called
+  "Advanced Perl Programming"; it covers interesting advanced
+  features of Perl.</p>
+
+<hr />
+
+
+  <h2>Structure of this document</h2>
+
+  <p>This document will first try to emphasize the most useful
+  functions of the <tt>perl-MDK-Common</tt> library, e.g. the
+  most commonly used and simple. Then, some functions whose use
+  is not trivial will be explained. As a last part, an
+  introduction to the code-style to please
+  <tt>perl_checker</tt> will be shown.</p>
+
+<hr />
+
+
+  <h2>Most useful functions</h2>
+
+  <p><b>Note:</b> many functions' name, extending capabilities of
+  existing functions, or being their functional counterpart, are
+  suffixed with the underscore character (<tt>_</tt>); for
+  example, <tt>chomp_</tt> is the equivalent of <tt>chomp</tt>,
+  but returns the chomp'ed results instead of modifying its
+  argument.</p>
+
+  <ul>
+  <li>
+   <b>cat_</b>(FILENAME): returns the file contents: in scalar 
+    context it returns a single string, in array context it
+    returns the lines. If the file doesn't exist, it returns
+    <tt>undef</tt>.
+
+  <p>Perl IO operations are verbose and the API is cluttered.
+  There are many situations in which you want to read the
+  contents of a file, put it in a scalar or loop around the
+  files. <tt>cat_</tt> allows to do that easily:</p>
+
+  <pre class="SCREEN">
+  printf "Mandrake release:\n%s\n", cat_('/etc/mandrake-release');
+
+  foreach (cat_('/proc/mounts')) {
+      my ($dev, $where, $type) = split;
+      print "$dev is mounted on $where (type $type)\n";
+  }
+  </pre>
+  </li>
+
+
+  <li>
+   <b>output</b>(FILENAME, LIST): creates a file and outputs the
+    list (if the file exists, it is clobbered)
+
+  <p>Counterpart of <tt>cat_</tt>. Build the contents of the file
+  in your program, and when you're happy with it, write it on
+  disk:</p>
+
+  <pre class="SCREEN">
+  my @resolv_conf = qw(search mandrakesoft.com);
+  push @resolv_conf, "nameserver $_" foreach @name_servers;
+  output('/etc/resolv.conf', @resolv_conf);
+  </pre>
+  </li>
+
+
+  <li>
+   <b>member</b>(SCALAR, LIST): is the value in the list?
+
+  <p>Returns true if the value is stringwise equivalent to an
+  element of the list:</p>
+
+  <pre class="SCREEN">
+  if (!member($driver, @modules)) {
+      print "Sorry, the driver is not available in our modules.\n"
+  }
+  </pre>
+  </li>
+
+
+  <li>
+   <b>difference2</b>(ARRAY REF, ARRAY REF): returns the first
+   list without the element of the second list
+
+  <p>Performs a set-wise substraction, e.g. removes in first list
+  the elements that are members of the second one:</p>
+
+  <pre class="SCREEN">
+  my @types = difference2(\@available_types, \@bad_types);
+  print "Please select a type from: @types\n";
+  </pre>
+  </li>
+
+
+  <li>
+   <b>uniq</b>(LIST): returns the list with no duplicates
+
+  <p>Removes duplicates from the list, keeping the order of the
+  list, and the first element when duplicates.</p>
+
+  <pre class="SCREEN">
+  my @types = uniq map { (split)[2] } cat_('/proc/mounts');
+  print "Filesystem types in use: @types\n"
+  </pre>
+  </li>
+
+
+  <li>
+   <b>min</b>(LIST): returns the minimum number from a list
+   <p></p>
+  </li>
+
+
+  <li>
+   <b>man</b>(LIST): returns the maximum number from a list
+   <p></p>
+  </li>
+
+
+  <li>
+   <b>chomp_</b>(STRING): non-mutable version of <tt>chomp</tt>:
+    do not modify the argument, returns the chomp'ed value.
+
+  <p>Very useful for simple functional expressions.</p>
+
+  <p>Note: also works on lists: <tt>chomp_($a, $b)</tt> is
+  equivalent to <tt>chomp($a); chomp($b); ($a,$b)</tt>.</p>
+
+  <pre class="SCREEN">
+  my $pid = chomp_(cat_('/var/run/cardmgr.pid'));
+  </pre>
+  </li>
+
+
+  </ul>
+
+<hr />
+
+
+  <h2>Other interesting functions</h2>
+
+  <p>The following describes functions whose use is not
+  trivial.</p>
+
+  <ul>
+  <li>
+   <b>if_</b>(BOOL, LIST)
+
+  <p>Returns LIST if the BOOL condition is true, else an empty
+  list.</p>
+
+  <p>Note: it's equivalent as doing <tt>BOOL ? LIST : ()</tt>,
+  except that since it's a function, LIST is evaluated even if
+  BOOL is false. It's useful because it's shorter and more
+  readable than the ternary <tt>?:</tt>.</p>
+
+  <p>A first convenient use is when you want to loop on a list
+  and conditionally on another:</p>
+
+  <pre class="SCREEN">
+  foreach (@types, if_($arch eq 'ppc', @ppc_types)) {
+      # ...
+  }</pre>
+
+  <p>It's also useful to select elements from a list and modify
+  them on-the-fly, e.g. performing the equivalent of a
+  <tt>grep</tt> then a <tt>map</tt>. It works because
+  Perl automatically concatenates lists.</p>
+
+  <pre class="SCREEN">
+  my @md_devices = map { if_(/^(md\d+)/, $1) } cat_('/proc/mdstat');
+
+      # equivalent (but much more elegant!) to:
+
+  my @md_devices = map { /^(md\d+)/; $1 } grep { /^md\d+/ } cat_('/proc/mdstat');
+  </pre>
+  </li>
+
+
+  <li>
+  <b>substInFile</b> { CODE } FILENAME: executes the code for
+    each line of the file; you can know the end of the file is
+    reached using <tt>eof</tt>
+
+  <p>Typically used to change a parameter in a file:
+
+  <pre class="SCREEN">
+  substInFile { s/^FORWARD_IPV4.*\n//; $_ .= "FORWARD_IPV4=true\n" if eof } '/etc/sysconfig/network';
+  </pre>
+
+
+  <li>
+   <b>each_index</b> { CODE } LIST: just like <tt>each</tt>, but
+   sets $::i
+
+  <p>Useful when you need to perform an action on each element of
+  a list, but you also need the index of each element:</p>
+
+  <pre class="SCREEN">
+  each_index { printf "%s mountpoint: $_", $::i == 2 ? 'third' : 'other' } cat_('/proc/mounts');
+  </pre>
+  </li>
+
+
+  </ul>
+
+<hr />
+
+
+  <h2>perl_checker</h2>
+
+  <p></p>
+
+
+<hr />
+
+    <p>
+       Last update: Fri Apr 18 22:08:06 2003
+    </p>
+
+</body>
+
+</html>
author	Guillaume Cottenceau <gc@mandriva.com>	2003-04-18 20:08:14 +0000
committer	Guillaume Cottenceau <gc@mandriva.com>	2003-04-18 20:08:14 +0000
commit	d90ca16fcbe79ec2889ac33ec339606d84eb8830 (patch)
tree	352895e17a5225c5f2c643754ae26b0ddc03ab81
parent	b4c7d5388840d617fba30d3a3d3cba97e826f6b4 (diff)
download	perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.gz perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.bz2 perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.tar.xz perl-MDK-Common-d90ca16fcbe79ec2889ac33ec339606d84eb8830.zip