From d90ca16fcbe79ec2889ac33ec339606d84eb8830 Mon Sep 17 00:00:00 2001 From: Guillaume Cottenceau Date: Fri, 18 Apr 2003 20:08:14 +0000 Subject: first alpha pre version of beta of the first draft of a tutorial --- perl-MDK-Common.spec | 7 +- tutorial.html | 327 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 332 insertions(+), 2 deletions(-) create mode 100644 tutorial.html 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 1.1.0-2mdk +- add the tutorial to the -devel package + * Thu Apr 17 2003 Pixel 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 @@ + + + + + + + perl-MDK-Common tutorial + + + + + + +

perl-MDK-Common tutorial v0.1

+ +

Guillaume Cottenceau

+ +

+ + +

Introduction

+ +

This document aims at helping people interested in learning + more on perl-MDK-Common, a Perl library which is intensively + used in MandrakeSoft in-house software development.

+ +

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:

+ +

MDK::Common::File: some useful list/hash functions
MDK::Common::Func: functions suited to functional-style programming
MDK::Common::Globals: allows to share constant values between packages
MDK::Common::Math: some math functions
MDK::Common::String: functions to perform various formatting on strings
MDK::Common::System: system-related useful functions
MDK::Common::Various: other useful functions

+ +

Thanks to perl-MDK-Common's own documentation, an + easy way to directly access information about the provided + functions, you can use perldoc, for example + perldoc MDK::Common::Func will explain the functions + of the Func module. Use perldoc MDK::Common to view + information on all the available functions.

+ +

Additionally, perl-MDK-Common provides a binary + called perl_checker, 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.

+ +

+ + +

Prerequisites

+ +

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): http://www.comp.leeds.ac.uk/Perl/.

+ +

Programming with perl-MDK-Common also emphasizes + the following quality properties on your code:

+ +

no code duplication: 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 + perl-MDK-Common, you need to always keep in mind to + not duplicate code to perform a single action

functional style programming: 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

strict code style: 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; perl_checker will ask you to follow a + specific code style

+ +

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.

+ +

+ + +

Structure of this document

+ +

This document will first try to emphasize the most useful + functions of the perl-MDK-Common 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 + perl_checker will be shown.

+ +

+ + +

Most useful functions

+ +

Note: many functions' name, extending capabilities of + existing functions, or being their functional counterpart, are + suffixed with the underscore character (_); for + example, chomp_ is the equivalent of chomp, + but returns the chomp'ed results instead of modifying its + argument.

+ +

+ cat_(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 + undef. + +
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. cat_ allows to do that easily:
+ +
```
+  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";
+  }
+  
```
+
+ output(FILENAME, LIST): creates a file and outputs the + list (if the file exists, it is clobbered) + +
Counterpart of cat_. Build the contents of the file + in your program, and when you're happy with it, write it on + disk:
+ +
```
+  my @resolv_conf = qw(search mandrakesoft.com);
+  push @resolv_conf, "nameserver $_" foreach @name_servers;
+  output('/etc/resolv.conf', @resolv_conf);
+  
```
+
+ member(SCALAR, LIST): is the value in the list? + +
Returns true if the value is stringwise equivalent to an + element of the list:
+ +
```
+  if (!member($driver, @modules)) {
+      print "Sorry, the driver is not available in our modules.\n"
+  }
+  
```
+
+ difference2(ARRAY REF, ARRAY REF): returns the first + list without the element of the second list + +
Performs a set-wise substraction, e.g. removes in first list + the elements that are members of the second one:
+ +
```
+  my @types = difference2(\@available_types, \@bad_types);
+  print "Please select a type from: @types\n";
+  
```
+
+ uniq(LIST): returns the list with no duplicates + +
Removes duplicates from the list, keeping the order of the + list, and the first element when duplicates.
+ +
```
+  my @types = uniq map { (split)[2] } cat_('/proc/mounts');
+  print "Filesystem types in use: @types\n"
+  
```
+
+ min(LIST): returns the minimum number from a list +
+
+ man(LIST): returns the maximum number from a list +
+
+ chomp_(STRING): non-mutable version of chomp: + do not modify the argument, returns the chomp'ed value. + +
Very useful for simple functional expressions.
+ +
Note: also works on lists: chomp_($a, $b) is + equivalent to chomp($a); chomp($b); ($a,$b).
+ +
```
+  my $pid = chomp_(cat_('/var/run/cardmgr.pid'));
+  
```
+

+ +

+ + +

Other interesting functions

+ +

The following describes functions whose use is not + trivial.

+ +

+ if_(BOOL, LIST) + +
Returns LIST if the BOOL condition is true, else an empty + list.
+ +
Note: it's equivalent as doing BOOL ? LIST : (), + 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 ?:.
+ +
A first convenient use is when you want to loop on a list + and conditionally on another:
+ +
```
+  foreach (@types, if_($arch eq 'ppc', @ppc_types)) {
+      # ...
+  }
```
+ +
It's also useful to select elements from a list and modify + them on-the-fly, e.g. performing the equivalent of a + grep then a map. It works because + Perl automatically concatenates lists.
+ +
```
+  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');
+  
```
+
+ substInFile { CODE } FILENAME: executes the code for + each line of the file; you can know the end of the file is + reached using eof + +
Typically used to change a parameter in a file: + +
```
+  substInFile { s/^FORWARD_IPV4.*\n//; $_ .= "FORWARD_IPV4=true\n" if eof } '/etc/sysconfig/network';
+  
```
+ + +
+ each_index { CODE } LIST: just like each, but + sets $::i + +
Useful when you need to perform an action on each element of + a list, but you also need the index of each element:
+ +
```
+  each_index { printf "%s mountpoint: $_", $::i == 2 ? 'third' : 'other' } cat_('/proc/mounts');
+  
```
+

+ +

+ + +

perl_checker

+ +

+ + +

+ +

+ Last update: Fri Apr 18 22:08:06 2003 +

+ + + + -- cgit v1.2.1