perltutorial

Threads: why locking is required when using shared variables (ikegami)

I was recently faced with a thread that used .= on a shared variable, and I wondered if that was safe. I figured I'd write up a introductory tutorial on the answer I found. For simplicity, we'll look at ++ first.

The following code outputs 400,000:

my $count     = 100_000;my $num_calls = 4;my $sum = 0;sub inc { ++$sum for 1..$count; }inc() for 1..$num_calls;print("$sum\n");   # 400000

If you ran the 4 calls to inc in parallel, would the answer still be 400,000? Not likely, if you don't change inc.

use threads;use threads::shared;my $count     = 100_000;my $num_calls = 4;my $sum : shared = 0;sub inc { ++$sum for 1..$count; }$_->join for map { threads->create( \&inc ) } 1..$num_calls;print("$sum\n");   # 314813

That's because there is a [wp://race condition].

+=======================+|          CPU          |+-----------+-----------+| thread 1  | thread 2  |+===========+===========+| ...       |           |   T| load $sum |           |   i| inc       |           |   m+-----------+-----------+   e|           | ...       |   ||           | load $sum |   ||           | inc       |   v|           | save $sum ||           | ...       |+-----------+-----------+| save $sum |           || ...       |           |+===========+===========+

The solution is to protect the [wp://critical section] using a thread synchronization mechanism such as lock.

use threads;use threads::shared;my $count     = 100_000;my $num_calls = 4;my $sum : shared = 0;sub inc { for (1..$count) { lock($sum); ++$sum } }$_->join for map { threads->create( \&inc ) } 1..$num_calls;print("$sum\n");   # 400000

Whenever an transformation operation (read ⇒ manipulate ⇒ write) is performed on a shared variable, locking is needed. See [mod://threads::shared] for tools to do this.

The program behind the below outputs results similar to the following:

++s     sum = 233564 (expecting 400000)s+=1    sum = 143915 (expecting 400000)c.=l    length = 248149 (expecting 400000)c=c.l   length = 123360 (expecting 400000)

As you can see, +=, .= and = . are also not atomic. The program can only prove that an operator isn't atomic (i.e. is interruptable). It cannot prove that an operator is atomic (i.e. is not interruptable). If you're getting the "expecting" result, try upping $count and/or $threads.

use v5.8.0;use strict;use warnings;use threads;use threads::shared;{   my $count   = 100_000;   my $threads = 4;   my $sum : shared = 0;   sub inc {      for (1..$count) {         ++$sum;      }   }   $_->join      for map { threads->create( \&inc ) }          0..$threads-1;   print("++s     sum = $sum (expecting " . ($count*$threads). ")\n");}{   my $count   = 100_000;   my $threads = 4;   my $sum : shared = 0;   sub inc_assign {      for (1..$count) {         $sum += 1;      }   }   $_->join      for map { threads->create( \&inc_assign ) }          0..$threads-1;   print("s+=1    sum = $sum (expecting " . ($count*$threads). ")\n");}{   my $count   = 100_000;   my $threads = 4;   my $content : shared = '';   sub append {      my ($letter) = @_;      for (1..$count) {         $content .= $letter;      }   }   $_->join      for map { threads->create( \&append, chr(ord('a')+$_) ) }          0..$threads-1;   print("c.=l    length = " . length($content) .         " (expecting " . ($count*$threads). ")\n");}{   my $count   = 100_000;   my $threads = 4;   my $content : shared = '';   sub concatenate {      my ($letter) = @_;      for (1..$count) {         $content = $content . $letter;      }   }   $_->join      for map { threads->create( \&concatenate, chr(ord('a')+$_) ) }          0..$threads-1;   print("c=c.l   length = " . length($content) .         " (expecting " . ($count*$threads). ")\n");}

Update: Added the preface and links to Wikipedia.

Added to [Tutorials] by [planetscape] ( keep:0 edit:6 reap:0 )

Big-O Notation - What is it good for? (Limbic~Region)

[All],
If you have ever felt that people debating the big-oh notation of some algorithm sound like they are speaking a foreign language, then this tutorial is for you. You may have even decided to educate yourself by checking out the [wp://Big_o_notation|Wikipedia entry] and have been convinced it was a foreign language. You are not alone.

You may have already read [id://227909] by [dws] which is excellent. This tutorial will repeat much of the same information in a much more elementary manner as well as go into detail about how useful or not the notation is. It is likely I won't be completely accurate about a number of things in the tutorial. My hope is that by the end, your understanding of the topic will be sufficient enough that you can understand the corrections others make (as I am sure they will).

What Is The Big-O

This tutorial covers the Big-O as it relates to computer science. If you were thinking of something else (perhaps Fridays in the Chatterbox), you can stop reading now. Simply put, it describes how the algorithm scales (performs) in the worst case scenario as it is is run with more input. Since my simple explanation may not be simple enough - let me give an example. If we have a sub that searches an array item by item looking for a given element, the scenario that the Big-O describes is when the target element is last (or not present at all). This particular algorithm is O(N) so the same algorithm working on an array with 25 elements should take approximately 5 times longer than an array with 5 elements.

It is easy to lose sight of the fact that there is more to consider about an algorithm other than how fast it runs. The Big-O can also be used to describe other behavior such as memory consumption. We often optimize by trading memory for time. You may need to choose a slower algorithm because it also consumes less of a resource that you need to be frugal with.

What The Big-O Is Not

Constants: The Big-O is not concerned with factors that do not change as the input increases. Let me give an example that may be suprising. Let's say we have an algorithm that needs to compare every element in an array to every other element in the array. A simple implementation may look like:

for my $i (0 .. $#array) {    for my $j (0 .. $#array) {        next if $j == $i;        # Compare $i, $j    }}

This is O(N^2). After a little bit of testing we decide that this is far too slow, so we make a little optimization.

for my $i (0 .. $#array - 1) {    for my $j ($i + 1 .. $#array) {        # Compare $i, $j    }}

We have just cut our run time in half - YAY! Guess what, the Big-O has stayed the same O(N^2). This is because N^2 / 2 only has one variable part. The divided by 2 does not affect how the algorithm scales. If you remember a little linear algebra, the slope of a line is the change in height (execution time) as the length (size of input) increases. While the second algorithm's line will always be half as high as the first, it's slope will be exactly the same.

Implementation Details: The Big-O is an uncaring cold-hearted jerk. It does not care if you can't afford to buy the extra RAM needed for your problem and have to resort to tying your hash to disk. You are on your own. It also doesn't care that the data structure you would need to implement to achieve O(Log Log N) is so complex you will never be able to maintain it. In a nutshell, the Big-O lives in the land of theory and doesn't care very much about the real world.

What The Big-O Is Good For

The good news is that the Big-O belongs to an entire family of notation. This tutorial will not cover it but family members include describing the average and best cases. It also serves as a good indicator of what algorithm to use once you take your individual circumstances into consideration. Let me give a contrived example:

Let's consider using cacheing as an optimization. In theory, the Big-O is going to ignore it saying your input is all different and you will never benefit from it. In reality, you test it and discover that you have a 60% hit rate. You do a little more experimenting and discover that the input size required for a more complex algorithm to be faster is larger than your real maximum input size. This all despite the more complex alorithm having a more favorable Big-O.

In a nutshell, the Big-O of a given algorithm combined with the specific problem knowledge is a great way to choose the best algorithm for your situation.

What Do Those Symbols Mean?

So by this point you should realize that Big-O (theory) without context (real world) is not very useful. You are now armed with the knowledge necessary to start using Big-O as the mercenary it is. Ok Big-O, what exactly do you mean that algorithm is O(N Log N)? I am going to duck at this point and suggest you read the node by [dws] or the Wikipedia entry I linked to earlier. You may now be wondering if Big-O is really inanimate, perhaps even an abstract concept and not at all real as I have made it out to be. If so, how then can you determine the Big-O of a given algorithm? [http://algo.inria.fr/AofA/|Analysis of algorithms] is not for the faint of heart, so I must once again duck.

I have not really added anything to any of the other links I referenced. I do hope however that I have put it in plain enough english to be understood by even the most extreme novice. I welcome those more knowledgeable than myself to add corrections as well as provide additional content. I would only ask that you do so in the same spirit of this tutorial (understandable by non-CS majors).

Also see [id://25833] by [jeffa]

Cheers - [Limbic~Region|L~R]

Common Causes for "Modification of a read-only value attempted" (imp)

You tried, directly or indirectly, to change the value of aconstant. This type of error frequently occurs at a distance and is difficult to trace. The magic of $_ is often involved, but is not responsible.

Common causes:

Treating a loop variable as an lvalue
Modifying $_ inside foreach, map or grep
Modifying elements of @_ directly
Modifying $a or $b inside sort
Autovivifying $a or $b inside sort
Modifying an unlocalized $_

Treating a loop variable as an lvalue

for my $x (1,2) {  $x++;}

In this example $x is aliased to the constant '1', so when the loop body attempts to increment $x an error is triggered. See Lists With Constant Values for more details.

Modifying $_ inside [doc://perlsyn#Foreach-Loops-for-foreach|foreach], [doc://map] or [doc://grep]

for (1,2) {  chomp;}for ("foo", @list) {  s/foo/bar/;}@array = map  { $_++ } (1,2);@array = grep { $_++ } (1,2);

In all of these examples $_ is aliased to a constant, and when the loop body attempts to modify $_ an error is triggered. See Lists With Constant Values for more details.

Modifying elements of @_ directly

sub incr {  $_[0]++;}my $n = 1;incr($n); # goodincr(1);  # bad

Modifying elements of @_ directly allows you tomodify the variable that was passed to the function. For example, in the above example $n is now 2. But an error will occur when a constant is passed, as in the second call.

Modifying $a or $b inside [doc://sort]

@array = sort { $a++ } (1,2);

It is permissible (but ill-advised) to modify $a and $b within sort. However, modifying a constant that is aliased to $a or $b is still an error.

Autovivifying $a or $b inside [doc://sort]

my @bad;$bad[0] = [1];$bad[2] = [2];@bad = sort {$a->[0] <=> $b->[0]} @bad;

The variables $a and $b are aliased to each item in the list being sorted, and as such modifying them is possible - but will cause an error if the current element is unmodifiable. A common cause of this is sorting an array of references when where the list has a gap. In this situation $a will be undef, and autovivification by dereferencing will trigger an error.

Modifying an unlocalized $_

for (1,2) {  my $data = prompt_user();}sub prompt_user {   print "Enter a number\n";   while () {     # Do stuff   }}

This example will cause an error because the [doc://perlsyn#Foreach-Loops-for-foreach|for] loop aliases $_ to the literal '1', and then calls prompt_user which attempts to read a line from STDIN and store it in $_ - which is still aliased to '1'.

The error will also occur in this simplified scenario:

for (1,2) {    while () {    }}

Guidelines to avoid read-only errors:

Don't treat loop variables as a lvalue if there is any chance a constant value will be included
Don't modify an unlocalized $_
Don't modify $_ inside map or grep
Don't modify $a or $b inside sort
Don't dereference $a or $b inside sort without checking that they exist and are references
Don't use $_ for the loop variable unless it is a very trivial loop
Don't modify elements of @_ directly

Notes

Lists With Constant Values

Within the context of this document the important thing to understand is what expressions result in modifiable objects.The following expressions have constants in them:

$_++ for (1,2);$_++ for (1,@array);@array = map {$_++} (1,@array);

And the following are safe:

my @array = (1,2);for (@array) {  $_++;}

my ($x,$y) = (1,2);for ($x,$y) {  $_++;}

For an explanation of lists versus arrays I recommend the following:

[id://451421]
[href://http://japhy.perlmonk.org/articles/pm/2000-02.html|"List" Is a Four-Letter Word]

mod_perl / Apache::Registry accidental closures (imp)

When working with Apache::Registry it is very easy to create accidental closures.
This is due to the way Apache::Registry makes a fake package for your script, as I'll demonstrate in this tutorial.

The only indication that something is amiss (other than the unpredictable behaviour) will be the following line in your error log: Variable "$foo" will not stay shared at ...

The following code demonstrates the problem with accidental closures when using Apache::Registry.

use strict;use warnings;my $foo = 5;print "Content-type: text/plain\n";print "Content-disposition: inline; filename=foo.txt\n\n";printf "Package: %s\n", __PACKAGE__;printf "[%s] Before: %s\n", $$, $foo;badness(5);printf "[%s] After: %s\n", $$, $foo;sub badness {    my $val = shift;    printf "[%s] badness: %s\n", $$, $foo;    $foo += $val;}

Apache::Registry will take the above code and create a new package for it based on the ServerName and the name of the script, and then wrap the code in a sub handler {} block.

If your script is running on "foo.com" and is named "test.pl", then this is what the above code will look like after Apache::Registry is done:

package Apache::ROOTfoo_2ecom::test_2epl;use Apache qw(exit);sub handler {#line 1 /www/foo.com/test.pluse strict;use warnings;my $foo = 5;print "Content-type: text/plain\n";print "Content-disposition: inline; filename=foo.txt\n\n";printf "Package: %s\n", __PACKAGE__;printf "[%s] Before: %s\n", $$, $foo;badness(5);printf "[%s] After: %s\n", $$, $foo;sub badness {    my $val = shift;    printf "[%s] badness: %s\n", $$, $foo;    $foo += $val;}}

First run:

Package: Apache::ROOTfoo_2ecom::test_2epl[13520] Before: 5[13520] badness: 5[13520] After: 10

Second:

Package: Apache::ROOTfoo_2ecom::test_2epl[19331] Before: 5[19331] badness: 5[19331] After: 10

Third:

Package: Apache::ROOTfoo_2ecom::test_2epl[19331] Before: 5[19331] badness: 10[19331] After: 5

Fourth:

Package: Apache::ROOTfoo_2ecom::test_2epl[19331] Before: 5[19331] badness: 15[19331] After: 5

Notice how the number within the badness sub is increasing for each process, but the $foo that is seen by the instance script is never modified after 'badness' after the first execution for that process.

This is because the badness function is actually an inner function now,and it keeps a reference to the instance of $foo that was created for the first run.

Edit - example of how to avoid this issue added, per rhesa's suggestion

Thankfully it is easy to avoid these problems once you know why they occur.
Tips:

Keep your toplevel script minimal
Subroutines should only use the variables that were passed
Encapsulate behaviour in supporting objects

Example of a working alternative:

use strict;use warnings;my $foo = 5;print "Content-type: text/plain\n";print "Content-disposition: inline; filename=foo.txt\n\n";printf "Package: %s\n", __PACKAGE__;printf "[%s] Before: %s\n", $$, $foo;badness(\$foo, 5);badness(\$foo, 5);printf "[%s] After: %s\n", $$, $foo;sub badness {    my ($foo,$val) = @_;    printf "[%s] badness: %s\n", $$, $$foo;    $$foo += $val;}

mbito de variables en Perl: lo bsico (Hue-Bond)

Translated to spanish from [id://23317]'s original [id://66677].

mbito

Una de las cosas necesarias para dominar Perl es cmo manejar los mecanismos de mbito que te ofrece. Que queremos globales? Las tenemos. Que queremos evitar "colisiones" (dos variables con el mismo nombre pisndose una a la otra)? Podemos, y hay ms de una forma de conseguirlo. Pero las reglas de mbito de Perl no son siempre tan claras, y no es slo la diferencia entre my y local lo que hace tropezar a la gente, aunque aclarar eso es uno de mis objetivos.

He aprendido mucho de Coping with scoping y de varios libros de Perl (por ejemplo, Effective Perl Programming), por lo que debo dar crdito a sus autores ([Dominus] por el primero, y Joseph N. Hall y [merlyn] por el segundo). [Dominus] tambin ha hecho varias correcciones a los errores (algunos de ellos notables) de una versin anterior de este tutorial, as que l debera considerarse como mnimo el segundo autor (N del T: aunque [Dominus] no est de acuerdo con esto). Sin embargo la documentacin que viene con tu versin de Perl es la ms actualizada que puedes consultar, as que no dudes en usar perldoc perlop y perldoc -f foo en tu propio sistema.

Resumen

S, al principio...

my proporciona mbito lxico; una variable declarada con my slo es visible en el bloque en que ha sido declarada.
Los bloques de cdigo son trozos delimitados por llaves { }. Un archivo tambin se considera un bloque.
Usar use vars qw([nombres de variables]) o our ([nombres de variables]) para crear globales.
local guarda el valor de una global y lo sustituye por un valor nuevo a efectos del cdigo que est en el bloqueactual y al que llamemos desde tal bloque.

Espacios de nombres

Una de las ideas bsicas, aunque no es necesario dominarla para muchos programas, es la de espacios de nombres. Las variables globales (las que no se declaran con my) estn en un paquete. Los paquetes proporcionan espacios de nombres, que voy a explicar usando como metfora los apellidos. En los pases de habla hispana, "Roberto" es un nombre bastante comn, as que es posible que conozcamos a ms de un "Roberto" (asumiendo que vivimos en uno de estos pases). Normalmente, para los humanos, el contexto de la conversacin basta para que nuestra audiencia sepa de qu "Roberto" estamos hablando (en el vestbulo de la piscina, "Roberto" es el que controla de dardos; pero en el trabajo "Roberto" es el director de la empresa).

Por supuesto, estas personas tambin tienen apellidos (pero existen personas distintas con el mismo apellido, as que despus de todo esta metfora no es perfecta), y si quisiramos ser explcitos podramos aadirlos para que quien nos oye sepa de qu "Roberto" hablamos. $Garcia::Roberto es una cosa distinta de $Gonzalez::Roberto. Cuando tenemos dos variables distintas con el mismo "nombre de pila", podemos referirnos a cualquiera de ellas, sin importar el lugar del cdigo en que nos encontremos, usando el nombre completo de la variable.

Se usa el operador package para cambiar el paquete actual. Cuando usamos package Garcia en el programa, estamos, en efecto, diciendo que todas las variables y funciones no calificadas (es decir, que no tienen "apellido" explcito) deben ser entendidas como si estuvieran en el paquete Garcia. Es como decir "en esta parte del programa, voy a hablar de la familia Garcia".

De forma implcita, hay un package main al principio de los programas, esto es, excepto que declaremos explcitamente un paquete distinto, todas las variables que se declaren (teniendo en cuenta el uso de my) estarn en main. A las variables que estn en un paquete se les llama, y con razn, "globales de paquete", porque se puede acceder a ellas sin ms desde todos los operadores y subrutinas que estn en tal paquete (y si somos explcitos con sus nombres, tambin son accesibles desde fuera de l).

Usar paquetes hace que acceder a las variables sea como moverse en distintos crculos. Por ejemplo, en el trabajo, se entiende que "Roberto" es "Roberto Szywiecki", el jefe. En la piscina, "Roberto" es "Roberto Yamauchi", el experto en dardos. Aqu tenemos un pequeo programa para mostrar el uso de paquetes:

#!/usr/bin/perl -wpackage Szywiecki;$Robert = "el jefe";sub terminate {  my $name = shift;  print "$Robert ha despedido a ${name}\n";}terminate("arturo"); # muestra "el jefe ha despedido a arturo"package main;# terminate("arturo"); # produce un error si se descomenta__OUTPUT__el jefe ha despedido a arturo

El nombre completo de la variable $Robert es $Szywiecki::Robert (ntese que el $ se desplaza al principio, antes del nombre del paquete, indicando que este es el escalar Robert que est en el paquete Szywiecki). Para el cdigo y, ms importante, las subrutinas del paquete Szywiecki, un $Robert sin calificar se refiere a $Szywiecki::Robert -- excepto que $Robert haya sido "enmascarado" por una declaracin my o local (hablaremos de esto despus).

Ahora, al hacer use strict (y se debera! consulta [strict.pm] por ejemplo), tendremos que declarar todas esas variables globales antes de poder usarlas, EXCEPTO que querramos usar siempre sus nombres completos. Esa es la razn por la que la segunda llamada a terminate fallara si la descomentramos. Perl espera encontrar una subrutina terminate en el paquete main, pero no la hemos definido. Es decir, esto:

#!/usr/bin/perl -wuse strict;$Robert = "el jefe";  # error!print "\$Robert = $Robert\n";

producir un error, mientras que si ponemos el nombre entero (recordando que existe un package main implcito), no hay problema:

#!/usr/bin/perl -wuse strict;$main::Robert = "el jefe";print "\$main::Robert = $main::Robert\n";

Para satisfacer a strict 'vars' (la parte de strict que se encarga de las declaraciones de variables), tenemos dos opciones; producen resultados distintos y una de ellas slo est disponible en Perl 5.6.0 y ms recientes:

El operador our ($foo, $bar) (en Perl 5.6.0 y superiores) declara $foo como una variable en el paquete actual.
use vars qw($foo $bar) (versiones anteriores, pero todava funciona en 5.6) le dice a strict 'vars' que es correcto usar estas variables sin calificarlas del todo.

Una de las diferencias entre our y el ms antiguo use vars es que our proporciona mbito lxico (ms acerca de esto en la seccin de my, ms abajo).

Otra diferencia es que con use vars, debemos usar un array de nombres de variables, no las variables propiamente dichas (tal como con our). Ambos mecanismos nos permiten usar globales al mismo tiempo que mantenemos uno de los principales beneficios de strict 'vars': el estar protegidos de crear variables accidentalmente si nos equivocamos al teclear. strict 'vars' exige que las variables se declaren explcitamente (como diciendo "estas son las globales que voy a usar"). Los dos mecanismos permiten hacer esto con globales de paquete.

Algo que debemos tener en cuenta (que es potencialmente algo malo, dependiendo de lo fantico que uno sea de la privacidad") es que las variables globales no son slo globales a ese paquete, sino que son accesibles desde cualquier parte del cdigo, siempre que se usen sus nombres completos. Podemos hablar de Roberto, el experto de dardos, en el trabajo si decimos "Roberto Yamauchi" (en este cdigo no uso strict por brevedad):

#!/usr/bin/perl -wpackage Szywiecki;$Robert = "el jefe";package PoolHall;$Robert = "el experto en dardos";package Szywiecki; # a trabajar otra vez!print "Aqu en el trabajo, 'Robert' es $Robert, pero en la piscina, 'Robert' es $PoolHall::Robert\n";__OUTPUT__Aqu en el trabajo, 'Robert' es el jefe, pero en la piscina, 'Robert' es el experto en dardos

Lo veis? Entender los paquetes no es tan difcil. En trminos generales, un paquete es como una familia de variables (y de subrutinas! el nombre completo de aquel terminate en un ejemplo anterior es &Szywiecki::terminate -- lo mismo sirve para hashes y arrays, por supuesto).

`my` (y un poco ms sobre `our`) a.k.a mbito lxico

Las variables declaradas con my no son globales, aunque pueden actuar como tales. Uno de los usos principales de my es operar con una variable que slo sirva en un bucle o subrutina, pero desde luego que hay muchos ms. He aqu algunos conceptos acerca de my:

El mbito de una variable my es un bloque de cdigo.
Un bloque se define normalmente con llaves { }, pero en lo que a Perl concierne, un archivo tambin es un bloque.
Las variables declaradas con my no pertenecen a ningn paquete, slo "pertenecen" a su bloque.
Aunque podemos dar nombre a los bloques (por ejemplo, BEGIN), no podemos calificar el nombre del bloque para acceder a la variable my.
Las variables my a nivel de archivo son las que se declaran en un archivo pero fuera de un bloque de cdigo.
No se puede acceder a una variable my de archivo desde fuera del archivo en que se declare (excepto que sea el valor de retorno de una subrutina, por ejemplo).

Mientras slo escribamos programas de un solo archivo (por ejemplo, los que no importan mdulos), algunos de estos conceptos no importan mucho. Pero si estamos interesados en privacidad y encapsulacin (por ejemplo, si escribimos mdulos), tendremos que entender todas esas cosas.

He aqu un programa comentado para explicar algunas:

#!/usr/bin/perl -wuse strict;#recordemos que estamos en el paquete mainuse vars qw($foo);$foo = "Yo!"; # damos valor a $main::fooprint "\$foo: $foo\n"; # muestra "Yo!"my $foo = "Hey!"; # variable my a nivel de archivoprint "\$foo: $foo\n"; # muestra "Hey!" -- la variable nueva 'pisa' a la vieja{ # comenzamos un bloque   my $foo = "Yacht-Z";     print "\$foo: $foo\n";   # muestra "Yacht-Z" -- hay una nueva variable $foo visible  print "\$main::foo: $main::foo\n";  # todava podemos ver $main::foo  subroutine();   } # fin del bloqueprint "\$foo: $foo\n"; # nuestra variable $foo a nivel de archivo se ve otra vez!print "\$main::foo: $main::foo\n"; # $main::foo todava est aqusub subroutine {  print "\$foo: $foo\n"; # muestra "Hey!"  # Por qu? porque la variable declarada en el bloque sin nombre est en    # su mbito -- ahora tenemos otras llaves distintas rodeando esto. Pero la  # variable de archivo todava est en mbito, y todava "pisa" a la  # declaracin de $main::foo.}package Bar;print "\$foo: $foo\n"; # muestra "Hey!" -- la variable my todava es visible# si no hubiramos hecho la declaracin arriba, esto provocara un error: el# intrprete nos dira que Bar::foo no ha sido definida.__OUTPUT__   $foo: Yo!      $foo: Hey!     $foo: Yacht-Z  $main::foo: Yo!$foo: Hey!$foo: Hey!$main::foo: Yo!  $foo: Hey!

Tal como la parte de abajo del ejemplo nos dice, dado que no estn en ningn paquete, las variables my pueden ser visibles incluso aunque hayamos declarado un paquete nuevo, dado que el bloque de cdigo es el archivo (al menos en este ejemplo).

Este ejemplo usa un bloque sin nombre, no hay estructura de control asociada (por ejemplo if o while). Pero de ser as tampoco habra diferencias.

Las variables my de archivo SON accesibles desde los bloques definidos en ese archivo (tal como el ejemplo muestra), esta es una manera de la que pueden actuar como globales. Si, no obstante, subroutine se hubiera definido en otro archivo, tendramos un error en tiempo de ejecucin. Una vez sabemos cmo funciona my, podemos saber, slo fijndonos en la sintaxis del archivo, dnde va a ser visible. Esta es una razn por la que el mbito que proporciona se llama "lxico". En esto, use vars y el nuevo operador our difieren: si ponemos our $foo en el paquete Bar pero fuera de un bloque, estamos diciendo que (hasta que aparezca otro operador de mbito) debe entenderse que las ocurrencias de $foo se refieren a $Bar::foo. Esto ilustra la diferencia entre use vars y el nuevo our:

#!/usr/bin/perl -wuse strict;our ($bob);use vars qw($carol);$carol = "ted";$bob = "alice";print "Bob => $bob, Carol => $carol\n";package Movie;print "Bob => $bob, Carol => $carol\n";

El segundo print produce un error, porque $carol se toma como $Movie::carol, mientras que $bob es $main::bob.

Mientras que esta "expansin sobre paquetes" (que slo se muestra en el caso de our) es una similaridad funcional entre los dos tipos distintos de operadores de mbito, no debemos olvidar la diferencia entre ellos, que es que our declara una global, pero my no.

`local` a.k.a. mbito dinmico

Ahora llegamos a local, que es como my, pero debido a su nombre, su funcin se confunde con frecuencia con la de my. Aqu est el detalle: local $foo almacena el valor actual de la variable global $foo, y hace que en el bloque actual y en el cdigo al que se llame desde el bloque actual, $foo se refiera al valor que le demos en tal bloque (hacer local $foo le dar a $foo el valor undef, lo mismo que con my). Actualmente, local slo funciona en globales, no se puede usar sobre una variable my.

Ya que local puede afectar a cosas que ocurren fuera del bloque en que lo hemos usado, local proporciona mbito denominado dinmico, ya que su efecto se determina a partir de lo que ocurre cuando se ejecuta el programa. Esto es, el compilador no puede saber cuando local har efecto o no durante la compilacin del programa (que ocurre antes de la ejecucin del mismo). Esto distingue el mbito dinmico del lxico proporcionado por my y our, que tienen efectos visibles en tiempo de compilacin.

El resultado bsico de esta diferencia es que si localizamos una variable dentro de un bloque y llamamos a una subrutina desde ese bloque, la subrutina ver el valor de la variable localizada. Esta es una diferencia importante entre my y local. Comparar el ejemplo anterior con este:

#!/usr/bin/perl -wuse strict;use vars qw ($foo); # "our $foo" si usamos 5.6$foo = "global value";print "\$foo: $foo\n"; # muestra "global value"print "mysub    result '", &mysub(),    "'\n"; # "global value"print "localsub result '", &localsub(), "'\n"; # "local value"print "no sub   result '", &showfoo(),  "'\n"; # "global value"sub mysub { my $foo = "my value"; showfoo();}sub localsub { local $foo = "local value"; showfoo(); # SIEMPRE muestra "local value"}sub showfoo {  return $foo;}__OUTPUT__$foo: global valuemysub    result 'global value'localsub result 'local value'no sub   result 'global value'

Ntese que showfoo ignora (en apariencia) la declaracin my de mysub (ya que hemos abandonado el bloque en el que la declaracin my tiene efecto) pero la declaracin local de localsub no se ignora. Y despus de abandonar ese bloque, el valor original de $foo se vuelve a ver.

Espero que hayis aprendido tanto al leer esto como yo al escribirlo!

POD en 5 minutos (Hue-Bond)

Translated to spanish from [node://Juerd]'s original [id://252477].

Plain Old Documentation en 5 minutos

La documentacin es importante

Todos el mundo lo sabe, y sabe por qu. Me voy a saltar esta seccin porque cualquier discusin detallada de por qu la documentacin es importante rompera mi promesa de que se puede aprender a documentar en cinco minutos.

Documentacin en Perl

El cdigo fuente en Perl puede contener documentacin en formato POD. POD significa "Plain Old Documentation" (documentacin sencilla y antigua). Se puede mezclar POD con cdigo, poner todo el POD al principio o ponerlo al final. Slo depende del gusto de cada uno. T eliges.

Encabezados en POD

La estructura lgica es importante, por tanto se suelen usar encabezados. Hay cuatro niveles, y con esto debera llegar. Se usan los comandos =head1 .. =head4 (oficialmente se les llama comandos de prrafo. Son prrafos porque estn separados del resto del POD mediante lneas enblanco).

=head1 NOMBREMy::Module - Un mdulo de ejemplo

Secciones habituales

Para mantener las cosas claras, se usan las mismas secciones en todas partes. Ya hemos visto la seccin NOMBRE. S, es costumbre escribir los prrafos head1 en MAYSCULAS. Si haces mdulos para CPAN, debes usar este estilo. Si no, o si usas POD para otras cosas que documentacin (tambin es un formato bueno para escribir artculos o informes), queda a tu eleccin.

NOMBRE contiene el nombre del mdulo o script, un guin y una descripcin corta.
SINOPSIS significa "ver todo junto" y muestra ejemplos de uso.
DESCRIPCIN contiene una descripcin larga de lo que hace el mdulo y lista sus funciones.
BUGS o ADVERTENCIAS habla de los bugs o problemas que el usuario debera conocer.
AGRADECIMIENTOS es donde el autor agracede a los que arreglan bugs y prueban el programa.
COPYRIGHT o LICENCIA menciona las restricciones de copyright. Sin embargo, no hay que poner toda la GPL :).
DISPONIBILIDAD anuncia dnde se pueden encontrar versiones ms recientes.
AUTOR explica quin ha hecho el programa, si no lo hace ya la seccin COPYRIGHT.
VASE TAMBIN refiere al lector a un lugar con ms documentacin.

Todos estos son para =head1.

Las funciones, mtodos y todo eso se explican normalmente en una seccin =head2 bajo DESCRIPCIN.

Como mnimo, hay que documentar los argumentos que reciben las funciones y los valores que se devuelven. Si hay condiciones necesarias para algo, se deben mencionar. Si una funcin devuelve undef cuando hay errores, hay que hacrselo saber a la gente.

Est bien escribir frases cortas. Es mejor evitar las largas.

Ejemplos de cdigo

Los prrafos tabulados se toman como cdigo, con la tabulacin intacta. As de fcil!:

=head1 SINOPSIS    use My::Module;    my $object = My::Module->new();     print $object->as_string;

Esto se llama un prrafo textual.

Marcado

POD soporta un pequeo conjunto de elementos de marcado. Para mantener mi promesa, me voy a limitar a enumerarlos:

B<texto en negrita>
B<texto en cursiva>
B<texto subrayado>
B<cdigo>
B<y se pueden I<anidar>>

Tambin hay F, S, X y Z pero apenas se usan y no merece la pena explicarlos en un tutorial pequeo como este.

Si alguna vez hace falta incluir un carcter '>' dentro de cdigo, hay dos opciones. Si queremos poner $foo->bar con fuente de cdigo, podemos hacer esto:

C<$foo-E<gt>bar>
C<< $foo->bar >> (los espacios son necesarios!)
C<<< $foo->bar >>> (los espacios son necesarios!)

Entidades

Hemos visto que se puede usar E para entidades. Son como las entidades de HTML; tambin tenemos estas:

verbar para una barra vertical.
sol para una barra (solidus).

Las entidades numricas pueden ir en decimal, octal (con el prefijo '0') y en hexadecimal (con el prefijo '0x').

Listas

En este caso un ejemplo es mucho ms claro que una explicacin:

=head2 Mtodos=over 12=item CDevuelve un objeto My::Module nuevo.=item CDevuelve una representacin delobjeto en forma de cadena. Sirveprincipalmente para depuracin.=back

Como puede verse, se empieza esta lista con =over y la acabamos con =back. Entre ambos comandos hay =items. El nmero despus de =over es el nivel de tabulacin, usado principalmente por los renderizadores de texto para conseguir un diseo horizontal. pod2text convierte el ejemplo anterior en:

  Methods      "new"       Returns a new                  My::Module object.      "as_string" Returns a stringified                   representation of the                   object. This is mainly                  for debugging purposes.

Otras cositas de POD

Se puede usar L para enlazar a secciones del mismo documento o a otros documentos. POD se termina con =cut para volver a Perl. Hay comandos especiales para los distintos formatos de salida. Para leer la documentacin completa de POD, teclear:

perldoc perlpod

Un ejemplo completo

=head1 NOMBREMy::Module - Un mdulo de ejemplo=head1 SINOPSIS    use My::Module;    my $object = My::Module->new();    print $object->as_string;=head1 DESCRIPCINEste mdulo no existe en realidad, sehizo con el nico objetivo de mostrarcmo funciona POD.=head2 Mtodos=over 12=item CDevuelve un objeto My::Module nuevo.=item CDevuelve una representacin delobjeto en forma de cadena. Sirveprincipalmente para depuracin.=back=head1 AUTORJuerd - =head1 VASE TAMBINL, L=cut

Conclusin

Documentar con POD es fcil. A divertirse!

perlunitut: Unicode in Perl (Juerd)

NAME
DESCRIPTION

Definitions

Unicode
UTF-8
Text strings (character strings)
Binary strings (byte strings)
Encoding
Decoding
Internal format

Your new toolkit
I/O flow (the actual 5 minute tutorial)
Q and A

This isn't really a Unicode tutorial, is it?
What about binary data, like images?
What about the UTF-8 flag?
When should I decode or encode?
What if I don't decode?
What if I don't encode?
Is there a way to automatically decode or encode?
Cheat?! Tell me, how can I cheat?
What if I don't know which encoding was used?
Can I use Unicode in my Perl sources?
Data::Dumper doesn't restore the UTF-8 flag; is it broken?
How can I determine if a string is a text string or a binary string?
How do I convert from encoding FOO to encoding BAR?
What about the use bytes pragma?
What are decode_utf8 and encode_utf8?
What's the difference between UTF-8 and utf8?
What character encodings does Perl support?
Which version of perl should I use?

SUMMARY
ACKNOWLEDGEMENTS
AUTHOR
SEE ALSO

NAME

perlunitut - Perl Unicode Tutorial

DESCRIPTION

The days of just flinging strings around are over. It's well established thatmodern programs need to be capable of communicating funny accented letters, andthings like euro symbols. This means that programmers need new habits. It'seasy to program Unicode capable software, but it does require discipline to doit right.

There's a lot to know about character sets, and text encodings. It's probablybest to spend a full day learning all this, but the basics can be learned inminutes.

These are not the very basics, though. It is assumed that you alreadyknow the difference between bytes and characters, and realise (and accept!)that there are many different character sets and encodings, and that yourprogram has to be explicit about them. Recommended reading is ``The AbsoluteMinimum Every Software Developer Absolutely, Positively Must Know About Unicodeand Character Sets (No Excuses!)'' by Joel Spolsky, athttp://joelonsoftware.com/articles/Unicode.html.

This tutorial speaks in rather absolute terms, and provides only a limited viewof the wealth of character string related features that Perl has to offer. Formost projects, this information will probably suffice.

Definitions

It's important to set a few things straight first. This is the most importantpart of this tutorial. This view may conflict with other information that youmay have found on the web, but that's mostly because many sources are wrong.

You may have to re-read this entire section a few times...

Unicode

Unicode is a character set with room for lots of characters. The ordinalvalue of a character is called a code point.

There are many, many code points, but computers work with bytes, and a byte canhave only 256 values. Unicode has many more characters, so you need a methodto make these accessible.

Unicode is encoded using several competing encodings, of which UTF-8 is themost used. In a Unicode encoding, multiple subsequent bytes can be used tostore a single code point, or simply: character.

UTF-8

UTF-8 is a Unicode encoding. Many people think that Unicode and UTF-8 arethe same thing, but they're not. There are more Unicode encodings, but much ofthe world has standardized on UTF-8.

UTF-8 treats the first 128 codepoints, 0..127, the same as ASCII. They takeonly one byte per character. All other characters are encoded as two or more(up to six) bytes using a complex scheme. Fortunately, Perl handles this forus, so we don't have to worry about this.

Text strings (character strings)

Text strings, or character strings are made of characters. Bytes areirrelevant here, and so are encodings. Each character is just that: thecharacter.

On a text string, you would do things like:

    $text =~ s/foo/bar/;    if ($string =~ /^\d+$/) { ... }    $text = ucfirst $text;    my $character_count = length $text;

The value of a character (ord, chr) is the corresponding Unicode codepoint.

Binary strings (byte strings)

Binary strings, or byte strings are made of bytes. Here, you don't havecharacters, just bytes. All communication with the outside world (anythingoutside of your current Perl process) is done in binary.

On a binary string, you would do things like:

    my (@length_content) = unpack "(V/a)*", $binary;    $binary =~ s/\x00\x0F/\xFF\xF0/;  # for the brave :)    print {$fh} $binary;    my $byte_count = length $binary;

Encoding

Encoding (as a verb) is the conversion from text to binary. To encode,you have to supply the target encoding, for example iso-8859-1 or UTF-8.Some encodings, like the iso-8859 (``latin'') range, do not support theUnicode standard; characters that can't be represented are lost in theconversion.

Decoding

Decoding is the conversion from binary to text. To decode, you have toknow what encoding was used during the encoding phase. And most of all, it mustbe something decodable. It doesn't make much sense to decode a PNG image into atext string.

Internal format

Perl has an internal format, an encoding that it uses to encode text stringsso it can store them in memory. All text strings are in this internal format.In fact, text strings are never in any other format!

You shouldn't worry about what this format is, because conversion isautomatically done when you decode or encode.

Your new toolkit

Add to your standard heading the following line:

    use Encode qw(encode decode);

Or, if you're lazy, just:

    use Encode;

I/O flow (the actual 5 minute tutorial)

The typical input/output flow of a program is:

    1. Receive and decode    2. Process    3. Encode and output

If your input is binary, and is supposed to remain binary, you shouldn't decodeit to a text string, of course. But in all other cases, you should decode it.

Decoding can't happen reliably if you don't know how the data was encoded. Ifyou get to choose, it's a good idea to standardize on UTF-8.

    my $foo   = decode('UTF-8', get 'http://example.com/');    my $bar   = decode('ISO-8859-1', readline STDIN);    my $xyzzy = decode('Windows-1251', $cgi->param('foo'));

Processing happens as you knew before. The only difference is that you're nowusing characters instead of bytes. That's very useful if you use things likesubstr, or length.

It's important to realize that there are no bytes in a text string. Of course,Perl has its internal encoding to store the string in memory, but ignore that.If you have to do anything with the number of bytes, it's probably best to movethat part to step 3, just after you've encoded the string. Then you knowexactly how many bytes it will be in the destination string.

The syntax for encoding text strings to binary strings is as simple as decoding:

    $body = encode('UTF-8', $body);

If you needed to know the length of the string in bytes, now's the perfect timefor that. Because $body is now a byte string, length will report thenumber of bytes, instead of the number of characters. The number ofcharacters is no longer known, because characters only exist in text strings.

    my $byte_count = length $body;

And if the protocol you're using supports a way of letting the recipient knowwhich character encoding you used, please help the receiving end by using thatfeature! For example, E-mail and HTTP support MIME headers, so you can use theContent-Type header. They can also have Content-Length to indicate thenumber of bytes, which is always a good idea to supply if the number isknown.

    "Content-Type: text/plain; charset=UTF-8",    "Content-Length: $byte_count"

Q and A

This isn't really a Unicode tutorial, is it?

No, Perl has an abstracted interface for all supported character encodings, sothis is actually a generic Encode tutorial. But many people think thatUnicode is special and magical, and I did't want to disappoint them, so Idecided to call this document a Unicode tutorial.

What about binary data, like images?

Well, apart from a bare binmode $fh, you shouldn't treat them specially.(The binmode is needed because otherwise Perl may convert line endings on Win32systems.)

Be careful, though, to never combine text strings with binary strings. If youneed text in a binary stream, encode your text strings first using theappropriate encoding, then join them with binary strings. See also: ``What if Idon't encode?''.

What about the UTF-8 flag?

Please, unless you're hacking the internals, or debugging weirdness, don'tthink about the UTF-8 flag at all. That means that you very probably shouldn'tuse is_utf8, _utf8_on or _utf8_off at all.

Perl's internal format happens to be UTF-8. Unfortunately, Perl can't keep asecret, so everyone knows about this. That is the source of much confusion.It's better to pretend that the internal format is some unknown encoding,and that you always have to encode and decode explicitly.

When should I decode or encode?

Whenever you're communicating with anything that is external to your perlprocess, like a database, a text file, a socket, or another program. Even ifthe thing you're communicating with is also written in Perl.

What if I don't decode?

Whenever your encoded, binary string is used together with a text string, Perlwill assume that your binary string was encoded with ISO-8859-1, also known aslatin-1. If it wasn't latin-1, then your data is unpleasantly converted. Forexample, if it was UTF-8, the individual bytes of multibyte characters are seenas separate characters, and then again converted to UTF-8. Such double encodingcan be compared to double HTML encoding (&gt;), or double URI encoding(%253E).

This silent implicit decoding is known as ``upgrading''. That may soundpositive, but it's best to avoid it.

What if I don't encode?

Your text string will be sent using the bytes in Perl's internal format. Insome cases, Perl will warn you that you're doing something wrong, with afriendly warning:

    Wide character in print at example.pl line 2.

Because the internal format is really UTF-8, these bugs are hard to spot,because UTF-8 is usually the encoding you wanted! But don't be lazy, and don'tuse the fact that Perl's internal format is UTF-8 to your advantage. Encodeexplicitly to avoid weird bugs, and to show to maintenance programmers that youthought this through.

Is there a way to automatically decode or encode?

If all data that comes from a certain handle is encoded in exactly the sameway, you can tell the PerlIO system to automatically decode everything, withthe encoding layer.

You can provide this layer when opening the file:

    open my $fh, '>:encoding(UTF-8)', $filename;  # auto encoding on write    open my $fh, '<:encoding(UTF-8)', $filename;  # auto decoding on read

Or if you already have an open filehandle:

    binmode $fh, ':encoding(UTF-8)';

Some database drivers for DBI can also automatically encode and decode, butthat is typically limited to the UTF-8 encoding, because they cheat.

Cheat?! Tell me, how can I cheat?

Well, because Perl's internal format is UTF-8, you can just skip the encodingor decoding step, and manipulate the UTF-8 flag directly.

Instead of :encoding(UTF-8), you can simply use :utf8. This is widelyaccepted as good behavior.

Instead of decode and encode, you could use _utf8_on and _utf8_off.But this is, contrary to :utf8, considered bad style.

There are some shortcuts for oneliners; see -C in perlrun.

What if I don't know which encoding was used?

Do whatever you can to find out, and if you have to: guess. (Don't forget todocument your guess with a comment.)

You could open the document in a web browser, and change the character set orcharacter encoding until you can visually confirm that all characters look theway they should.

There is no way to reliably detect the encoding automatically, so if peoplekeep sending you data without charset indication, you may have to educate them.

Can I use Unicode in my Perl sources?

Yes, you can! If your sources are UTF-8 encoded, you can indicate that with theuse utf8 pragma.

    use utf8;

This doesn't do anything to your input, or to your output. It only influencesthe way your sources are read. You can use Unicode in string literals, inidentifiers (but they still have to be ``word characters'' according to \w),and even in custom delimiters.

Data::Dumper doesn't restore the UTF-8 flag; is it broken?

No, Data::Dumper's Unicode abilities are as they should be. There have beensome complaints that it should restore the UTF-8 flag when the data is readagain with eval. However, you should really not look at the flag, andnothing indicates that Data::Dumper should break this rule.

Here's what happens: when Perl reads in a string literal, it sticks to 8 bitencoding as long as it can. (But perhaps originally it was internally encodedas UTF-8, when you dumped it.) When it has to give that up because othercharacters are added to the text string, it silently upgrades the string toUTF-8.

If you properly encode your strings for output, none of this is of yourconcern, and you can just eval dumped data as always.

How can I determine if a string is a text string or a binary string?

You can't. Some use the UTF-8 flag for this, but that's misuse, and makes wellbehaved modules like Data::Dumper look bad. The flag is useless for thispurpose, because it's off when an 8 bit encoding (by default ISO-8859-1) isused to store the string.

This is something you, the programmer, has to keep track of; sorry. You couldconsider adopting a kind of ``Hungarian notation'' to help with this.

How do I convert from encoding FOO to encoding BAR?

By first converting the FOO-encoded byte string to a text string, and then thetext string to a BAR-encoded byte string:

    my $text_string = decode('FOO', $foo_string);    my $bar_string  = encode('BAR', $text_string);

or by skipping the text string part, and going directly from one binaryencoding to the other:

    use Encode qw(from_to);    from_to($string, 'FOO', 'BAR');  # changes contents of $string

or by letting automatic decoding and encoding do all the work:

    open my $foofh, '<:encoding(FOO)', 'example.foo.txt';    open my $barfh, '>:encoding(BAR)', 'example.bar.txt';    print { $barfh } $_ while <$foofh>;

What about the `use bytes` pragma?

Don't use it. It makes no sense to deal with bytes in a text string, and itmakes no sense to deal with characters in a byte string. Do the properconversions (by decoding/encoding), and things will work out well: you getcharacter counts for decoded data, and byte counts for encoded data.

use bytes is usually a failed attempt to do something useful. Just forgetabout it.

What are `decode_utf8` and `encode_utf8`?

These are alternate syntaxes for decode('utf8', ...) and

encode('utf8',...)

What's the difference between `UTF-8` and `utf8`?

UTF-8 is the official standard. utf8 is Perl's way of being liberal inwhat it accepts. If you have to communicate with things that aren't so liberal,you may want to consider using UTF-8. If you have to communicate with thingsthat are too liberal, you may have to use utf8. The full explanation is inEncode.

UTF-8 is internally known as utf-8-strict. This tutorial uses UTF-8consistently, even where utf8 is actually used internally, because thedistinction can be hard to make, and is mostly irrelevant.

Okay, if you insist: the ``internal format'' is utf8, not UTF-8.

What character encodings does Perl support?

To find out which character encodings your Perl supports, run:

    perl -MEncode -le "print for Encode->encodings( q:all )";

Which version of perl should I use?

Well, if you can, upgrade to the most recent, but certainly 5.8.1 or newer.This tutorial is based on the status quo as of 5.8.7.

You should also check your modules, and upgrade them if necessary. For example,HTML::Entities requires version >= 1.32 to function correctly, even though thechangelog is silent about this.

SUMMARY

Decode everything you receive, encode everything you send out. (If it's textdata.)

ACKNOWLEDGEMENTS

Thanks to Johan Vromans from Squirrel Consultancy. His UTF-8 rants during theAmsterdam Perl Mongers meetings got me interested and determined to find outhow to use character encodings in Perl in ways that don't break easily.

Thanks to Gerard Goossen from TTY. His presentation ``UTF-8 in the wild'' (DutchPerl Workshop 2006) inspired me to publish my thoughts and write this tutorial.

Thanks to the people who asked about this kind of stuff in several Perl IRCchannels, and have constantly reminded me that a simpler explanation wasneeded.

Thanks to the people who reviewed this document for me, before it went public.They are: Benjamin Smith, Jan-Pieter Cornet, Johan Vromans, Lukas Mai, NathanGray.

AUTHOR

Juerd Waalboer <juerd@cpan.org>

A Simple Socket Server Using 'inetd' (dwildesnl)

Using inetd to serve a socket

It is often the case that one needs to test a system before the hardware is available or on-line. In my case, I'm developing an interface which will talk to a socket on a complex piece of Fab Metrology gear called an Applied Materials NanoSEM, using a complex protocol called SEMI SECS-II/GEM HSMS. I needed a quick and dirty handler to act as the NanoSEM while I get the protocol parser working.

UNIX-like systems such as FreeBSD and Linux have a nifty feature called inetd, which comes to our rescue. inetd runs a program you specify whenever somebody else tries to connect to the socket you've chosen. By making a few simple configuration improvements, we can send our input to the specified socket, and inetd invokes our program, passing our input to it as STDIN. Our handler then processes it and spits out its response as STDOUT back to our socket. Cool, huh? What's even more cool is that if another process (or system) also tries to connect to the same socket, inetd will invoke another copy of our handler without bothering the first one.

Interested? Okay, here's the code...

The server handler:

#!/usr/bin/perl -w -T# sinet.pl A simple inetd socket server.use strict;my $old_fh = select(STDOUT);$| = 1;select($old_fh);while( my $line =  ){    $line =~ s/\r?\n$//;    if ($line =~ /endit/)     {die "shutting down\n";    }# do your processing here!    print "  $line\n";}

This little program will process anything that comes in on the specified port, clearing carriage returns and line feeds, and (in this simple case) spitting it back with two spaces in front and a newline at the end. An input containing "endit" causes the handler to exit, and, thanks to the flush sequence at the top, output is immediate. Make your program executable:

# chmod +x /usr/local/bin/sinet.pl

The configuration:

Okay, now, here's the setup. In /etc (you need to be superuser), edit /etc/services to add your port number to the known services list, making up a unique name for the service. My port is 6100, its service is 'secshsms', and I've asked it to handle both stream (tcp) and datagram (udp) packets, although this example will only deal with tcp.

secshsms6100/tcp   # DSW Handler for SECS-II/GEM HSMS trafficsecshsms6100/udp   # DSW

Next, edit /etc/inetd.conf to attach your program to that service:

# DSW add-on for SECS-II over HSMSsecshsmsstreamtcpnowaitnobody/usr/local/bin/sinet.pl secshsms

Okay, find inetd and restart it.

# ps -ax | grep inetd  563  ??  Is      0:00.01 /usr/sbin/inetd -wW -C 60# kill -1 563

From now on, any process that attempts to talk to my machine's port 6100 gets its output routed to my handler sinet.pl.

With that in hand, here's a sample client, adapted from Perl Cookbook recipe 17.10. It can be installed on any machine within a routable network (i.e., no firewall) and it will talk to my handler.

A simple client:

#!/usr/bin/perl# ncliauto.pl a simple automated clientuse warnings;use strict;use IO::Socket;my ( $confstr, $host, $port, $kidpid, $handle, $line, @say );# the config file contains host name (or IP addr) and port number, with a space between# examples:  localhost 6100#            myserv.mynet.com 6100#            123.456.789.1 6100open( CONF, "<./hsms.conf") or die "conf file: $!\n";$confstr = ;close( CONF ) or die "closing conf file: $!\n";chomp $confstr;( $host, $port ) = split( /\s+/, $confstr );# This is our demo array of outputs sent to the handler@say = ( 'You are getting sleepy...', '... very sleepy.', 'Your eyes are getting very heavy!', "... it's so hard to hold them open.", "You're so very sleepy now.", 'You just want to go to sleep.', 'Sleep feels so good!', "You're asleep. Sleep!", "You've earned it, just relax and sleep!", "... Sleep!", "              Sleep!", "                        Sleep!", '', '... zzz... zzz... ...zzz ...', 'endit');# This creates our client socket$handle = IO::Socket::INET->new( Proto => "tcp", PeerAddr => $host, PeerPort => $port )    or die "can't connect to port '$port' on host '$host': $!\n";# make sure it turns around inputs immediately$handle->autoflush(1);# announce our connectionprint STDERR "[connected to $host:$port]\n";# fork a child to handle sending our data to the socketdie "can't fork: $!\n" unless defined($kidpid = fork());if ( $kidpid ){#   The parent handles data coming from the socket server to us    while ( defined( $line = <$handle> ) )    {print STDOUT $line;    }#   ... until the connection is broken    kill( "TERM" => $kidpid );}else{#   The child process receives data for us    foreach my $item ( @say )    {print $handle $item . "\r\n";sleep 1;    } }exit;

Working from this skeleton, a more elaborate language can be developed. The program on each end can be made to parse and respond to commands from the other.

UPDATE 1: changed server user to nobody, thank you [idsfa].

Don Wilde
"There's more than one level to any answer."

Gay (Anonymous Monk)

UR GAY U STUPID BIATCH

Module::Compile (or: what's this PMC thingy?) (Juerd)

This document is written in response to many questions triggered by [id://536101]. It's not useful as a tutorial, because Module::Compile is in its infancy and very likely to change further, but posted here because it provides information only.

History

Once upon a time, people thought that maybe Perl would be faster if compiled code could be re-used in a later session. (Actually, many people still do.) So they created support for compiled Perl Modules, and where Python libraries got their "c" after their "py", compiled Perl modules would get their "c" after their "pm", and the "pmc" extension was born.

It works somewhat like this: you have a module, say, Test.pm, and the following line gives you the compiled version:

perl -MO=Bytecode,-H -MTest -e1 > Test.pmc

Provided that Test.pmc is in the same directory that Test.pm is, perl will automatically load Test.pmc instead of Test.pm the next time someone uses "use Test" or "require Test". This is because in every directory of @INC, perl first sees if a .pmc exists, and if it does, it loads that, and if not, then it tries to load the .pm.

What's going on?

If you strace the process, you can easily see what was going on before:

stat64("/usr/local/lib/perl/5.8.7/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/local/lib/perl/5.8.7/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/local/share/perl/5.8.7/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/local/share/perl/5.8.7/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/lib/perl5/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/lib/perl5/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/share/perl5/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/share/perl5/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/lib/perl/5.8/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/lib/perl/5.8/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/share/perl/5.8/Test.pmc", 0x7fe20a50) = -1 ENOENT (No such file or directory)open("/usr/share/perl/5.8/Test.pm", O_RDONLY|O_LARGEFILE) = 4

Before perl finds Test.pm in /usr/share/perl/5.8, it first tries a lot of other directories, each time stat()ing Test.pmc first, and then trying to open Test.pm. Now, because I have created a Test.pm in /usr/share/perl/5.8, perl's done a little earlier:

stat64("/usr/local/lib/perl/5.8.7/Test.pmc", 0x7f95aa50) = -1 ENOENT (No such file or directory)open("/usr/local/lib/perl/5.8.7/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/local/share/perl/5.8.7/Test.pmc", 0x7f95aa50) = -1 ENOENT (No such file or directory)open("/usr/local/share/perl/5.8.7/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/lib/perl5/Test.pmc", 0x7f95aa50) = -1 ENOENT (No such file or directory)open("/usr/lib/perl5/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/share/perl5/Test.pmc", 0x7f95aa50) = -1 ENOENT (No such file or directory)open("/usr/share/perl5/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/lib/perl/5.8/Test.pmc", 0x7f95aa50) = -1 ENOENT (No such file or directory)open("/usr/lib/perl/5.8/Test.pm", O_RDONLY|O_LARGEFILE) = -1 ENOENT (No such file or directory)stat64("/usr/share/perl/5.8/Test.pmc", {st_mode=S_IFREG|0644, st_size=720, ...}) = 0stat64("/usr/share/perl/5.8/Test.pm", {st_mode=S_IFREG|0644, st_size=28863, ...}) = 0open("/usr/share/perl/5.8/Test.pmc", O_RDONLY|O_LARGEFILE) = 4

Don't be fooled by the stat() on Test.pm; it's ignored. The actual open() is now on Test.pmc instead of Test.pm.

Sad ending

So, why did (and does) nobody really use this? Well, it turns out that bytecode loading is indeed faster in some (but not all) cases, but not very reliable: segfaults are quite common, and nobody so far has been able to fix it.

But there is another problem with Byteloader. The PMC file is actually just a normal Perl file: via a source filter, the bytecode is loaded. That's nasty, and makes using precompiled bytecode even less interesting.

Thus a sad story seemed to end, and the PMC feature was ignored, forgotten, and almost about to be deprecated... (Features aren't removed lightly in Perl - even if nobody uses it, a deprecation cycle is needed.)

Joyful rebirth of PMC and source filters

... if it weren't for the incredible geniuses who work on Perl 6 to find a very neat way to use the PMC feature to make Perl 6 acceptance and initial use less painful!

But actually, it's not even really Perl 6 related. It's just a very neat thing that you can also put to good use if you don't want to use Perl 6 yet. You see, we have source filters that can do very nice and spiffy (no pun intended) things for us, but are also known to have certain negative feelings attached to them. Sourcefilters have problems with mod_perl and other embedded perls, and they cannot be combined with other source filters. Besides that, source filters are always runtime overhead, and the result is usually not cached anywhere. You can't even debug the result easily, because the intermediate code is not available on disk.

The new invention exists in the form of [cpan://Module::Compile], formerly (for less than a day — that's how fast things go in Freenode #perl6) known as PMC::Filter.

Instead of using the normal source filters, Module::Compile writes the "compiled" code to a .pmc file, and that's loaded from that point forward. The nice trick is that the PMC file doesn't have to be bytecode. It's just a normal pure Perl file.

But we call them compilers now

A "compiler" (read: source filter) is built quite easily:

package Foo;use Module::Compile -base;sub pmc_compile {    my ($class, $source) = @_;    # Convert $source into (most like Perl 5) $compiled_output    return $compiled_output;}1;

and using that is also very straight forward:

# Unfiltered code herequux(bar);use Foo;# This code is filtered!# Ehh... I mean compiled!no Foo;# Unfiltered code here, againquux(bar);

A nice solution for everyone who has found a good use for source filters, but doesn't use them. Module::Compile supports using multiple compilers (source filters, for those who still don't get it) at the same time, the intermediate code is available for simpler debugging, and it works well even with embedded perls.

Perl 6 again

Remember that it was Perl 6 people that invented all this? It must have something to do with Perl 6, then, right? Well, but of course! The idea is to compile Perl 6 code into Perl 5 code, so that you can use it without Perl 6. You can do this to have a module that has parts in Perl 5 and parts in Perl 6, which is nice if you want to upgrade an existing module with some of the nice new features that Perl 6 has to offer, but don't want to rewrite everything just yet.

An even nicer thing, though, is that this allows you to write modules that are fully Perl 6, that will work both in Perl 5 and Perl 6.

Distribution

There are two problems with the PMC technique, though:

You need to have all the stuff installed that is needed for a succesful compilation
Users don't have write access in the system library directories

But there is one solution that solves both these problems: let Module::Compile generate your PMCs as you develop your software, and when you're done, distribute the compiled result along with the rest, so that people can use that. Also, if the PMC is installed with the rest, then someone with superuser privileges installs it.

Perl 6 example

Oh, you want example code, of course! Here it is, again copied straight from Module::Compile's documentation:

# User.pmuse v6-pugs;module User;...some p6 code here...no v6;...back to p5 land...

Oh well, I'll steal their explanation too:

On the first time this module is loaded, it will compile Perl 6 chunks into Perl 5 (as soon as the no v6 line is seen), and merge it with the Perl 5 chunks, saving the result into a User.pmc file.

The next time around, Perl 5 will automatically load User.pmc when someone says use Foo. On the other hand, Perl 6 can run User.pm as a Perl 6 module just fine, as "use v6-pugs" and "no v6" both works in a perl 6 setting also.

The pmc module will imbue v6.pm with the ability to check for Foo.pmc's updatedness also, and if it's up to date, then it'd touch its timestamp so the .pmc is loaded on the next time.

Final words

And that's why you shouldn't disable the PMC feature in Perl: although unused since its invention in 1999, there's now a very powerful use for it! Fortunately, so far the survey shows that only Mandrake/Mandriva users have it disabled. They can fix it soon, by upgrading.

Do note that Perl 6 is very far from production quality, and that Module::Compile is also still very young. You should probably not use them for anything serious yet.

Thank you, ingy++ and audreyt++, for bringing us this wonderful innovation!

Using Look-ahead and Look-behind (Roy Johnson)

If you are familiar with Perl's regular expressions, you are probably already familiar with zero-width assertions: the ^ indicating the beginning of string and the \b indicating a word boundary are examples. They do not match any characters, but "look around" to see what comes before and/or after the current position.

With the look-ahead and look-behind constructs documented in perlre.html#Extended-Patterns, you can "roll your own" zero-width assertions to fit your needs. You can look forward or backward in the string being processed, and you can require that a pattern match succeed (positive assertion) or fail (negative assertion) there.

Syntax

Every extended pattern is written as a parenthetical group with a question mark as the first character. The notation for the look-arounds is fairly mnemonic, but there are some other, experimental patterns that are similar, so it is important to get all the characters in the right order.

(?=pattern): is a positive look-ahead assertion
(?!pattern): is a negative look-ahead assertion
(?<=pattern): is a positive look-behind assertion
(?pattern): is a negative look-behind assertion

Notice that the = or ! is always last. The directional indicator is only present in the look-behind, and comes before the positive-negative indicator.Common tasks Finding the last occurrence There are actually a number of ways to get the last occurrence that don't involve look-around, but if you think of "the last foo" as "foo that isn't followed by a string containing foo", you can express that notion like this:/foo(?!.*foo)/ The regular expression engine will do its best to match .*foo, starting at the end of the string "foo". If it is able to match that, then the negative look-ahead will fail, which will force the engine to progress through the string to try the next foo.Substituting before, after, or between characters Many substitutions match a chunk of text and then replace part or all of it. You can often avoid that by using look-arounds. For example, if you want to put a comma after every foo:s/(?<=foo)/,/g; # Without lookbehind: s/foo/foo,/g or s/(foo)/$1,/g or to put the hyphen in look-ahead:s/(?<=look)(?=ahead)/-/g; This kind of thing is likely to be the bulk of what you use look-arounds for. It is important to remember that look-behind expressions cannot be of variable length. That means you cannot use quantifiers (., +, or {1,5}) or alternation of different-length items inside them.Matching a pattern that doesn't include another pattern You might want to capture everything between foo and bar that doesn't include baz. The technique is to have the regex engine look-ahead at every character to ensure that it isn't the beginning of the undesired pattern:/foo # Match starting at foo (?: # Complex expression: (?!baz) # make sure we're not at the beginning of baz . # accept any character )* # any number of times bar # and ending at bar/x; Nesting You can put look-arounds inside of other look-arounds. This has been known to induce a flight response in certain readers (me, for example, the first time I saw it), but it's really not such a hard concept. A look-around sub-expression inherits a starting position from the enclosing expression, and can walk all around relative to that position without affecting the position of the enclosing expression. They all have independent (though initially inherited) bookkeeping for where they are in the string.The concept is pretty simple, but the notation becomes hairy very quickly, so commented regular expressions are recommended. Let's look at the real example of [id://319742]. The poster wants to put a space after any comma (punctuation, actually, but for simplicity, let's say comma) that is not nestled between two digits. Building up the s/// expression: s/(?<=, # after a comma, (?! # but not matching (?<=\d,) # digit-comma before, AND (?=\d) # digit afterward ) )/ /gx; # substitute a space Note that multiple lookarounds can be used to enforce multiple conditions at the same place, like an AND condition that complements the alternation (vertical bar)'s OR. In fact, you can use Boolean algebra ( NOT (a AND b) === (NOT a OR NOT b) ) to convert the expression to use OR:s/(?<=, # after a comma, but either (?: (?CapturingIt is sometimes useful to use capturing parentheses within a look-around. You might think that you wouldn't be able to do that, since you're just browsing, but [478043|you can]. But remember: the capturing parentheses must be within the look-around expression; from the enclosing expression's point of view, no actual matching was done by the zero-width look-around.

Creating COM and DCOM objects with Perl (JamesNC) Ok, you have a written a really cool perl program and you would like to use if from MSExcel or MSWord or from a WSH or VB script. Perhaps it is an interface to DBI or some other really great perl module. How do you do it? This short tutorial for Win32 users explains how and give examples of how to share perl $scalars, @arrays and %hashes using a WSC - Windows Scripting Component to local and networked users. The documentation shows much more info. This tutorial is a just a quick and dirty how to get it working along with some stuff I have learned that is NOT in the documentation like how to do hashes( mimicked ) This tutorial also assumes that you know some VBA and how to open up the VB Editor in Excel. Helpful links: < a href="http://www.microsoft.com/downloads/details.aspx?FamilyId=408024ED-FAAD-4835-8E68-773CCC951A6B&displaylang=en " >WSC Wizard Technically optional, but I would get this free tool that generates a .wsc framework for you. < a href="http://www.microsoft.com/downloads/details.aspx?familyid=C717D943-7E4B-4622-86EB-95A22B832CAA&displaylang=en" >WSH Optional on W2K/XP WSC and WSH Documentation The process is fairly simple. Create a .WSC file ( recommend using the Wizard ) Add Perl and/or Perlscript code to the .WSC file Register the .WSC COM object with windows In your VB code, use CreateObject to create a instance of the COM object Now on to the examples! Copy and paste the following code into a file named "pcom.WSC" ( Note: do not alter the classid in this file! ) After you create the above file on your system. Then you just need to Register it with windows. In windows this is simple. Right click on the file Select -> Register Whew! That was tough. **You may also notice the "Generate Type Library" and wonder what it does. If it worked, it would help open up the api to your COM object and things like autocomplete in the VB editor would work for you. It kind of works in that if you were to create the typelib and then go to Excel and create a refrence to it, things would seem to work. But at run time when the COM object gets created, it is always the wrong type (Variant/Object) vs the Object that you created. So, don't even bother. Microsoft knows about this error and acknowledges it, but doesn't disable the "feature"... bizarreOk, we have Registered our COM object. Now, we need to use it! Here's how using Excel: Open a blank Excel sheet and add the following code Sub sortList_test()Set obj = CreateObject("pcom.WSC")Dim l() As Variantl = obj.sortList("fox", "dog", "moose", "cat", "fish") For Each li In l Debug.Print li Next liEndEnd SubSub getHash_test()Set obj = CreateObject("pcom.WSC")Dim hash As Scripting.DictionarySet hash = obj.getHash("dogHash")Debug.Print "Buddy is my " & hash.Item("buddy")End SubSub getScalar_test()Set obj = CreateObject("pcom.WSC")scalar = obj.getScalar(1)Debug.Print scalarscalar = obj.getScalar("a string! from VB")Debug.Print scalarEnd Sub Make sure that you have References to "Microsoft Scriptlet Library" and "Microsoft Scripting Runtime" selected. Call the subs and that's it for the fast track intro. I will elaborate more below on DCOM and a few more selected details. What about DCOM? Why use it? Your office mate on the same network doesn't have Perl installed on his box, but he wants to use your nifty perl object. DCOM comes to the rescue! Here are the steps needed to allow a user on another computer have access to the object. (Since this is documented in the above links I am only going to give an outline, search the docs for more details.) You need to modify the pcom.WSC file and add remotableattribute (be careful of the spelling! it is NOT remoteable) to the section like so: Now, you can call the object by using the the 2 argument form of CreateObject in your VB like so...Set hash = obj.getHash("dogHash", "127.0.0.1") If you tried this, it would fail on your friends computer because you have to first register your object on his machine AND you need to give him permission to use that object from your computer. How to register your COM object on his computer Open up regedit and search for pcom.WSC Right-click on the "{e91a2a76-18bc-4ab0-8b1c-06d6d0442287}" entry (pcom.WSC's classid ) and then select Export from the popup menu. Save this registry entry as pcom.reg Now, you just can use this file to add the needed information to his registry. Copy the file to your friends computer and Merge the file with his registry. ( You can do that with a Right-click and select Merge ) You are 1/2 way there. Now, you need to give him permission to access the object on your machine. You do that with "dcomcnfg.exe". This utility has a different interface for W2K and XP, so I will let you figure this part out. Basically, after you add the remotable entry, you will need to re-register the pcom.WSC file again, then open dcomcnfg.exe and browse the the pcom object and set the permissions for that object as appropriate. See the documentation for more details on how to run the object with different credentials. You can set security on the objects and more with the utility! What about debugging? The docs again. But my take on it is obviously debug your perl separately or in a .vb script where you can see the output more easily. Well, that's it. Hope it will open the world of amazing things perl can do with great ease and power to spread sheets and and other Windows applications for you. Other options I did not talk about include some solutions from ActiveState. They have some commercially available tools that can turn your scripts into stand alone controls and services, system tray utilities, apps and more. I don't work for them, but their PDK - Perl Dev Kit is worth the money IMHO if you want more robust features of doing these types of things. Cheers, JamesNC Test adding tutorial (wl69) I am doing a reseach project about the web community. I just test adding a tutorial without logging into the community. I am so sorry about messing up the tutorial section. If anyone has authority to delete the node, please go ahead! I appreciate that! How A Function Becomes Higher Order (Limbic~Region) All: [isbn://1558607013|Higher Order Perl], by [Dominus], has become a very popular book. It was written to teach programmers how to transform programs with programs. Many of us who do not have familiarity with Functional Programming are not aware of what [http://en.wikipedia.org/wiki/Higher-order_function|Higher Order] functions are. It is a function that does at least on of the two following things:Accepts a function as input Returns a function as output This tutorial is an illustration of how a simple every day function may become higher order increasing its usefulness in the process. Along the way we will pick up other tricks that can make our code more flexible and useful. Problem: We have a file containing a list of scores and we need to determine the highest score. Using the principal of code reuse and not reinventing the wheel, we turn to our trusty [cpan://List::Util]. use List::Util 'max';my @scores = ;my $high_score = max(@scores); Unfortunately, this requires all of the scores to be held in memory at one time and our file is really big. Just this once, we decide to break the rules and roll our own. my $high_score;while ( ) { chomp; $high_score = $_ if ! defined $high_score || $_ > $high_score;} As time goes by "just this once" has happened many times and we decide to make our version reuseable. sub gen_max { my $max; $max = $_[0] if defined $_[0]; return sub { for ( @_ ) { $max = $_ if ! defined $max || $_ > $max; } return $max; };}my $max = gen_max();while ( ) { chomp; $max->($_);}my $high_score = $max->(); This is our first step into Higher Order functions as we have returned a function as the output for the sake of reusability. We have also have many advantages over the original [cpan://List::Util] max function. Does not require all values to be present at once Ability to define a starting value Ability to process one or more values at a time Unfortunately, our function breaks the second we start comparing strings instead of numbers. We could make max() and maxstr() functions like [cpan://List::Util] but we want to use the concept of Higher Order functions to increase the versatility of our single function. sub gen_reduce { my $usage = 'Usage: gen_reduce("initial" => $val, "compare" => $code_ref)'; my $val; die $usage if @_ % 2; my %opt = @_; die $usage if ! defined $opt{compare} || ref $opt{compare} ne 'CODE'; my $compare = $opt{compare}; $val = $opt{initial} if defined $opt{initial}; return sub { for ( @_ ) { $val = $_ if ! defined $val || $compare->($_, $val); } return $val; };}my $maxstr = gen_reduce(compare => sub { length($_[0]) > length($_[1]) } );while ( ) { chomp; $maxstr->($_);}my $long_str = $maxstr->(); Now our function takes a function as input and returns a function as output. In addition to the previous functionality, we have added a few more features. Named parameters - allows flexibility in ordering and presence of arguments as well as ease in extensibility User defined comparator - our max function has now become a reduce function This does not have to be the end of the journey into Higher Order functions, though it is the end of the tutorial. Whenever you encounter a situation where two programs do nearly identical things but their differences are enough to make using a single function impossible - consider Higher Order functions to bridge the gap. Remember - it is important to always document your interface and assumptions well! I open the floor to comments both on the advantages and disadvantages of Higher Order functions. As they say, there is no such thing as a free lunch and there are always cases in which it makes sense to use distinct routines for distinct problems. Cheers,[Limbic~Region|L~R]Note: [cpan://List::Util] is a great module and the limitation of requiring all the values to be present at once is usually made up for by the fact that it also provides a reduce() function, has both C and Perl implementations, and syntactic sugar. The limitations were highlighted here for illustration purposes though I recommend using it when and where it does the job you need it to. Stepping up from XML::Simple to XML::LibXML (grantm) If your XML parsing requirements can be boiled down to "slurp an XML file into a hash",then XML::Simple is very likely all you need.However,many people who start using [http://search.cpan.org/dist/XML-Simple/|XML::Simple] continue to cling to the module even when their requirements have outgrown it.Most often,it's fear of the unknown that keeps them from 'stepping up'; to a more capable module.In this article,I'm going to attempt to dispel some of that fear by comparing using [http://search.cpan.org/dist/XML-LibXML/|XML::LibXML] to using XML::Simple. Installation If you're running Windows,you can get a binary build of XML::LibXML from Randy Kobes' [http://theoryx5.uwinnipeg.ca/|PPM repositories].If you're running Linux then things will be even simpler - just use the package from your distribution (eg: on Debian: apt-get install libxml-libxml-perl). If for some reason you're unable to install XML::LibXML,but you have XML::Parser,then you might like to install XML::XPath which is a Pure Perl module that implements a very similar API to LibXML but uses XML::Parser for the parsing bit. Some Sample Data Let's start with a file that lists the details of books in a (very small) library: Perl Best Practices Damian Conway 0596001738 542 Perl Cookbook, Second Edition Tom Christiansen Nathan Torkington 0596003137 964 Guitar for Dummies Mark Phillips John Chappell 076455106X 392 A Simple Problem As a warm-up exercise, let's list the titles of all the books from the XML file. Please assume all the code samples begin as follows: #!/usr/bin/perl use strict; use warnings; my $filename = 'library.xml'; Here's one solution, using XML::Simple: use XML::Simple qw(:strict); my $library = XMLin($filename, ForceArray => 1, KeyAttr => {}, ); foreach my $book (@{$library->{book}}) { print $book->{title}->[0], "\n" } And here's a LibXML solution that works the same way: use XML::LibXML; my $parser = XML::LibXML->new(); my $doc = $parser->parse_file($filename); foreach my $book ($doc->findnodes('/library/book')) { my($title) = $book->findnodes('./title'); print $title->to_literal, "\n" } The '/library/book' argument to findnodes is called an XPath expression. If we substitute a slightly more complex XPath expression, we can factor out one line of code from inside the loop: foreach my $title ($doc->findnodes('/library/book/title')) { print $title->to_literal, "\n" } And if it's code brevity we're looking for, we can take things even further (this is Perl after all): print $_->data . "\n" foreach ($doc->findnodes('//book/title/text()')); A More Complex Query Now, let's select a specific book using its ISBN number and list the authors. Using XML::Simple: use XML::Simple qw(:strict); my $isbn = '0596003137'; my $library = XMLin($filename, ForceArray => [ 'book', 'author' ], KeyAttr => { book => 'isbn' } ); my $book = $library->{book}->{$isbn}; print "$_\n" foreach(@{$book->{author}}); And with LibXML: use XML::LibXML; my $isbn = '0596003137'; my $parser = XML::LibXML->new(); my $doc = $parser->parse_file($filename); my $query = "//book[isbn/text() = '$isbn']/author/text()"; print $_->data . "\n" foreach ($doc->findnodes($query)); This time, we've used a more complex XPath expression to identify both the element and the elements within it, in a single step. To understand that XPath expression, let's first consider a simpler one: //book[1]This expression selects the first in a sequence of consecutive elements. The [1] is actually a shorthand version of the more general form: //book[position() = 1]Note XPath positions are numbered from 1 - weird huh?. As you can see, the square brackets enclose an expression and the XPath query will match all nodes for which the expression evaulates to true. So to return to the XPath query from our last code sample: //book[isbn/text() = '0596003137']/author/text()This will match the text content of any elements within a element which also contains an element with the text content '0596003137'. The leading // is kind of a wildcard and will match any number of levels of element nesting. After you've re-read that a few times, it might even start to make sense. The XML::XPath distribution includes a command-line tool 'xpath' which you can use to test your XPath skills interactively. Here's an example of querying our file to extract the ISBN of any book over 900 pages long: xpath -q -e '//book[pages > 900]/isbn/text()' library.xmlTo achieve the same thing with XML::Simple, you'd need to iterate over the elements yourself: my $library = XMLin($filename, ForceArray => [ 'book' ], KeyAttr => {}); foreach my $book (@{$library->{book}}) { print $book->{isbn}, "\n" if $book->{pages} > 900; } Modifying the XML One area in which XML::Simple is particularly weak is round-tripping an XML file - reading it, modifying the data and writing it back out as XML. For this example, we're going to locate the data for the book with ISBN 076455106X and correct its page count from 392 to 394: use XML::Simple qw(:strict); my $isbn = '076455106X'; my $xs = XML::Simple->new( ForceArray => 1, KeyAttr => { }, KeepRoot => 1, ); my $ref = $xs->XMLin($filename); my $books = $ref->{library}->[0]->{book}; my($book) = grep($_->{isbn}->[0] eq $isbn, @$books); $book->{pages}->[0] = '394'; print $xs->XMLout($ref); In this example I've used a number of tricks to attempt to make the output format resemble the input format as closely as possible: an XML::Simple object was used to ensure the exact same options were used both for input and output the ForceArray option was turned on to ensure that elements didn't get turned into attributes - unfortunately this necessitates the use of the extra ->[0] indexing the KeyAttr option was used to stop arrays being folded into hashes and thus losing the order of the elements - unfortunately this necessitates iterating through the elements rather than indexing directly by ISBN the KeepRoot option was used to ensure the root element name was preserved - unfortunately this introduced an extra level of hash nesting Even after disabling all the features that make XML::Simple both simple and convenient, the results are not ideal. Although the order of the books was preserved, the order of the child elements within each book was lost. By contrast, the LibXML code to perform the same update is both simpler and more accurate: use XML::LibXML; my $isbn = '076455106X'; my $parser = XML::LibXML->new(); my $doc = $parser->parse_file($filename); my $query = "//book[isbn = '$isbn']/pages/text()"; my($node) = $doc->findnodes($query); $node->setData('394'); print $doc->toString; Other Operations If you need to remove an element from an XML document using XML::Simple, you'd simply delete the appropriate hash key. With LibXML, you would call the removeChild method on the element's parent. For example: my($book) = $doc->findnodes("//book[isbn = '$isbn']"); my $library = $book->parentNode; $library->removeChild($book); To add an element with XML::Simple you'd add a new key to the hash. With LibXML, you must first create the new element, add any child elements (such as text content) and add it at the right point in the tree. For example: my $rating = $doc->createElement('rating'); $rating->appendTextNode('5'); $book->appendChild($rating); If that looks a bit too complex, there's also a convenience method you can use to add one element with text content in a single step: $book->appendTextChild('rating', '5'); XML::LibXML also provides a very handy method called parse_balanced_chunk that allows you to create a collection of related DOM nodes from a string containing an XML fragment. You can then add those nodes to your document: my $fragment = $parser->parse_balanced_chunk( '532.00' ); $book->appendChild($fragment); When you call toString to output the XML, you'll find the nodes you've added are not nicely indented as they would be with XML::Simple. This is hardly surprising since such indenting would require extra text nodes and if you don't add them they won't magically appear. In theory, you can call toString(1) to specify you want indents added, but I haven't had any success with that. You can however pipe the output through: xmllint --format - The xmllint utility is part of the libxml distribution. Resources The documentation for XML::LibXML is spread across a number of classes, including: XML::LibXML::Parser - methods and options for using during parsing XML::LibXML::Document - the class returned by the parser XML::LibXML::Node - abstract base class implementing methods common to different types of DOM nodes XML::LibXML::Element - methods specific to Element nodes XML::LibXML::Attr - methods specific to Attributes nodes XML::LibXML::Text - methods specific to Text nodes Zvon.org hosts an XPath Tutorial and an interactive XPath lab. (P6) Why the tilde makes sense (Juerd) Before I try to explain why the tilde (~) makes sense, let me first explain what happened to the plus (+). Infix (in between) plus still adds two numbers: 4 + 5 will stay 9. I think everyone will be very pleased with this. Prefix (in front) plus changed a little. It used to be a no-op, but in Perl 6 it forces numeric context. In other words, +$foo will evaluate $foo as a number, regardless of what it actually is. This instantly fixes all those ugly occurrences of $foo + 0. Then, there is the plus in a set of bit operators. As you may or may not know already, the bit operators have all changed. This is done because they've found much better uses for the beatiful characters like | and &. In Perl 5, when you had $foo | $bar, it would do a bitwise OR. But it didn't end there: there are stringy bitwise OR and numeric bitwise OR. The operation chosen would depend on the values of the two variables. This is highly unperlish, because in most other situations we have different operators for strings and numbers, because they just aren't the same thing. Thus, numeric OR is now +|. Ugly, yes, but how often do you use these? Besides, it may be ugly, but it's very clear to anyone who reads the code what $foo +| $bar will do. By the time you reach this paragraph, you either want to know what tilde has to do with all of this, or you have already thought of it. Tilde is for strings what plus is for numbers. That is: infix it will add (concatenate), prefix it will force string context (to get rid of "$foo" and $foo . "". And in bit operators it will give you string bit operations. Some examples: "foo" ~ "bar" # >>> "foobar"5 ~ 09 # >>> "59"~1e3 # >>> "1000""ja" ~| " ph" # >>> "japh" Some want the dot to stay for string concatenation. That would be possible, but the dot as a prefix operator would be troublesome with numbers: "foo" . "bar" # >>> "foobar"5 . 09 # >>> "59".1e3 # >>> "1000""ja" .| " ph" # >>> "japh" You do want .1 to be 0.1 rather than "1", I think. And, you may have been used to writing spaces around the dot before, but many people were surprised that while $foo.$bar could result in "53", 5.3 never did. The dot isn't lost, though. Perl 6 uses it for object orientation, instead of the arrow that Perl 5 used. It can even be used prefix, because method names cannot begin with a digit. Of course, when used without a left side, it defaults to $_. In my code, at least, method calls are used much more often than string concatenation. I like the change because of that, and because of the nice consistency with plus, that tilde can give us. handling multiple file handles for code generation (danmcb) What follows doesn't involve a lot of code, but demonstrates some nice things you can do with Perl's powerful. flexible, concise syntax. It is something I used in a project of mine where I am genearating a lot of C++ code. The code generates a large number of source and header files. In its first incarnation, each file was just opened and closed as needed, like this: open SRC "> file";# print lots of stuffclose SRC; This was fine for a while, but as time went on the thing got slower and slower, as the number of files grew. Also the sounds coming out of the hard disc suggested that some optimisation was in order. Hmm. So here's a wish list for some improvements; keep a number of files open, get back the filehandles as needed by the program by a simple mechanism. Minimise opening and closing of file handles. Provide a simple way to print header and footer text in the file (e.g. the guard statements which are necessary in CPP header files). Clean up nicely when done. This means closing file handles, and calling methods that handle version management software as needed. Here's how it was done: { my %fhs; sub END {foreach (keys %fhs){ my $fh = $fhs{$_}; if ($_ =~ /\.h\.new$/) {print $fh "#endif\n"; } close $fh; if ($_ =~ /\.h\.new$/) { Clearcase::handleClearCaseElement($_); }} }sub openFile{ my ($file, $header) = @_; unless (defined $fhs{$file}) {my $f;open ($f, "> $file") || die "could not open $file for output $!";$fhs{$file} = $f;print $f $header; } return $fhs{$file};}} It's pretty simple. The END block handles cleanup, adds closing #ENDIFs where necessary, and calls some Clearcase handling routines which take care of version control.. The %fhs hash is private to the END and openFile methods. openFile takes an argument for header info for the file in my system. You could change this around to fit your requirements. The other code has an easy time now. Whenever a certain file is wanted for output, just call my $fh = openFile('myFilename.cc', $header) and start printing to $fh. Job done. The script is back down to a few seconds to run as a result of this (from over 30 seconds) and the disc is a lot happier. The code is much more readable too. It would be wise, if the number of files gets very high, to extend this code to check that the number of open filehandles does not get too close to the system limit. It's possible to see some smart mechanism where least used filehandles are closed and only reopened when requested again ... as I don't need this right now, I'll leave this as an exercise for some future monk ... How to Ask a Regex Question (with Test::More) (repost, with Sitedocclan approval) (tphyahoo) This is the second post in the [id://479461] series, and assumes you have read the first, main post. In this installment, we learn how to use Test::More::like($string, $regex) and the qr quotelike operator to ask regex questions in a sane way. Let's dive right in. ******************BEGIN QUESTION TEMPLATE************************ O Wise Monks, I can't get this regex to do what I want it to do. As you can see, it fails two tests. use warnings;use strict;use Test::More qw(no_plan);my $emailsregex = qr/\w+@\w+\.(net|com|org)/;while () {like($_, $emailsregex)}__DATA__timmytimmers@aol.comhillary-hillers@aol.comgarbygerbil@herbill.gerbil.orggarbygerbil@herbill.gorgil.orgreginald_reggers@aol.com I'm on Windows XP system using the standard ActiveState perl distribution.I got both standard and error output out of my test, into one output file, by running this with emailsregex.pl > output.txt 2>&1 output.txt. The output I got was ok 1ok 2not ok 3# Failed test (emailsregex.pl at line 8)# 'garbygerbil@herbill.gerbil.org# '# doesn't match '(?-xism:\w+@\w+\.(net|com|org))'not ok 4# Failed test (emailsregex.pl at line 8)# 'garbygerbil@herbill.gorgil.org# '# doesn't match '(?-xism:\w+@\w+\.(net|com|org))'ok 51..5# Looks like you failed 2 tests of 5. What the heck am I doing wrong? ******************END QUESTION TEMPLATE************************ (Debugging the regex is left as an exercise for the reader.) How to Ask a Question (With Test::More) (repost, now with Sitedocclan approval.) (tphyahoo) The newbie has questions... the wise old monks have answers... but all too often newbie can't communicate the question, and the wise old monks fall over each other trying to guess what the newbie might have meant -- perhaps what [merlyn] meant when he wrote "the only personality trait Perl programmers have in common is that they're all pathologically helpful" (Programming Perl, "Perl Culture"). Examples of this happen all the time -- see for instance the recent post at [id://479266].Well, pathological helpfulness (or xp greed :) ) has its bright side as a cultural feature, but enough is enough. With this series of posts I want to help everyone save time, newbies and wise old owls alike, by providing templates for how to ask certain common types of questions. This is intended to be an alternative place to point newbies to, rather than the (also very helpful, but in a more general way) [id://172086]. As a bonus feature, newbies learning this will also learn Test::More, a powerful tool every monk should incorporate into their life. The first example will be short. My comments are in ~ . Here goes. ******************BEGIN QUESTION TEMPLATE************************ O Wise Monks, I am having a problem I hope you can help me with. As you can see, in the following code, my zero test for the "multiplies_by_seven" function fails. ~the problem is isolated~ I tried googling on "perldoc shift" but no dice. Am I searching with the wrong search terms? ~the newbie tried to help himself first before going to the perlmonks~ What the heck am I doing wrong? ~The novice now posts his code using code tags: see [Writeup Formatting Tips]~ # use strict; #~the newbie has used the strictures~use warnings; use Test::More qw(no_plan);my ($result, $expected);# ~convenient way to structure your input and expected output is to ~# ~suck in the test data, which is everything after the __DATA_ line.~while () {#~splits a string on spaces by default; see perldoc -f split~my ($input, $expected) = split; my $output = multiply_by_seven($input);is($output, $expected, "testing $input");}sub multiply_by_seven {my $number = shift or die "no number";return $number*7;} #~convenient way to structure your input and expected output, #assuming that you can use whitespace as the delimiter.__DATA__1 72 143 210 0 I'm on Windows XP system using the standard ActiveState perl distribution. ~The novice mentions what system he is on.~I got both standard and error output out of my test, into one output file, by running this with perl multiplyBySeven.pl > output.txt 2>&1 output.txt. ~Enables newbie to communicate his test result with a minimum of putzing around~ The output is: ok 1 - testing 1ok 2 - testing 2ok 3 - testing 3no number at multiplyBySeven.pl line 18, line 4.1..3# Looks like your test died just after 3. Any ideas? Thanks very much in advance, o wise monks :) ******************END QUESTION TEMPLATE************************ That's basically it. Why the 0 test fails is left as an exercise for the reader :) Soon to come: How To Ask a Regex Question (with Test::More) How To Ask a Multiline Regex Question (with Test::More) How To Ask a Data Structures Question (with Test::More) How to Ask A Regex Question (With Test::More) (tphyahoo) This is the second post in the [id://479461] series, and assumes you have read the first, main post. In this installment, we learn how to use Test::More::like($string, $regex) and the qr quotelike operator to ask regex questions in a sane way. Let's dive right in. ******************BEGIN QUESTION TEMPLATE************************ O Wise Monks, I can't get this regex to do what I want it to do. As you can see, it fails two tests. use warnings;use strict;use Test::More qw(no_plan);my $emailsregex = qr/\w+@\w+\.(net|com|org)/;while () {like($_, $emailsregex)}__DATA__timmytimmers@aol.comhillary-hillers@aol.comgarbygerbil@herbill.gerbil.orggarbygerbil@herbill.gorgil.orgreginald_reggers@aol.com I'm on Windows XP system using the standard ActiveState perl distribution.I got both standard and error output out of my test, into one output file, by running this with emailsregex.pl > output.txt 2>&1 output.txt. The output I got was ok 1ok 2not ok 3# Failed test (emailsregex.pl at line 8)# 'garbygerbil@herbill.gerbil.org# '# doesn't match '(?-xism:\w+@\w+\.(net|com|org))'not ok 4# Failed test (emailsregex.pl at line 8)# 'garbygerbil@herbill.gorgil.org# '# doesn't match '(?-xism:\w+@\w+\.(net|com|org))'ok 51..5# Looks like you failed 2 tests of 5. What the heck am I doing wrong? ******************END QUESTION TEMPLATE************************ (Debugging the regex is left as an exercise for the reader.) How To Ask a Question (With Test::More) (tphyahoo) The newbie has questions... the wise old monks have answers... but all too often newbie can't communicate the question, and the wise old monks fall over each other trying to guess what the newbie might have meant -- perhaps what [merlyn] meant when he wrote "the only personality trait Perl programmers have in common is that they're all pathologically helpful" (Programming Perl, "Perl Culture"). Examples of this happen all the time -- see for instance the recent post at [id://479266].Well, pathological helpfulness (or xp greed :) ) has its bright side as a cultural feature, but enough is enough. With this series of posts I want to help everyone save time, newbies and wise old owls alike, by providing templates for how to ask certain common types of questions. This is intended to be an alternative place to point newbies to, rather than the (also very helpful, but in a more general way) [id://172086]. As a bonus feature, newbies learning this will also learn Test::More, a powerful tool every monk should incorporate into their life. The first example will be short. My comments are in ~ . Here goes. ******************BEGIN QUESTION TEMPLATE************************ O Wise Monks, I am having a problem I hope you can help me with. As you can see, in the following code, my zero test for the "multiplies_by_seven" function fails. ~the problem is isolated~ I tried googling on "perldoc shift" but no dice. Am I searching with the wrong search terms? ~the newbie tried to help himself first before going to the perlmonks~ What the heck am I doing wrong? ~The novice now posts his code using code tags: see [Writeup Formatting Tips]~ # use strict; #~the newbie has used the strictures~use warnings; use Test::More qw(no_plan);my ($result, $expected);# ~convenient way to structure your input and expected output is to ~# ~suck in the test data, which is everything after the __DATA_ line.~while () {#~splits a string on spaces by default; see perldoc -f split~my ($input, $expected) = split; my $output = multiply_by_seven($input);is($output, $expected, "failed for $input");}sub multiply_by_seven {my $number = shift or die "no number";return $number*7;} #~convenient way to structure your input and expected output, #assuming that you can use whitespace as the delimiter.__DATA__1 72 143 210 0 I'm on Windows XP system using the standard ActiveState perl distribution. ~The novice mentions what system he is on.~I got both standard and error output out of my test, into one output file, by running this with perl multiplyBySeven.pl > output.txt 2>&1 output.txt. ~Enables newbie to communicate his test result with a minimum of putzing around~ The output is: ok 1 - failed for 1ok 2 - failed for 2ok 3 - failed for 3no number at multiplyBySeven.pl line 16, line 4.1..3# Looks like your test died just after 3. Any ideas? Thanks very much in advance, o wise monks :) ******************END QUESTION TEMPLATE************************ That's basically it. Why the 0 test fails is left as an exercise for the reader :) Soon to come: How To Ask a Regex Question (with Test::More) How To Ask a Multiline Regex Question (with Test::More) How To Ask a Data Structures Question (with Test::More) The extremely simple buffering tutorial (really just an example) (tphyahoo) Only for novice monks too lazy to read [dominus]'s suffering from buffering:from [perlvar]: HANDLE->autoflush(EXPR)$OUTPUT_AUTOFLUSH # need to use English at the start of your module $| If set to nonzero, forces a flush right away and after every write or print on the currently selected output channel. Default is 0 (regardless of whether the channel is really buffered by the system or not; $| tells you only whether you've asked Perl explicitly to flush after each write). STDOUT will typically be line buffered if output is to the terminal and block buffered otherwise. Setting this variable is useful primarily when you are outputting to a pipe or socket, such as when you are running a Perl program under rsh and want to see the output as it's happening. This has no effect on input buffering. See getc in the perlfunc manpage for that. (Mnemonic: when you want your pipes to be piping hot.) Some simple code:#see also http://perl.plover.com/FAQs/Buffering.htmluse strict;use warnings;#prints, waits a second, printsfor (1..3) {sleep 1;print "$_\n";}#without the newline, waits the entire time and then prints the whole thing.for (1..3) {sleep 1;print "$_";}$| = 1;#now it worksfor (1..3) {sleep 1;print "$_";}#you might want to go back to the default behavior now.$| = 0; Not Exactly a Hash Tutorial (planetscape) (A List of Resources, Definitely A Work in Progress, and Contributions Always Welcome :-) Online: Chapter 3 in Beginning Perl by Simon Cozens Chapter 5 of Picking Up Perl by Bradley M. Kuhn Section 2.3 in Impatient Perl by Greg London Effective Perl: Intermediate and Advanced Topics contains a wealth of information, not limited to hashes, but also including several pages on Joseph N. Hall's PErl Graphical Structures (PEGS). Uri Guttman's tutorial on AUTOVIVIFICATION tlm's rant on AUTOVIVIFICATION Extracting array of hashes from data Obligatory Google Print: Chapter 5 of Learning Perl by Randal L. Schwartz and Tom Phoenix p l a n e t s c a p e PDF::API2 Table (Sapphira) Hi, do anybody know: how can i create a table with the modul (PDF::API2)? And how can i make that automatically is word-wrapping at the end of the row? Thanks Sapphira Understanding transformation sorts (ST, GRT), the details (5mi11er) Let me start by saying that while I understood in theory what was happening in the Schwartzian and Guttman Rosler Transformations, I had a difficult time understanding the the details of how the magic "map sort map" incantations actually worked.I had read the requisite articles scattered around the Monastery, especially [id://145659|Advanced Sorting - GRT - Guttman Rosler Transform] and [id://447633|Choosing the right sort (Or: WUDsamatter?)] and [id://287149|fast, flexible, stable sort]. From [id://22609|tye's] reputation, and his description in this last node, I'd figured he touched upon something brilliant, but I certainly didn't "get it". I copied the snippet, filled in the XFORM function, and ran the code manually through the debugger printing what various parts of the sort transformation did, and finally "got it". Now, I'm pretty intelligent, so I figured that if I hadn't gotten it after reading bunches of the "sort" technique articles around the catacombs, that it would probably help a number of others if I could explain the magic a bit so they might understand what was going on with these transformation techniques. The basic theory We take the data we want to sort some particular way, and figure out how to mangle that data such that a standard Perl ascii sort will do the job for us, then unmangle the data such that we get back our original information, except now in sorted order. If you understand this, and have inklings about how to transform the data, but don't understand the details about how it all gets put together, this node is intended specifically for you. How this Transformation works As is true for all transformations, it helps a great deal to first understand that everything within this construct: (directly from [id://287149|Tye's node] above)my @sorted= @list[ map { unpack "N", substr($_,-4) } sort map { XFORM($list[$_]) . pack "N", $_ } 0..$#list]; is layed out in reverse order from which the execution is done. So, start at the end, you'll see the 0..$#list, which is just a list of all the indexes within the array @list. The indexes are what we're iterating over, and $_ is set to each index in turn.Next we have :map { XFORM($list[$_]) . pack "N", $_ } which simply calls XFORM(), which is your transformation of the data into a sortable string, and then appends to that string an encoding of the index value packed (in an architecturally independant format) into 4 bytes. That's the pack "N", $_ portion. The map statement just says to do that for every index. The resulting array of transformed, stringified data with the index values packed and glued to the end of each string is then passed to the sort routine. Assuming your transformation works as it is supposed to, the correctly sorted array of transformed, stringified data is then passed to the first map statement. This map just grabs the last 4 bytes of each string, which must be our encoded index value from the original array, and decodes it back into a usable index value; and it does this for all the entries. To be completely clear, the transformed, stringified stuff is thrown away at this point; only the index values are left. What we have at this point is an array of index values from the original array, but these index values are in the desired sorted order! At this point we've simplified the original transformation into this: my @sorted=@list[@array_of_sorted_indexes]; Execute that and we finally get @sorted which has the original array's information, but in sorted order, and @list is unmodified. If you're fuzzy about the @list[@array] notation, this is perfectly legal. Try this in a debugging session: print @{[a..z]}[0,4,8,14,20]; and you'll get the list 'a,e,i,o,u' back. If all that was still not clear enough and you need a concrete example with the sort magic broken out into individual statements, the following sorts dotted IP address information: #!/usr/bin/perluse strict;use warnings;sub XFORM { # Extract the sort key from $_[0] and return it. # This will often be written in-line # rather than as a real subroutine. return sprintf("%012.0f", ip2val($_[0]));}my ($addstr,$value,@addstrary,@addvalary,@sorted,$DEBUG);{ no warnings 'numeric'; if($ARGV[0] > 0) { $DEBUG = shift @ARGV; } else { $DEBUG = 0; }}while (<>) { s/(^\s+)//; #remove indentation s/\s+[\n\r]+//g; #remove all eol spaces/tabs & ctrl chars if(/^$/) { next; } #ignore blank lines if(/^#/) { next; } #ignore comments ($addstr) = Extract_IP_Address($_); if($addstr ne '') { #Use this to check the XFORM routine #printf "%15.15s %s\n",$addstr,XFORM($addstr); push @addstrary, $addstr; }}if($DEBUG == 0) { @sorted= @addstrary[ map { unpack "N", substr($_,-4) } sort map { XFORM($addstrary[$_]) . pack "N", $_ } 0..$#addstrary ];} else { #split up Tye's GRT sort above into separate pieces my (@arytosort, @sorted_stuff, @index_info); @arytosort = map { XFORM($addstrary[$_]) . pack "N", $_ } 0..$#addstrary; @sorted_stuff = sort @arytosort; @index_info = map { unpack "N", substr($_,-4) } @sorted_stuff; @sorted = @addstrary[@index_info];}foreach my $str (@sorted) { print "$str\n";}#---- Misc. IP address routines ----############################################ convert 4 byte integer value to an IP address###########################################sub val2ip { my ($a,$b,$c,$d)=unpack("CCCC",pack("N",$_[0])); return "$a.$b.$c.$d";}############################################ convert IP address to a 4 byte integer value###########################################sub ip2val { if ( $_[0]=~ /([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+)/o ){ return (unpack("N",pack("CCCC",$1,$2,$3,$4)) ); } else { return 0; }}###################################################################### Find the first dotted ip address in any string, puts it in $1, # and put the individual octets in $2, $3, $4 & $5. Figure out the# long integer representation of that address, and Return everything# in a list.## NOTE: it doesn't check to make sure each octet is between 0-254, # nor if the numbers between the dots are 1 to 3 characters in length.## Example: given "the IP address of www.xxx.com is 206.24.105.142"# return the list ('206.24.105.142',206,24,105,142,3457706382)#####################################################################sub Extract_IP_Address { if ( $_[0]=~ /(([0-9]+)\.([0-9]+)\.([0-9]+)\.([0-9]+))/o ){ return ($1,$2,$3,$4,$5, unpack("N",pack("CCCC",$2,$3,$4,$5)) ); } else { return (); }} It'll read from an input file or Standard In, and grab the first IP address on each line. If you want to manually run through the split up sort steps within a debugger, the script's first argument should be any positive number. Or just set $DEBUG yourself while in the debugger...-Scott Implementing Dispatch Tables (Roy Johnson) A dispatch table is just a mapping from strings to actions.If you find yourself lamenting the lack of a C-style switch/case statementin Perl, and you find yourself grumbling that the equivalentseries of if statements is a linear search, you probably want adispatch table. In Perl, the hash is a natural way to implement this.There is an [http://search.cpan.org/~pardus/Zoidberg-0.95/lib/Zoidberg/DispatchTable.pm|implementation in CPAN], but I don't think it's what we'relooking for. It's certainly not straightforward, and dispatch tables are easy enough to roll your own. The trivial case A basic dispatch table might look like this:my %disp_table = ( something => \&do_something ); You put a string in, you get a code ref out. Then, presumably, you executethe code ref:$disp_table{'something'}(); What could be simpler?Defaulting That's great if what you're looking for is in the table, but if it'snot, you're going to get an error for trying to use an empty string asa subroutine ref, because the hash value came up undef. Soyou need to have an alternative:($disp_table{'not there'} || sub {})(); Now if the hash lookup returns nothing, you fall back on a subroutinethat doesn't do anything. Of course, you could use a default that didsomething if you wanted to.Fall-through (chaining) What if you've got a bunch of things that map to the same action? You couldduplicate your code for each of them: one => sub { print "Number!\n" }, two => sub { print "Number!\n" }, three => sub { print "Number!\n" }, which should then raise a red flag that you need to abstract it outinto its own subroutine. And if 'one' is supposed to do somethingbefore falling through, you can embed that sub call in its custom action: one => sub { print "The loneliest "; number() }, two => \&number, three => \&number, By chaining calls this way, you can make things "fall through" to whatever you want them to. They are not limited by what comes next (which is good, because ina hash, what comes next is unpredictable).Matching patterns and ranges Up until a few minutes ago, I would have said that using a dispatch tableprecludes pattern matching. I would have been wrong. Super Search on dispatchtable came up with [429761|an ingenious post by grinder] that shows how todo just that, using[http://search.cpan.org/~dland/Regexp-Assemble-0.15/Assemble.pm|Regexp::Assemble]. In a sense, the pattern match is still searching all the alternatives,albeit in an optimized way. However, the circumstances in which a dispatchtable is most advantageous — where you have a very large number ofalternatives — are where a regex is likely to bog down.Ranges offer a similar challenge. Of course, neither patterns nor ranges arehandled by C's switch statement. Modula handles ranges, but it sacrifices fall-through (and may only work on numbers and single characters). You can't have everything. If you can't enumerate all the cases you want to cover, youdon't want a dispatch table. Functions that check all the alternativesin order (such as my [444780|smatch]) can offer a great deal of flexibility. Having Perl build the table The only really tricky bit about having a subroutine that translates alist of arguments resembling a C switch statement into a dispatch tableis in implementing fall-through. A program doesn't have the luxury ofcreating new named subroutines, so there's a bit of bookkeepingto handle there.I have implemented a function that does the translation for all thefeatures described above (except patterns and ranges, for the reasons cited)in the Snippet [id://456132]. vdd (NodeReaper) This node was taken out by the NodeReaper on Wed May 4 10:28:36 2005 (EST) Reason: [gellyfish]: deleteFor more information on this node visit: this How To: Make An Iterator (Limbic~Region) Purpose: The purpose of this tutorial is to give a general overview of what an iterator is, why they are useful, and how to build one. It is intended to give the reader enough information to begin using iterators though a certain level of understanding is assumed. The See Also section should be researched if supplemental information is needed.What Is An Iterator An iterator is simply a code reference that when executed will calculate the next item in a list and return it. In the event the list is exhausted, an agreed upon return value is given. A reusable iterator will have a constructing subroutine that creates a closure around any necessary state variables and returns an anonymous code ref that will be used as the iterator.Why Are Iterators Useful Typically, the most straightforward to get a list is to define an algorithm to generate the list and store the results in an array. There are several reasons why you might want to consider an iterator instead:list is too long to fit into memory Since only the state information necessary to calculate the next item is stored, the iterator typically has a tiny memory footprint.infinite list (also referred to as a stream) Iterators are probably the only way to represent infinite lists.Circular list While the list may be finite, you want the traversal of the list to be infinite (imagine days of the week).Unknown number of items needed It is a waste to create a list with hundreds of thousands of items if you find what you are looking for at number 42.Need multiple copies of the list Each instance of an iterator has a copy of its own state variables via the closure and since the anonymous code reference is relatively light-weight, it is efficient to pass around. How To Build An Iterator The basic structure of an iterator constructor looks like:sub gen_iterator { my @initial_conditions = @_; my $current_state; return sub { # ... code to calculate $next_state; return $current_state = $next_state; };} If anything needs to be known before work can begin, initial conditions are passed in as arguments. Any state variables that are needed to calculate are declared and/or initialized at the same level as the anonymous sub routine. A block of code that interacts with the state variables is returned to the caller completing the transaction. Each time the code reference is executed, the state variables are updated and the next item is returned.my $next = gen_iterator( 42 );print $next->(), "\n" for 1..10; # next 10 items in list Example: list is too long for memory my @list = map { my @lines = <$_>; \@lines } @f_handles;# becomesmy $next = gen_iterator( \@f_handles );while ( my $lines = $next->() ) { print @$lines, "\n";}sub gen_iterator { my $f_handle = shift; my $index = -1; return sub { $index++; return undef if $index > $#f_handle; my @lines = <$f_handle->[$index]>; return \@lines; };} Example: infinite list sub gen_iterator { my $curr = shift; $curr++ if $curr % 2; my $next; return sub { if ( ! defined $next ) { return $next = $curr } return $next += 2; };}my $next_even = gen_iterator( 41 );print $next_even->(), "\n" while 1; Example: circular list sub gen_iterator { my @list = @_; my $index = -1; return sub { $index++; $index = 0 if $index > $#list; return $list[ $index ]; };}my $work_day = gen_iterator( qw/Mon Tue Wed Thu Fri/ );print $work_day->(), "\n" for 1..7; Example: unknown number of items needed sub gen_iterator { my $prime; return sub { # ... code to calculate $next_prime from $prime; return $prime = $next_prime; };}my $next_prime = gen_iterator();while ( 1 ) { my $p = $next_prime->(); last if crack_code( $p );} Example: multiple copies needed Left as an exercise for the reader.Things To Consider What to use to indicate list is exhausted Be sure to document what value indicates the end of the list and be sure to use something that isn't considered a valid item in the list. If it is impossible to know, give the user the ability to specify what value to use as part of the initial conditions passed to the constructorUsing references to external variables as state variables In the first example, instead of making a copy of @f_handles, a reference was used. Changes to @f_handles may have side-effects during the course of iteration. Always document assumptions.Special return conditions may apply In order to avoid skipping the initial condition in the list, a special return clause was used. Often this is only needed for the first item.State variable persistence Just because the iterator has reached the end of the list doesn't mean it magically goes away. The state variables still have references to them so they are not garbage collected. If you have a substantial amount of state variables, either take special steps to destroy them at the end of the list or be sure to document them so people using your code can destroy the iterator itself at the calling level. See Also[id://268891] by [broquaint] [doc://perlsub] (perldoc perlsub) [http://perl.plover.com/hop/|Higher Order Perl] by [Dominus] A great book that covers the concept of iterators and a whole lot moreCheers - [Limbic~Region|L~R] Note: The examples in this tutorial are meant for instructional purposes and are not guaranteed to be complete or functional without work from the user. Jos's Guide for creating Perl modules (cog) NAME SYNOPSIS DESCRIPTION Before you start Picking a good name for your module Start your module h2xs module-starter ExtUtils::ModuleMaker Step by step: what to do Document first Create tests Use strict Use warnings Exports How it works What to export Inside your distribution Keep the Changes up to date Don't forget the README The MANIFEST Makefile.PL Version numbers Almost done Test it yourself Before uploading Uploading Other good practices Release early, release often Good style Source control Me got Kwalitee Other things you should know CPAN Testers Registering modules So I have a module. Now what? Final words SEE ALSO Books Links Modules Documentation ACKNOWLEDGEMENTS AUTHOR COPYRIGHT NAME Jos's Guide for creating Perl modulesSYNOPSIS Follow this guide to create good Perl distributionsDESCRIPTION From time to time, someone with little experience comes to me andasks: "I'd like to create a module. What do I do?"In order to answer that question to as many people as possible at thesame time, I decided to write this guide.Before you start Before creating a module, use CPAN Search tosee if it already exists. If you don't find it at first, search for itunder different names; search for its functionality, rather than thename you'd be giving it.You should do this exhaustively so you don't waste your timeduplicating effort. If your search on CPAN doesn't satisfy you, you can also searchGoogle. A lot of times, the right keywords are in the messages peoplepost about the module but not in the documentation. Just because a namespace exists doesn't mean you should abandon yourmodule. See if it is any good, if it has everything you'd like it tohave, and if it's being maintained. A good alternative is to contactthe author and ask him what he thinks about it. Maybe he'll give youthe namespace or you can also submit patches for the existing module. If you need help with any of this, you can ask the PAUSE admins atmodules@perl.org.They will gladly help you with that, and sometimes they even havedifferent means to contact the person. Picking a good name for your module A module needs a good name that's intuitive, something that peoplesearch for, and describes the functionality it provides.If you're having trouble deciding on a name for your module, send ane-mail tomodule-authors@perl.organdmodules@perl.org.The readers can help you figure out a goodname. If you have a name you're not sure about, keep that name in your mindfor a couple of days. If you don't think of anything better, it'sprobably a good name. If the name is really bad, you'll probably thinkof another one during this time. Start your module Sure, you can create your *.pm file, but don't forget the Makefile.PL,decent tests and the MANIFEST, along with META.yml and... wait aminute, you're not actually thinking of doing this all by yourself,are you?As with several other tasks that people do on a daily basis, startinga module from scratch is a task that has been automated... severaltimes! This means you have a range of module creation tools to help you.h2xs A simple execution of h2xs is enough to create a module; here's anexample: h2xs -XAn My::New::Module The resulting structure is something like this (depending on yourversion of h2xs). . `-- My-New-Module |-- Changes |-- MANIFEST |-- Makefile.PL |-- README |-- lib | `-- My | `-- New | `-- Module.pm `-- t `-- My-New-Module.t You're left with a directory with the name of your module, containinga Changes, MANIFEST, Makefile.PL, README, lib/ directory for yourmodules and a t/ directory for your tests. Not bad... Without the -b switch, h2xs assumes your module requires your currentversion of Perl. If your module doesn't have any particular needs forthat version, change that! I have been a victim of this in the past,with people sending me e-mails saying "Hey, your module requires Perl5.8.4, but it would run in 5.6.0. Could you please change that?" Saveyourselves that trouble and check that.module-starter The module-starter script from [cpan://Module::Starter] asks for a few moreparameters to start with. Here's an example: module-starter --module=My::New::Module --author="Me, Myself" \ --email=myself@cpan.org Here's the resulting structure from this: `-- My-New-Module |-- Changes |-- MANIFEST |-- Makefile.PL |-- README |-- lib | `-- My | `-- New | `-- Module.pm `-- t |-- 00.load.t |-- pod-coverage.t `-- pod.t Looks pretty much the same as the result of h2xs, right? But don't letthat fool you! Apart from the new files that test your PODdocumentation, the contents of those files are different from the onesgenerated with h2xs. Give a try to both systems and check out thedifferences. Currently, I use module-starter to start my own modules.ExtUtils::ModuleMaker [cpan://ExtUtils::ModuleMaker] is another tool for creating modules. Using thecommand modulemaker you are taken throught a menu. The resultingstructure would be something like this: `-- My `-- New `-- Module |-- Changes |-- LICENSE |-- MANIFEST |-- Makefile.PL |-- README |-- Todo |-- lib | `-- My | `-- New | `-- Module.pm |-- scripts `-- t `-- 001_load.t You can see some resemblances to the two other systems, right? Noticethe Todo and LICENSE files, as well as the scripts directory.Step by step: what to do Document first Now that you've created the skeleton of your module, you shouldmove on to its guts, to its code, right?Wrong! My personal opinion is that you should always start by thinking aboutwhat you're doing. This will save time in the long run. Start with the documentation. My experience tells me that coding gets mucheasier after you've documented every single one of your functions. Before actually coding, write down the description of what everyfunction in the module should do. This gives you a chance to figureout what you are doing. I usually keep a list of modules I'd like to create. Rather thancreate them when I think about them, I take notes on themfrom time to time. When the right time comes, I use that list andpick one of the modules with the most notes. Then, I write thedocumentation.Create tests Make tests before your code. I usually make mine at the same timeI'm coding. I code a function, write its tests and test it.Tests find things your eye wouldn't catch. As your module evolves,things you left behind can suddenly break. Tests will warn you aboutthem. You should test as much as you can. No test is a test too many. Test for basic cases, but you should also test the extreme ones. Don'tforget to test your functions with and without parameters, and evenwith parameters in excess, or wrong ones. You should know what thosefunctions return in each of those cases. You should also test your documentation, but module-starter willautomatically create those tests for that, using [cpan://Test::Pod::Coverage]and [cpan://Test::Pod].Use strict Use strict! "Strictures" can warn you about things that otherwiseyou'd be unaware of, like uninitialized variables and so on. Justput it at the top of all of your code files. use strict;Use warnings Warnings are good for your code and your sanity. use warnings; Use warnings and strict at the very beginning ofscripts or modules. But there is a downside to using warnings, though: they'renot backwards compatible! If your code uses warnings, itwon't work with versions of Perl prior to 5.6. You can,however, use warnings while developing and remove them whenreleasing. The latest version of [cpan://Test::Harness] turns on warnings whileyou test, so you might as well make your code warning free.Exports How it works When you have a module, you probably have functions. When a user usesyour module, he has to import your functions into his program.You're the one who chooses what he's able to import (that is, you canchoose not to let a particular function be imported) and how. Here's an example, to make things easier: require Exporter; our @ISA = qw(Exporter); our %EXPORT_TAGS = ( 'all' => [ qw( function_make function_remove activate_all deactivate_all ) ], 'action' => [ qw( function_make function_remove ) ], 'manipulation' => [ qw( activate_all deactivate_all ) ], ); our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } ); our @EXPORT = qw( function1 ); Here's a brief explanation of what is going on in that code: The last instruction (yes, we're starting by the end) states thatwhoever uses the module will always get function1. The user getseverything in the @EXPORT array automatically. The %EXPORT_TAGS hash is kind of an 'alias maker'. In the example, thetag action is mapped into function_make andfunction_remove,manipulation is mapped into activate_all anddeactivate_all,and all is mapped in the four functions. When using a module likethis: use The::Module qw/:action/; The current package is importing function_make andfunction_remove. The @EXPORT_OK is also very important. Things that are not in the@EXPORT variable can only be imported if they are included in@EXPORT_OK. In this particular example, it's OK to import any of the fourfunctions comprised in the all tag. This means one can do somethinglike this: use The::Module qw/:action activate_all/; He will get function_make,function_remove, activate_all andfunction1 loaded in his package.What to export So now that you have a couple of functions / methods implemented, youshould think on what to export...If your module is purely object oriented, then you probably won'texport anything. However, if you have functions, you might feel a sudden urge to exportsome of them. Don't!!! Do not export functions just because. Instead, make them available tobe exported, but let the user select what he wants to use (but don'tforget to document the possibilities, of course). Plus, people HATE changes in the API, so think deeply about it. By notexporting anything, your API will remain the same when you add newfunctionalities to your module. So, instead of adding those functions to @EXPORT, try adding them to@EXPORT_OK.Inside your distribution Keep the Changes up to date The Changes file is there for a reason, right? Keep it up to date! Itwill help users know what you have changed (and therefore choosingwhether to download and install the new version or not); it will helpyou in case something gets broken from one version to the next one(because you'll know what you have changed); plus, you (and everybodyelse, for that matter) will be able to keep track of your work.Don't forget the README The README file is really important. Not everybody reads it, but theyshould. That's why it is named README; because you're supposed to READIT!Anyway, browsing a module on the CPAN, people will often look at theREADME, and if it isn't much, they will very likely take that as asign that your module isn't really finished. Both h2xs and module-starter create a standard README file, which youshould change and add sections to as you feel the necessity for. Iusually copy the POD documentation of my main module to it.The MANIFEST The MANIFEST file contains the list of all files to include in thedistribution (and only those get into it).Whenever you add an extra file, don't forget to include it on theMANIFEST file, or your distribution will be incomplete (and,probably, broken).Makefile.PL There is a file called Makefile.PL. By looking at it, you might thinkthat you actually don't need to do anything to it; and that might betrue, most of the times.If you used h2xs, you should check its parameters. Otherwise, youshould be fine. However, there is one situation when you absolutely should updateMakefile.PL: when you use other modules. That is, when your module hasdependencies. Just go there and add something like this: PREREQ_PM => { 'Another::Module' => 0.01, }, That, for instance, states that your module depends on the existenceof at least version 0.01 of Another::Module. This makes life easier for everybody. The user who's downloading andinstalling your module automatically doesn't have to spend timefiguring out the dependencies, for instance; and CPANPLUS will testyour module correctly (hopefully). When testing, [cpan://Test::Prereq] might be a good option to check whetherthere are any modules you should add to PREREQ_PM (see section "Maketests", down below).Version numbers Whenever you release a new version, change the version number in yourmodule... and in the README... and be sure to include it in theChanges file too. It's really depressing when you upload a module andafterwards notice you got the version number wrong... (and it's evenmore depressing when you release the module again to get rid of thatannoyance and you do it again).Do not go from version 0.01 to 1.00 and then to 2.00, because thatreally looks bad and you'll be in version 20.00 in no time. Instead,go from 0.01 to 0.02, and from there to 0.03, and so on. Also, there isn't really the necessity of going to 1.00 just from0.99; people often change the integer part of the version (if one maycall it the integer part, given that it is usually a string) when theydo major changes in the design of the system, not when they run out ofnumbers. Versions which are still being implemented usually have the currentversion number with an underscore and a number, like 0.04_01 and arecalled "developer releases"; the underscore makes it clear that thedistribution is not yet ready for the general public. You shouldfollow that practice. You can even upload a developer's release to theCPAN. When people look at your module they will see that version, witha red sign stating it's a developer's release and a link to the lastready-to-take version.Almost done Test it yourself Before uploading your module, you should test it yourself. Use this tomake your distribution: make dist Suppose you had forgotten about including something in the MANIFEST,for instance. Just because your module passed all your tests in yourspecific directory doesn't mean it's working. make disttest That should do it.Before uploading Check your distribution before you upload it.Are the tests OK? Are they enough? Do they cover everything? Did I test after I last changed something? Did I get the version number right in three different places? Did I change the default documentation both on the module and on the README? Are all files in the MANIFEST? Did I include all the dependencies in Makefile.PL?Uploading The PAUSE is the Perl's Authors Uploading Server. In orderto upload something to the CPAN, you need a PAUSE account.Get an account at PAUSE.If you don't like the PAUSE web interface or you want toautomate it, or find it boring or whatever, you can take alook at release and Module::Release, which are toolsthat automatically upload files to the CPAN andSourceForge.net. Other good practices Release early, release often You don't have to wait until your module is completed to release it."Release early, release often!" You'll be moremotivated to do your work, people will be able to track yourprogress and might even give you some very important feedback on it.Good style In the CPAN, good coding style might be the differencebetween you receiving patches or not, or even between peopleactually using your modules or not (because some programmersare too suspicious and feel the urge to understand everylittle piece of code they use).Read perlstyle and Perl::Tidy which show very goodways to tidy up your Perl code.Source control Keep your code under a source control system, such as CVS,Subversion, or Perforce. You get backups, version controland lots of other advantages. Others who want to help can alsoaccess it if you make it public.Me got Kwalitee The Kwalitee of your modules is not really Quality, but asclose as possible as an automatic Quality-measurer can be.The Kwalitee project examines distributions on the CPAN forgood Perl coding practices, such as the use of strict,existence of tests, and so on. It assigns a score to eachdistribution, and therefore an average mean to the authors. Strive for a high Kwalitee score is good for you, yourmodules, and its users. The higher Kwalitee you get, thebigger your ego becomes, and people consider your modules tobe higher quality.Other things you should know CPAN Testers One of the best things about the CPAN is that your releases areactually tested by other people.As a module author, you don't have to bother about it; you simplyupload your modules to the CPAN and wait to see if anything happens. If your module's tests fail somewhere, you'll receive a report(actually, you're likely to receive quite a few, given that yourmodule will probably fail on other systems too). Don't take it too hard if you receive an email with a subject startingwith "FAIL Your::Module". It's nothing personal! You screwed up, butit's no big deal, because thanks to the CPAN Testers you are nowinformed of the problem and you can easily (hopefully) correct it andrelease a new version. There, no harm done.Registering modules Another thing you can do is to register the namespace ofyour module.To do that, go to your PAUSE account and use the "Registernamespace" option, which is pretty simple to use. You'llhave to elaborate on how and why is your moduleimportant, but it's not that difficult, really. When people look at your home node on CPAN Search(http://search.cpan.org/~yourusername), they will see allyour modules and a list of the registered ones, along withsome information on those. A registered module was approved by PAUSE admins.Therefore, it's not simply a product of some delusionalvisionist with headaches and is probably something good,unless, of course, some PAUSE admin that day was adelusional visionist and had an headache.So I have a module. Now what? If you're thinking "Time for another one", hold your horses there,pal! Creating module after module really isn't that hard; the hardthing is to maintain them all and keep them useful. Loads of moduleson their 0.01 versions that really don't do much and do have a list of"promises" don't do anyone much good, do they? Keepin mind that you should take all your modules to a stable version ofthem.There's nothing wrong in having a bunch of modules you haven'tcompleted yet, but there is something wrong in having a bunch ofmodules you will never complete.Final words That said, I hope you now know a bit more than when you startedreading this document, and I hope it helps the Kwalitee... er...Quality of the CPAN modules around.If you still have doubts (or maybe even more than when you started),there are lots of people willing to help (and of course I'm one ofthem).Check out themodules@perl.org mailing list. For anything else, I'm cog at cpan dot org. SEE ALSO Books Writing Perl Modules for CPAN, by Sam Tregar Links Perl Testing Reference Card Perl tutorial Lesson 8 Kwalitee CPAN Testing Service (CPANTS) http://magnonel.guild.net/~schwern/talks/CPANTS/full_slides/ Perl module author's mailing list, module-authors@perl.org Perl authors upload server (PAUSE) mailing list, modules@perl.org Modules Exporter ExtUtils::ModuleMaker Module::Release Module::Starter Perl::Tidy Test::More Test::Prereq Documentation perlmodlib perlmodstyle perlnewmod perlstyle ACKNOWLEDGEMENTS This guide was loosely based on brian's Guide to Solving Any Perl Problem (which you should read, too).Alberto Simes and brian d foy made really good suggestions for sections to add to this document, as well as some changes to the existing ones. AUTHOR Jos Castro, cog at cpan dot orgCOPYRIGHT Copyright 2004, Jos Castro, Creative Commons license. Perl White Magic - Special Variables and Command Line Switches (cog) Context This tutorial on Special Variables and Command Line Switches was originally published in the YAPC::EU::2004 proceedings (where it was awarded the prize for best paper).(hopefully, when translating the tex to html, I haven't screwed up anything O:-) ) Prologue Everything was silent, but for the two of them breathing. - 'All my life I've felt there was more to system administration thanthis... And now... now that you've arrived... now I know I wasright!' - 'You really think I'll be up to the job, Command Line?' - 'Yes, you will. You will, $_.' Super-powers come to those who wait $_ woke up with a sudden and loud noise. It would have sounded like a fan,should he know what a fan was. He knew there were things to be done, and that sooner or later he would becalled into aid. He did not know, however, what those particular thingswere and who would be in charge of choosing how and what to do exactly. As soon as these thoughts crossed his mind, gravity suddenly disappeared. Somekind of magnet picked him up and promptly took him to the top of a script,right after a shebang. Beneath him, comments could be seen.Commented code can mean an awfull lot of different things, and $_ knew thisbetter than any other variable. It can be meant to identify the Creator or thepurpose of life, but can also exist just to state that something is yetunfinished. One would hope it was not the case... Slowly at first, he started going down the script. Slowly enough to read thecomments: # counts words and lines in a file He passed that line and saw the next following ones: while (<>) { @words = split /\W+/; $words += @words; } print "lines -> $.\nwords -> $words\n"; Not knowing what to do, he started feeling anxious as gravity pulled him nearerto his destiny. At this point, Command Line shouted at him: - 'Use the monitor on your wrist!!' He looked at his wrist and saw something that resembled a smaller version ofsomething someone wanting to hitchhike through the galaxy would take as a guide,but it was actually something someone wanting to hitchhiking through a Perlscript would take as a guide. Plus, it had no "Don't Panic" stuff; instead, ithad Perldoc written on it. He quickly turned it on and searched for split (he already knew what awhile was). He realized that being called with a single argument,split would need him to complete his task. Knowing this, and reaching that line (several times in a row), $_ took hisplace in front of the split. ZAP!!! ZAP!!! His contents were instantely splited up and the resulting array was counted,having that result summed up to $words. After exiting the while, $_ met $.: - 'Hi', said $_. - 'Hi.' - 'Who are you?' - 'I'm $..' - 'That I can see, but... exactly what are you doing here?' - 'I am counting lines.' - 'What lines have you been counting if I've been through all of them and neversaw you?' - 'I see you're not familiar with special variables... I would advise you tomake use of that little device on your wrist and search for perlvar.' So he did, and promptly understood what a special variable was: they werethere, they just couldn't be seen... $., in particular, had beencounting the input lines right from the beginning of the script, and was readyto pop into action when called... and so it did. Not a second after realizing all this, $_ was pulled back to where he wasbefore. Command Line walked near him for a while: - 'How do you feel?' - '... Strange...' - 'Don't worry, you'll get over it. Happens to all of us. Soon you'll be readyfor more.' Different perspectives As before, $_ was taken again by the strange force. He was ready for it beforeit started, but then came the surprise... Strangely enough, this time he wasn't moving vertically, but ratherhorizontally... Everything resembled an assembly line. The first thing he noticed was a command line switch, but he did not know whatone was yet. He reached the monitor on his wrist and started hitting itdesperately. He eventually strolled across perlrun and searched for it.He found it: -e commandline may be used to enter one line of program. That explained the horizontal movement. Looking back and forward, he saw the complete line of code: perl -e 'while (<>) {$w += split /\W+/} print "$. $w\n"' He could now understand what was going on. This was practically the same scriptas before, except now it wasn't a script anymore, it was an "One-Liner", one ofthe most beautiful creations by the hand and mind of the OriginalCreator (The one and only: Larry Wall). The whole line resumed as expected, and he was on his way back home when he wassuddenly pulled back again into action. He saw a weird switch, this time. It was -ne. He looked it up butcouldn't find it. He was staring at the beginning of chapter "CommandSwitches", wondering, when he read something that washed away any doubt: As with all standard commands, a single-character switch may be clustered with the following switch, if any. #!/usr/bin/perl -spi.orig # same as -s -p -i.orig -ne was surely the same as -n -e, and he already knew one ofthem. He looked for the other and promptly found it: -n causes Perl to assume the following loop around your program [...] LINE: while (<>) { ... # your program goes here } He looked at the rest of the line to get a better feel of what was going on: perl -ne '$w+=split /\W+/; END{print"$w $.\n"}' Everything seemed OK now. He already knew that any END block was to beexecuted only at the end of the script, after everything else. The programwould go like this: LINE: while (<>) { $w += split /\W+/; END { print"$w $.\n" } } That was rather close to his first task, but with less coding going around. He finished his task and rushed for another one; this time it was a scriptinside a file again: #!/usr/bin/perl -n # counts words and lines in a file @words = split /\W+/; $words = @words; END { print "lines -> $.\nwords -> $words\n"; } Someone was obviously doing experiments, but that was good for him, as he wassurely learning from it. By knowing the -n switch, someone had actually shrinked the code. He would have asked -n what he though about it, but everyone knowscommand line switches don't speak. That would be just stupid. $_ went home and rested for a while. A whole bag of switches Again, the same startup routine. This time, the user was noticeably moreexperienced: #!/usr/bin/perl -w use strict; At least he seemed to know what he was doing. Every good script should startwith something like that. The Perldoc screen told him: -w prints warnings about dubious constructs One should always use it. Below, another comment: #Adding a commit each 100 lines He had heard something about this... DBA's sometimes have troubleinserting too many rows in a table, as that very same information is kept asroolback data between commit instructions(so everything can be undone, if needed). Adding a commit each 100 lines would solve this problem, as the maximumof information kept at a time would consist of 100 records. Following, the code: my $line; while (<>) { $line++; unless ( $line % 100 ) { print "commit;\n"; } print; } It wasn't as complicated as it would seem at first. He noticed the $linepart could be replaced with $., and the rest of the code could beshortened with the -n, but he really wasn't expecting what happened inhis next task. Just after finishing this, he was called again into action. He was getting usedto this and wouldn't get dizzy anymore. #!/usr/bin/perl -wp use strict; #Adding a commit each 100 lines unless ( $. % 100 ) { print "commit;\n"; } He looked up for -p: -p causes Perl to assume the following loop around your program [...] LINE: while (<>) { ... # your program goes here } continue { print or die "-p destination: $!\n"; } - 'So that's why the print statement has been removed.' It simply wasn't needed anymore, as the -p switch would do the same as-n and also print each line. He was pondering about this, when yet another surprise called for hisattention. He was, once again, in the Command Line; the user was making use ofthe -e switch once again: perl -i -pe 'print "commit;\n" unless ($.%100)' He knew what to do: -i[extension] specifies that files processed by the "<>" construct are to be edited in-place. It does this by renaming the input file, opening [...] - 'Wow.' He couldn't help the remark. That meant the input was to be read, processed, and then rewritten over theoriginal file. This would probably save the user the trouble of copying a newfile over an older one. He was taken back to his home. How many more switches would he meet? They come in pairs The same routine. Once again, $_ was ready for surprises and had his Perldocprepared. #!/usr/bin/perl -wlp use strict; # trims lines to 80 columns substr($_, 80) = ""; He looked up -l and, to his surprise, he found the exact code he wasrunning on. Hum... the user probably had a Perldoc of his own... (Perhaps hewas a special variable too?) The text on -l would go: -l[octnum] enables automatic line-ending processing. After reading a little bit more, he understood what was going on: the trailing"\n" on each line would be discarded, each line would be trimmed up to80 chars and printed with the "\n" back on. He noticed the textmentioned two other variables: $/ and $\... and their namessounded fierce. Usually, one goes from more code to less code, and not the other way around,but this was exactly what happened next. His next script, instead of using the-l switch, seemed to do the same by using those very same two variables.The user was obviously up to something (probably just testing and learning newfeatures). #!/usr/bin/perl -wp use strict; # trims lines to 80 columns chomp; $\ = $/; substr($_, 80) = "" Dazzled in astonishment, he didn't even think about reaching for his Perldoc. Heinstead asked the variables directly what they were up to. - 'Hi. - 'Can't you see we're busy?' said $/. - 'I'm sorry, but I'm new at this, and so many special variables and commandswitches are starting to mess with my mind...' - 'Oh, a beginner...' said $\. - 'Indeed, a beginner.' $/ agreed. - 'Yes. I was wondering who you guys are, and what you are doing.' - 'I am the input record separator. Usually, I contain a "\n"', explained$/. - 'And I am the output record separator... usually containing nothing...'sighed $\, with a slight note of disappointment. - 'And what are you doing?' asked $_. - 'We're swapping contents.' said $\. - 'Yes, it's a rather common practice.' Continued $/. - 'Actually, it's so common that someone actually invented a switch for this.' - 'So I noticed. -l, isn't it?' - 'So you've seen it too, uh?' - 'Yes.' As good as the conversation was getting, $_ noticed the end of the scriptarriving. - 'What's the purpose of what you're doing?' - 'Well, you see, most of the times you print something, you're actually printinga line, but that means you have to print the "\n" too, as the commonprint statement does not assume that. However, by making use of $\ here,you have no need of doing that...' - 'Yes, I'll do it for you!' interrupted $\ 'Just give me whateveryou want printed on every line, and I'll take care of it for you! We're closefriends, print and I.' - 'Wow... that's nice...' - 'Yes, and that's not all. You should see what *I* can do!' said $/. - 'Really, what can you do?' - 'Later, my friend, here comes EOF to take us home.' So that was the name of this magnet: EOF. The mighty variable $_ fell asleep with $/ on his head, and woke up still thinking aboutit. He was called into action and, to his contentment, there was $/: #!/usr/bin/perl -wpi use strict; $/ = ""; while(<>) { chomp; print "$_\n"; } - 'Hi.' - 'Hi.' - 'I can't see any comments on this script. What's going on?' - 'We're joining paragraphs.' - 'What do you mean?' - 'I mean we're joining paragraphs. Those having more than two blank linesbetween them are being pushed closer to each other. Basically, we'renormalizing text.' - 'I see... And how exactly are we doing that? And what's your part in allthis?' - 'Well, as I told you before, I am the input record separator, which means I'mthe one who decides the input that gets in at a time. Regularly, I have astring (usually "\n"), which is what I use to make that decision,spliting the input on that string, but I do have a couple of more tricks up mysleeve...' - 'I can imagine that. Are you using one of those right now?' - 'Yes. I am using the paragraph mode. By assigning me to an empty string, theuser gets me to separate input at blank lines. Basically, at "\n\n+".' - 'I see. But why not assigning you to "\n\n+" directly?' - 'Hey, kiddo! See me flying?' - 'No...' - 'Know why?' - 'Why?' - 'That's because I'm a special variable, not a super variable. I can't dealwith regular expressions.' - 'Hum... And I assume a simple "\n\n" wouldn't suffice, as thatwouldn't get all the cases...' - 'You assume correctly. I would take "\n\n\n\n", for instance, and findanother record in the middle of it. Hence, paragraph mode.' - 'Wow... Nice trick!' - 'Thanks.' - 'Too bad you don't do regular expressions, though...' - 'It's not that bad, really. Anyway, awk has to be better for something.' - 'I suppose you're right. What about your other tricks?' - 'Well, I can be assigned to a reference to an integer, a scalar containing aninteger or a scalar that's convertible to an integer...' - 'And what will that do?' - 'Given that integer, I will read that many bytes at a time.' - 'Wow.' - 'Gotta go. Bye.' - 'See you around.' That night, $_ had trouble falling asleep, dreaming of the possibilities those$/'s tricks could mean. Separations Yet another day. perl -ane 'print shift(@F), "\n"' Everything was so easy now that he was used to Perldoc. He was even able to opentwo windows at a time, one with perlrun and another with perlvar.He used the first one to search for -a: -a turns on autosplit mode when used with a -n or -p. An implicit split command to the @F array is done as the first thing inside the implicit while loop produced by the -n or -p. perl -ane 'print pop(@F), "\n";' is equivalent to while (<>) { @F = split(' '); print pop(@F), "\n"; } and the second for @F: @F The array @F contains the fields of each line read in when autosplit mode is turned on. [...] To tell the truth, the entry for -a already explained what @F wasdoing there. Anyway, the code in the documentation was very similar to the onehe was running on. He was clearly on a script for printing the first word ofevery input line. What for? He would soon find out. Next, he passed the following code: #!/usr/bin/perl -wane use strict # study commands (input is .bash_history) $commands{shift(@F)}++; END { for (keys %commands) { print "$_ -> $commands{$_}\n" } } This was a very simple way of studying how often commands are ran on thesystem. There was still another line of documentation, regarding -a: An alternate delimiter may be specified using -F. Another switch. And soon he would see and example of its usage: perl -F: -ane 'print shift(@F),"\n"' Hum... this would split the input lines on ':' and print every firstelement of those lines. (Maybe it would run on /etc/passwd, for alist of users) TIMTOWTDI Command Line approached $_ softly and woke him gently: - 'Wake up, $_!' - 'What is it?' - 'Come, you're going to learn an important lesson today.' - 'OK.' They walked along for a while. - 'So what's this lesson I'm going to learn?' - 'Be patient, my friend. Look, here's your first script for today!' #!/usr/bin/perl -w use strict; my @a = (1, 2, 3, 4, 5); print "@a"; $_ went through it as if he hadn't been doing anything else all his life. - 'There.' - 'Very good. Did you notice the output?' 1 2 3 4 5 - 'Cool...', said $_, 'Perl already knows he has to put a space betweenthose elements, right?' - 'Wrong. The truth is Perl knows he has to put something between thoseelements, allright. You're about to meet that something.' #!/usr/bin/perl -w use strict; my @a = (1, 2, 3, 4, 5); $" = "|"; print "@a"; - 'Done!' - 'Well done. Now, did you notice the difference?' 1|2|3|4|5 - 'Yes. I assume Perl takes the contents of $" and prints that everytimean array is printed. Right?' - 'Wrong again... Perl only uses $" if the array is inside quotes.Take a look at our next example!' #!/usr/bin/perl -w use strict; my @a = (1, 2, 3, 4, 5); print @a; $_ went through it. - 'Now look at the output produced.' 12345 - 'Odd... shouldn't a space be there too, separating elements?' - 'No. When not quoted, an array to be printed is joined with the contents of$,, and that variable is empty by default. Next example!' #!/usr/bin/perl -w use strict; my @a = (1, 2, 3, 4, 5); $, = "-"; print @a; - 'And now the output!' 1-2-3-4-5 - 'See?' - 'Yes... Interesting...' - 'Indeed. Let's go.' - 'OK...' - 'See how you can do the same with two different variables?' - 'Yes.' - 'That's your lesson for today. There's more than one way to do it!' - 'I see...' $_ was clever enough to remain silent for a while and think about what Command Line hadjust said... "There's more than one way to do it!" Thoughts 'I like it here.' exclaimed $_. 'All these switches and specialvariables, being famous and loved by all.' - 'That's not entirely true... Some variables are not very well known, andothers are not very appreciated.' replied Command Line. - 'For instance...?' - '$..' - 'Really? Is that true?' - 'Yes, it is.' - 'Who doesn't appreciate it?' - 'YAPC speakers who have to write articles with sentences ending in $..' - 'Why? I don't see any problem with a sentence ending in $..' - 'Oh, but there are problems with sentences ending in $..' - 'I really can't see what's wrong with $....' - 'Then you probably didn't pay attention to the four previous lines.' - 'Oh! That! I didn't realize that... Boy, it must really suck, being theonly variable some people don't like.' - 'Oh, not the only one...' - 'Who else, then?' - 'Guess.' - '$,, $??' - 'Those and $!!' Modules and one-liners $_ was on the move again. perl -MExtUtils::Installed -le ' print for ExtUtils::Installed->new()->modules' He looked -M on Perldoc and was preparing to look for -E too when henoticed there was no need for that... -M, according to Perldoc, would do the same as a use clauseinside the script. Basically, that line was the same thing as perl - le 'use ExtUtils::Installed; print for ExtUtils::Installed->new()->modules' The E was actually the beginning of a parameter for the -Mswitch. He also looked for documentation on that module (with Perldoc, too). He foundit and came to the conclusion that that line of code would print the name ofevery Perl module installed. That was a nice way to know what was on thesystem. The sky is the limit 'I think I'm getting the hang of this.' - 'There is still much to learn, $_.' - 'Are there more special variables?' - 'Quite a few. And some more command line switches, too.' - 'Wow... This is just amazing...' - 'I'm glad you like it. However, we won't have the time to go through all ofthem now.' - 'Oh... That's too bad...' - 'Don't worry. There are lots of places where you can learn more, and Perldoc is oneof them.'$_ stared at his Perldoc. - 'And besides that, you have lots of mailing lists, perlmonks, etc. You'll neverrun out of information. The trick is to keep practising.' $_ smiled. Revelations $_ was browsing his Perldoc and talking to Command Line: - 'Perl really seems to be a wonderful language, and all the special variablesand command line switches take an important part in it.' - 'Yes, but there is much more than that to Perl.' - 'Really?' - 'Yep. You should wait to read some of the other articles the author of thisone is thinking of writing.' - 'Wow... I can see why the user chose Perl.' - 'Yes, but it wasn't like that in the beginning.' - 'Really?' - 'Really. Things were a lot different, until the moment he had an epiphany,and heard a voice saying: "Don't try to do everything with the Bash. Instead,only try to realize the truth."' - 'What truth?' - 'There is no Bash.' How to install Win32::OLE under Linux? (dpavlin) I wanted to run [cpan://Win32::OLE]on my development machine which is Debian Linux. This tutorial is based onCrossOver Office Standard 4.1,but it should also work with Wine (not tested). Download and install Windows Installer 2.0 Redistributable for Windows 95, 98, and Me Download latestActive State Perl for Windows in .msi format.I used ActivePerl-5.8.6.811-MSWin32-x86-122208.msi. Note:I tried to install .zip format, but it didn't work for me. That'swhy you need first to install MSI 2.0 update. Start installation:$ /opt/cxoffice/bin/wine "C:~WB~WINDOWS~WB~SYSTEM~WB~msiexec.exe" /i ActivePerl-5.8.6.811-MSWin32-x86-122208.msi After a while, it should be over. Now you have perl installed in~/.cxoffice/dotwine/fake_windows/Perl/.Try to run it:$ uname -aLinux llin 2.6.10-1-686 #1 Tue Jan 18 04:34:19 EST 2005 i686 GNU/Linux$ /opt/cxoffice/bin/wine "c:\Perl\bin\perl.exe" -v You should get something like:This is perl, v5.8.6 built for MSWin32-x86-multi-thread(with 3 registered patches, see perl -V for more detail)Copyright 1987-2004, Larry WallBinary build 811 provided by ActiveState Corp. http://www.ActiveState.comActiveState is a division of Sophos.Built Dec 13 2004 09:52:01Perl may be copied only under the terms of either the Artistic License or theGNU General Public License, which may be found in the Perl 5 source kit.Complete documentation for Perl, including FAQ lists, should be found onthis system using `man perl' or `perldoc perl'. If you have access to theInternet, point your browser at http://www.perl.org/, the Perl Home Page. That's it!. It wasn't hard at all. Note:There are some problems however. While calling Excel via OLE works withCrossOver, if you have Excel started it will stop responding to GUI events.So, Excel window will look like it's frozen, but your scripts should be ableto communicate with Excel anyway. Update: I was totally wrong. Adding $excel->{Visible} = 1; fixed my problem. fvwm just doesn't know how to minimize running Excel. And, now assorted list of links to get youstarted with Excel and OLE automation. TPJ article is very good introduction needed for Linux-nerd like me.The Perl Journal #10 - Win32::OLE by Jan Dubois ActivePerl Help - Online Docs : Using OLE with Perl [id://153486] Using Perl XPath for converting Infopath XML files to Word Documents (karthik4perl) The other day I had filled out about 10 forms using Infopath. The problem is all Infopath documents are saved in XML and one cannot extract the contents of each XML Tag into simple text. I will explain how to extract information from XML tag and save it in a DOC format. You can then apply the same concept for the Infopath form to DOC conversion. So here goes... XPath is one of the many XML technologies you could use to traverse the XML Tree. If you access a file in your explorer, the path to your file may be in the format "C:\folder1\file1.txt". XPath uses similar concept to walkthrough your XML file which can be thought as a Parent Tree containing many child nodes. Lets take a very simple example. Suppose your XML file is in the following manner: BOOKS.XML File Perl Magic Karthik ORielly Perl for Dummies Mark ORielly Now you want to extract the necessary Book Information, i.e, the "Title" and "Author" of the Books. From the XML file the tags <title> and <author> should be extracted. Now in XPath you get the "title" tag's content by using the Path : //Books/Book/titleSimilarly for the "author" tag's content: //Books/Book/authorNow that you know what and how extract the information, its time to use Perl. The beauty of Perl is that you can materialize the idea in your mind into reality so easily. You got Perl modules to make your Life easy. I am going to use the XPath Perl module which is part of the XML module.You use the module by coding like this use XML::XPathNow you need to get the BOOKS.XML file into a variable and create a new XPath object. $file="books.xml";my $xp = XML::XPath->new(filename => $file); Open a WORD DOC file of the same name for conversion open(INFO3, ">$file.doc"); Print necessary information in the DOC file print INFO3 "Perl Xpath\n\n";print INFO3 "BOOK INFORMATION:\n\n"; Use the find method using the XPath object and give it the path. //Books/Book This will populate a Answer Node List which is used further to extract the tags <title> and <author> and print to the DOC file. $xp->find('//Books/Book')->get_nodelistThe resulting Perl File(BOOKEXTRACT.PL) is given below. BOOKEXTRACT.PL use XML::XPath; $file="books.xml"; my $xp = XML::XPath->new(filename => $file); open(INFO3, "+>$file.doc"); print INFO3 "Perl Xpath\n\n"; print INFO3 "BOOK INFORMATION:\n\n"; foreach my $book ($xp->find('//Books/Book')->get_nodelist){ print INFO3 "TITLE:"; print INFO3 $book->find('title')->string_value."\n"; print INFO3 "AUTHOR:"; print INFO3 $book->find('author')->string_value."\n"; print INFO3 "\n\n"; } print "Converted XML file into WORD file\n\n"; print $file." WORD document generated"; close(INFO3); *************************CODE*********************** After you run the PERL Script you will be presented with a DOC file of the same name as the XML file with the extracted information. Now that you know how to extract Tags and content into WORD DOC, you can apply the same method in the conversion of INFOPATH XML Files into WORD Documents. Hope this helps. Happy Coding. 20050113 Janitored by [Corion]: Fixed formatting 20050114 Unconsidered by [Corion]: was considered as move to Meditations (edit:14 keep:7 del:0) Perl Babysteps 1: Your First Simple Script (webfiend) Introduction This page is intended to provide the non-programmer with a gentle introduction to the Perl programming language. When you are done with it, you should feel ready to learn more. You will not be an expert, but you will be able to find the information you need to go farther. Beginners and experts alike should feel free to send suggestions about how to improve this tutorial. Installing PerlIt is very easy to find and install a copy of Perl for your operating system. How easy? Well, it's a single simple download, and you may already have it on your machine! WindowsWell, okay. If you are using a Windows machine, you probably don't already have Perl on your machine. But it's easy to get. You even have a couple different versions to choose from. ActivePerl This is the officially blessed version of Perl for Windows. It is released by ActiveState. ActivePerl can be downloaded for free, or you can order the ActiveCD from them. It comes with a wealth of widely used third-party libraries such as Tk, LWP, and the XML bundle. Whether you choose to download or purchase, here is your best starting point: http://www.activestate.com/Products/ActivePerl/ Perl on Cygwin On the other hand, maybe you prefer to have Windows with a touch of UNIX on top. First, I want to let you know that Perl is perfectly happy under Windows these days. But if you insist, or just happen to be curious, Perl is also available for Cygwin. Just rerun Cygwin's setup.exe program, and make sure that "Perl" is checked. Oh, and add an editor while you're at it, too. Maybe Vim or Emacs. Everybody ElseYou probably already have it, especially if you happen to be on a UNIX-based operating system such as Linux, FreeBSD, or Mac OS X. Seriously. Try the which command if you don't believe me. $ which perl /usr/bin/perl That'll teach you to doubt me. Just kidding. If you don't have it installed, you'll get a message along the lines of perl not found in .... Double-check to see if it's on your installation media. For OS X folks, you just need to install the Developer Disk. The Macho Geek Option: Compile From SourceWhatever operating system you are on, this is a valid choice. Still, there are a lot of options when building. It can be more than a little overwhelming. I would suggest you go with one of the available binary downloads while you're just starting out. Creating Perl ProgramsThe tradition in programming literature is to start by creating a program that prints a simple phrase, such as "Hello, World!" The idea is to give you some clue how much work is involved in creating a minimal program. I, for one, am not going to argue with tradition. Not this one, at least. Type the following into your text editor: # hello.pl # - Displays a warm greeting print "Hello, World!\n"; Save the file as hello.pl. We will run it in a few moments, but first, let's take a quick look at what we've got so far. CommentsOn each line, everything from # to the end of the line is a comment. Perl ignores comments, so they allow you to communicate with other people who read your code. Comments are very very good. When you come back to look at a complex script after a few months, you might forget what some block of code does, or why you chose one solution over another. Having the comments there help to remind you what you were intending, and generally serve to make it much easier sorting everything out. I like to start all of my scripts off with a quick header to describe the purpose of the program. Here is a rough template: # hello.pl # Displays a warm greeting. All we have is the name of the file and a brief description of what the program does. That is often all that you need, especially for simple scripts like this one. NOTE: The official documentation system for Perl is POD, or "Plain Old Documentation". It is powerful and widely used, but it is also beyond our scope for this stage of the tutorial. However, to give you a little taste of how much easier POD makes life, here is the first sentence displayed after you type the command perldoc -f print at the command line: Prints a string or a list of strings. You should read POD in 5 Minutes if you are curious to learn about how to format POD documentation for reading with the perldoc command. Now you would probably like to know how to actually run your program. Save the file you have been editing and switch to a command line. Make sure you are in the same directory as your script - this should be as simple as cd project_directory. Once you are in the right place, type the following into the command line: $ perl hello.pl Hello, World! $ Oh, what was the "\n" at the end of the string for? That is a fair question. It's a special code for the newline character. What's the newline character do? It's easier to show you what happens when you don't have it: print "Hello, World!"; Save it and run it. $ perl hello.pl Hello, World!$ Adding a newline character in the string tells Perl that you want to print a new line. Now do you see? All this is kind of cool, but it would be nice to customize it a little bit. Maybe we could change the program so that it says "Hello" to us personally. # hello.pl # Displays a warm greeting. my $name = "Brian"; print "Hello, $name!\n"; Now you might notice the semicolon at the end of each line. What? You noticed them before? Well, you're quicker than me. Perl recognizes the semicolon as the marker which ends one statement. So each statement must be terminated by a semicolon. Putting them on separate lines like that is something that Perl doesn't care about, but you might lose friends if you tried to put everything on one line. Now -- what? Another question? Okay, go ahead. What's that my doing? We use the word my to declare variables. Declaration is when we tell Perl that we have a variable we plan on using. The language doesn't require declaration, but it is good form, and you will find your code easier to debug later on as you learn more about clean programming. What's a variable? We'll get to that in a second. I'm impatient to see a running program! Save the file, and run it again. $ perl hello.pl Hello, Brian! $ There, I feel better. Let's move on to talking about variables. VariablesWe stored the string "Brian" in the variable name. A variable is basically just something you want the computer to remember so that you can get to it when you want it later. You can get a lot morecomplicated than that if you want, and a lot of programmers do. However, this definition should hold us over for a long time. The "$" symbol at the beginning tells Perl what kind of information this variable holds. Perl basically has two kinds of variables: Individual things like strings and numbers Collections of things like lists and dictionaries When you start digging in, you will see how broad of a generalization I've just made. Still, I think that this will last us until the end of this article, and the basic idea holds true for a lot of Perl programming. Anyways. Individual things are also called scalars by people who think that you don't have enough things to remember. Ah well, we'll get used to it. To their credit, "scalar" is a shorter term than "individual thing". Perl makes it easy to recognize a scalar, by making you prefix all scalar variables with a dollar sign. So $name is "the scalar variable name", or even "the individual thing called name". Eventually many Perl hackers end up calling it "dollar name". my $name = "Brian"; # My scalar variable called 'name' has the value "Brian" Having a program that displays the exact same message every time you run is nice when it comes to being consistent, but not so entertaining as a program. "What does it do?" "It prints out my name." "Oh." See? Boring. Let's make things a little more interesting. We could change the value of name in the code, but it might be a little tiresome to do this before showing it to each new person. How about making the program ask for a name? User interaction - a neat idea. print "What is your name? "; my $name = ; print "Hello, $name!\n"; We only made one small change, but I'll admit that there's a lot going on with that one change. Here's the short version: gets input from the user that you can save in a variable. There's a long version. Feel free to skip it if you just want to get on with it. The long version works out like this: The scalar $name is assigned the value of <STDIN> . <...> tells Perl that we want it to read a filehandle and hand the results back to us. A filehandle is a source of information. It could be an open file, but in this case it is STDIN. STDIN is the standard input stream - geek talk for "wherever we expect user input to be coming from". Most of the time, STDIN just means "keys the user enters from the keyboard". The result of reading from the filehandle (in this case, STDIN, which is in this case the text you entered from the keyboard) is stored in $name. There's a really long version, but I'm getting bored so we'll skip it for now. $ perl hello.pl What is your name? Brian Hello, Brian ! $ Hey, what happened? The exclamation is all the way on the next line! Calm down. Everything is going to be okay. Perl just counts the ENTER key at the end as a part of the input, and ENTER prints out as a newline ('\n' if you've been paying attention). Counting the newline is fine for reading text from a file, but it's a little inconvenient when you are handling input from the keyboard. Fortunately, there's the chomp function. What's it do? Let's ask perldoc -f chomp. On second thought, let's not. You can goright ahead, but I just did, and discovered that the docs for chomp are a little dense for today. Let's try mine: chomp removes the last character from a string, but only if that character is whitespace or a newline. Let's give it a try. print "What is your name? "; my $name = ; chomp($name); print "Hello, $name!\n"; You already know what chomp does, so running this script shouldn't provide any surprises: $ perl hello.pl What is your name? Brian Hello, Brian! $ ... and we're done! ConclusionNice work! You have begun to learn Perl by writing a complete program which gets input from a user and prints output including a modified version of their input. Stop for a minute and think about it. Yes, there is much more to learn, but you have dipped your toes into the pool. Now you can go out there and start learning about the huge and wild world of Perl programming. Additional ResourcesHere are a few links to resources that you can use while learning about Perl and how to use it for your own nefarious purposes. [Tutorials] [Where and how to start learning Perl] http://learn.perl.org http://www.perl.com/ http://perl.oreilly.com/ http://perldoc.perl.org/ Learning Perl is the book for the person who is just starting out with programming in Perl. There are a lot more, but I can't recall many of the links right now. I may put them up as time goes on. Update:(30 Dec 2004) Removed an aside about complicated script headers, since [Juerd] pointed out that Perldoc is a better choice for such information, and [Anonymous Monk] helped me realize that it may be a bit much to expect a total newbie to know when the extended information becomes necessary. If you want to know what that extended header looked like, check the first reply from [Juerd]. He was gracious enough to reproduce it in its entirety while making a much better suggestion. I also went ahead and did some formatting adjustments (replacing PRE blocks with CODE blocks). Threw in some suggested links from [kutsu], too. Update:(26 Jan 2005) Fixed several typographical errors pointed out by [erix] Update:(9 May 2006) Fixed a few markup issues and added link to http://perldoc.perl.org/ -- thanks [jdporter] Enabling GUI Debugging under Mod_Perl (mkirank) Greetings I Did the following to Enable GUI Debugging of Mod_Perl (Apache::Registry) scripts (I got this Information from different places ) , I have documented the steps followed and want to put it under the appropriate section (Suggest appropriate section) in perlmonks , This is my first attempt to writing a Setup Guide so am seeking the wise monks Inputs on the same. Please let me know your Feedback/Opinions and any suggestions Steps Followed Installed the following packages from CPAN 1.Tk Graphical User Interface ToolKit from CPAN (Tk-804.027.tar) 2. Installed the Apache-DB-0.09 3. Installed the Devel-ptkdb-1.1091.tar.gz Open the Apache::DB.pm file and change #require 'Apache/perl5db.pl'; Comment this line require 'Devel/ptkdb.pm'; Save the below code as file Db.patch #################################################################--- DB.pm2003/07/23 16:59:071.1+++ DB.pm2003/07/23 17:03:29@@ -39,6 +39,34 @@ return 0; } ++sub ptkdb ($$) {+ my ($class,$r) = @_;++ init();++ # need to have a list of authorized remote hosts+ $ENV{DISPLAY} = $r->get_remote_host.':0.0';+ $DB::connection_refused = 0; # try try again+ require 'Devel/ptkdb.pm';+ $DB::single = 1;+# bug workaround? Pressing "Return" button at toplevel makes ptkdb hang.+ $DB::subroutine_depth = 0 ;+ $DB::step_over_depth = -1 ;++ if (ref $r) {+ $SIG{INT} = \&DB::dbint_handler;+ $r->register_cleanup(sub {+ $SIG{INT} = \&DB::ApacheSIGINT();+ $DB::single = 0; # do not debug during withdraw+ $DB::window->close_ptkdb_window;+ });+ }++ return 0;+}++ 1; __END__################################################################# Save the below code as file Ptkdb.patch #################################################################--- ptkdb.pm2003/07/23 17:05:201.1+++ ptkdb.pm2003/07/23 17:51:09@@ -1105,8 +1105,21 @@ # Main Window -+eval { $self->{main_window} = MainWindow->new() ;+};+if ($@) {+ my $err = $@;+ my $r = eval { Apache->request }; # check if running under mod_perl+ undef $@;+ if ($r && $err =~ m/Xlib: connection .*? refused|Xlib: Client is not authorized|couldn't connect to display/) {+$DB::connection_refused = 1;+ $self->{main_window} = undef;+warn($err); # log the problem+ return;+ } + die $err;+} $self->{main_window}->geometry($ENV{'PTKDB_GEOMETRY'} || "800x600") ; $self->setup_options() ; # must be done after MainWindow and before other frames are setup@@ -1237,8 +1250,9 @@ $DB::window->{'event'} = 'run' ; $self->{current_file} = "" ; # force a file reset- $self->{'main_window'}->destroy ;+ $self->{'main_window'}->destroy if $self->{'main_window'}; $self->{'main_window'} = undef ;+ $DB::connection_refused = undef; # allow another try } sub setup_menu_bar {@@ -4048,7 +4062,12 @@ $^W = $saveW ; unless( $DB::ptkdb::isInitialized ) {- return if( $filename ne $0 ) ; # not in our target file+ if ( $filename ne $0 ) { # not in our target file+ # check if running under mod_perl+my $r = eval { Apache->request };+undef $@;+return unless $r;+ } &DB::Initialize($filename) ; } @@ -4063,6 +4082,11 @@ return ; } + if ( $DB::connection_refused ) { # X to remote host failed+ $@ = $DB::save_err ;+ return ;+ }+ $DB::window->setup_main_window() unless $DB::window->{'main_window'} ; $DB::window->EnterActions() ;################################################################# Install the DB.pm Patch Note Find the path of DB.pm and ptkdb.pm (on Linux You can use Locate command) patch /Apache/DB.pm < Db.patch Install the ptkdb patch patch /Devel/ptkdb.pm < Ptkdb.patch Add the Following Lines in Httpd.conf use Apache::DB (); Apache::DB->init; PerlFixupHandler Apache::DB->ptkdb Start the Httpd with the Following Command (this starts apache in a Single mode) /usr/local/apache/bin/httpd -X -D PERLDB Enable the X-Windows (there are some security considerations ..man xhost for more details.) xhost + When a request is sent the GUI pops up and we can go through the script (for the scripts that we run under Apache::Registry ) We need to step in on the below Line below eval & {$cv}($r, @_) } if $r->seqno; If your server is Linux and u are working on Windows you can do the same by using xterm Install cygwin Open cygwin export DISPLAY=localhost:0.0 X -multiwindow & xhost + xterm -display localhost:0 & ssh -X -l root export DISPLAY=localhost:0.0 xhost + 2004-12-03 Janitored by [Arunbear] - added readmore tags, as per Monastery [id://17558|guidelines] Updated [Steve_p] - moved to Tutorials per consideration Perl documentation documentation (brian_d_foy) I had too much free time today, so I created a new perl man page. It's been surprisingly useful for other people already. NAME perldocs - Perl documentation documentation SYNOPSIS This documents the perl documentation DESCRIPTION If you have perl, you should have the documentation. Before perl existed, it had no documention. Then version 1came along and that changed. As I write this, perl is up toversion 5.8 and it has over a thousand pages ofdocumentation that comes with perl itself. I generally advise people to read the documentation first,but it's too late for that in most cases, and even if youdid, it would take you a long time to finish. The trick isto know where to look to get what you need. Reading the Frickin' Manual The perl manual pages are on your system somewhere (unlessyou have Mac OS X, it seems: stay tuned for updates). Youcan use the perldoc command line program to read aparticular page. If you want to find out how to use it, usethe perldoc command to read its documentation. perldoc perldoc Any time you want to read a perl manual page, just tellperldoc to display that page. If I want to read perltoc, Iuse perldoc. perldoc perltoc Your system may also have the documentation in otherformats, such as HTML or Windows Help files. You can also read the perl docs on the web: http://perldoc.perl.org/. Enough POD to be dangerous POD is ``Plain old documentation''. It's a minimal plain text formatthat most perlers use to write things. Its format is explained inperlpod. perldoc perlpod You can look at the POD source with perldoc's -m switch. perldoc -m perlpod You can check your (or somebody else's) POD with podcheckeror the Test::Pod module. You can convert POD to other formats, including LaTeX, HTML,and text. Look for the pod2latex, pod2html, and pod2text.You need to give it the file name to convert, which you canget with perldoc's -l switch. pod2html `perldoc -l perl` > perl.html perltoc If you don't know which page you need to read, start with perltoc,which is the table of contents for the rest of the core perldocumentation. perldoc perltoc perlfaq Even if you are one in a million, that leaves 5,000 peoplejust like you, and if only 1 in a thousand use perl, that'sstill 5 perl programmers just like you. Every one of those5 people have already asked your question, twice. Theanswer might be in perlfaq somewhere. There are nine perlfaq pages, broken into broadcategories. perlfaq is a table of contents. You can search the perlfaq pages with perldoc's -qswitch. perldoc -q perldoc You can read the perlfaq online at http://perldoc.perl.org/perlfaq.html. Parts of the perlfaq are regularly posted to the usenet groupcomp.lang.perl.misc . If you want to see the latest version of the perlfaq, you cancheck out the sources from CVS. http://cvs.perl.org/viewcvs/cvs-public/perlfaq/ perlfunc perlfunc lists the documentation for each perl function, and althoughyou should read it through at least once in your life, you can read thedocumentation for a single function with perldoc's -f switch. perldoc -f localtime Modules Use the perldoc command to read the documentation forinstalled modules. perldoc Module::Starter CPAN Search Look on CPAN Search, http://search.cpan.org, fordocumentation on modules that you haven't installed. Randal's columns Randal has spent way too much time writing about Perl for itall to go to waste. Most of his columns are availableonline. http://www.stonehenge.com/merlyn/columns.html. Google Learn to use Google to find things. Use perl as a keyword.You only think this is obvious, but read the questions inusenet groups or on Perlmonks for a while to find outjust how many people can't use a search engine. For instance, you can limit your search to a particular sitewith in a Google search. This query limits itself to perldoc.perl.org site:perldoc.perl.org CGI You can search Randal's articles for ``deep copy'', site:www.stonehenge.com "deep copy" or search Perlmonks for @ISA site:perlmonks.thepen.com @ISA or search CPAN Search for ``pop3 ssl'' site:search.cpan.org POP3 ssl The Camel http://www.oreilly.com/catalog/pperl3/ You don't have to buy ``Programming Perl'', also known as theCamel book, but you also don't have to have any free timeeither. It's your choice. Every copy you buy supports starvingchildren in Mountain View. The Llama http://www.oreilly.com/catalog/learnperl4/ The Llama book is ``Learning Perl''. You don't have to learnPerl, but it helps. You'd be surprised how many people tryto get by without learning Perl. The Ram http://www.oreilly.com/catalog/perlckbk2/index.html A lot of people like ``The Perl Cookbook''. When you aren't readingits hundreds of pages for Perl recipes, it makes a darnedgood paperweight or a doorstop. Comprehensive Perl Archive Network (CPAN) Most of what you think of CPAN probably isn't: it's just the archive.CPAN Search, module uploads, CPAN.pm, and other things are not CPAN. CPAN has its own FAQ that explains it all. http://www.cpan.org/misc/cpan-faq.html Perl Authors Upload Server (PAUSE) PAUSE is the author interface to CPAN, and it has its own documentation. http://pause.perl.org/pause/query. -- brian d foy quotes in Perl (apotheon) Quotation marks are fairly ubiquitous in Perl, as in most programming languages. Different methods of quoting exist, and each has different uses and a different set of behaviors associated with it. This document is intended as a treatment of the subject of delimiting strings — "quoting". I try to keep it from devolving into lengthy digressions on tangential topics, such as escape characters and interpolation. Such topics do tie in with the use of such delimiters, however, and must to some degree be addressed. Further information can be found at [http://perldoc.perl.org/perlop.html|perlop]. single-quotes Single quotation marks are used to enclose data you want taken literally. Just as the <code></code> tags here at the Monastery make all text they enclose literally rendered, whitespace and all, so too does a set of single-quotes in Perl ensure that what they enclose is used literally: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = 'it is worth $foo';print $bar; This example, when run, produces the following: it is worth $foo double-quotes Double quotation marks are used to enclose data that needs to be interpolated before processing. That means that escaped characters and variables aren't simply literally inserted into later operations, but are evaluated on the spot. Escape characters can be used to insert newlines, tabs, and other special characters into a string, for instance. The values, or contents, of variables are used in double-quoted strings, rather than the names of variables. For instance: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = "it is worth $foo";print $bar; This example, when run, produces the following: it is worth 7 Double-quotes interpolate scalar and array variables, but not hashes. On the other hand, you can use double-quotes to interpolate slices of both arrays and hashes. escape characters The interpolating effects of double-quotes creates a necessity of using escaped characters to reproduce characters within a string that would be displayed literally within single-quotes, however. For instance, to add quotes to the above-printed string in the double-quote example, you would have to do something like this: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = "it is \"worth\" $foo";print $bar; The backslash "escapes" the quotation mark that follows it, so that running the above produces the following: it is "worth" 7 An exception to the literal interpretation behavior in the use of single-quotes is when you wish to include single-quotes inside the string. In that case, you must escape the single-quotes you want inside the string so the Perl compiler can discern between them and the single-quotes that delimit the string: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = 'it is \'worth\' $foo';print $bar; This example, when run, produces the following: it is 'worth' $foo In any interpolating quotation scheme, such as double-quotes (or qq and interpolating uses of <<, as described below), @ and $ characters must be escaped when you want them used literally. If they are not, they will be treated by the Perl compiler as indicators of variable names. quoting without quotes In Perl, you can use methods other than quotation marks to "quote" a string. This functionality makes using strings that contain quotation marks much easier sometimes, since those quotation marks no longer need to be escaped. There are three simple methods of doing this with the letter q. In the following three sections, on the subjects of q, qq, and qw notation, I refer exclusively to the use of parentheses as delimiters. Other delimiters can be used, however, which allows you to avoid having to escape the characters you choose to use as delimiters if you must also include instances of them in your string. For instance, instead of using parentheses, you could also use brackets ( [ ] ), braces ( { } ), asterisks ( * * ), and (almost?) any other characters other than whitespace. It's worth noting that in the case of an alphanumeric character there must be a space between the q (or qw, or qq). q The first way to quote without quotes is to use q() notation. Instead of using quotation marks, you would use parentheses with a q preceding them: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = q(it is 'worth' $foo);print $bar; This example, when run, produces the following: it is 'worth' $foo The q() function works the same as single-quoting your string, with the exception that you no longer need to escape single-quotes that appear within the string. You would, however, have to escape any parentheses you need in the string. qq In the same way that double-quotes add interpolation to the functionality of single-quotes, doubling the q adds interpolation to quoting without quotation marks. For instance, if you wanted to avoid escape characters and interpolate $foo in the above code, and wanted to use double-quotes around the word worth, you might do this: #!/usr/bin/perl -wuse strict;my $foo;my $bar;$foo = 7;$bar = qq(it is "worth" $foo);print $bar; This example, when run, produces the following: it is "worth" 7 qw You can use qw to quote individual words without interpolation. Use whitespace to separate terms you would otherwise have to separate by quoting individually and adding commas. This is often quite useful when assigning lists to array variables. The two following statements are equivalent: @baz = ('one', 'two', 'three');@baz = qw(one two three); here documents If you want to quote many lines of text literally, you can use "Here Document" notation. This consists of an introductory line which has two open angles (aka "angle brackets": << ) followed by a keyword — the end tag — for signalling the end of the quote. All text and lines following the introductory line are quoted. The quote ends when the end tag is found, by itself, on a line. For example, if the end tag is EOT: #!/usr/bin/perl -wuse strict;my $foo = 123.45;my $bar = "Martha Stewedprune";print <<"EOT";=====This is an example of text taken literally except that variables are expanded where their variable names appear. foo: $foo bar: $barEOT This example, when run, produces the following:=====This is an example of text taken literally except that variables are expanded where their variable names appear. foo: 123.45 bar: Martha Stewedprune The type of quotation marks placed around the end tag is important. For instance, in the above example, EOT is double-quoted, and as a result the values of $foo and $bar are substituted for the variable names. Double-quoting the end tag causes the quoted block of text to be interpolated as it would be with double-quotes. Use of single-quotes would cause it to be used literally, without interpolation, as though the quoted block of text were delimited by single-quotes rather than being referenced as a "here document". Omitting the quotation marks entirely defaults to behavior the same as using double-quotes. some notes to keep in mind: The end tag specifier must follow the << without any intermediate space. The actual end tag must be exactly the same as specified in the introduction line. The introduction line must end with a semicolon. The use of here documents is particularly useful in Perl scripts that include HTML and other markup, because it allows you to keep the markup relatively free of escape characters that would otherwise reduce the readability of it. Thanks due the PerlMonks community members who contributed suggestions and comments in discussion below. - apotheon CopyWrite Chad Perrin Recursion: The Towers of Hanoi problem (DigitalKitty) Hi all. Many computer science professors eventually discuss the concept of recursion. To help illustrate the power and elegance (yes, there are drawbacks as well) it provides, a classic problem known as the 'Towers of Hanoi' is often used.For those unfamiliar with this classic, please allow me explain the history and rules... The History: The puzzle is called "Towers of Hanoi" because an early popular presentation wove a fanciful legend around it. According to this myth (uttered long before the Vietnam War), there is a Buddhist monastery at Hanoi which contains a large room with three time-worn posts in it surrounded by 21 golden discs. Monks, acting out the command of an ancient prophecy, have been moving these disks, in accordance with the rules of the puzzle, once every day since the monastery was founded over a thousand years ago. They are said to believe that when the last move of the puzzle is completed, the world will end in a clap of thunder. Fortunately, they are nowhere even close to being done. The Rules: There are n disks (1, 2, 3,..., n) and three towers (pegs). The towers are labeled 'A', 'B', and 'C'. All the disks are initially placed on the first peg (the 'A' peg). No disk may be placed on top of a smaller disk. You may only move one disk at a time and this disk must be the top disk on a peg. The Code: use warnings;use strict;# Towers of Hanoi# Perl version (5.8.0)# Ported from Javamy $numdisks = 0;print "Number of disks? ";chomp( $numdisks = );print "The moves are:\n\n";movedisks( $numdisks, 'A', 'B', 'C' );sub movedisks { my( $num, $from, $to, $aux ) = @_; if( $num == 1 ) { print "Move disk $num from $from to $to\n"; } else { movedisks( $num-1, $from, $aux, $to ); print "Move disk $num from $from to $to\n"; movedisks( $num-1, $aux, $to, $from ); }} Any suggestions on how to 'fine tune' this program are more than welcome. Hope this proves interesting. Thanks, ~Katie20041023 Edit by [Steve_p]: Changed title from 'Visiting the Towers of Hanoi.' Using the SNMP module from the Net-SNMP library (Rhys) Where to get Net-SNMP You can get the Net-SNMP library package from http://net-snmp.sourceforge.net/. If you have RedHat Linux 9 or RedHat Enterprise Linux 3, you can install the net-snmp-5.0.9 packages from you installation CDs (or from RedHat Network, if you are fortunate enough to have access).If you install from source, you will need to compile and install the libraries, then cd into the 'perl' directory and install the Perl module separately. If you install using RPMs from RedHat, you need the net-snmp-perl package and all of its dependencies. If you build from the src.rpm package, make sure you use --with perl_modules. NOTE: If you use RPM, I highly recommend uninstalling the 5.0.9 packages provided by RedHat, getting the 5.1.x src.rpm, and rebuilding from there. Version 5.1 resolves a problem that causes 'make test' to fail any time you use MakeMaker. Everything actually works, but you can't test anything. Update:As of January, 2005, version 5.2.1 of Net-SNMP is available. I have had no trouble with it so far. Do Not Confuse Net-SNMP with Net::SNMP! The naming is unfortunate, but the SNMP module that comes with the Net-SNMP package is just 'SNMP'. The Net::SNMP module is a completely different beast. Confusing the two will get you in big trouble. Here's the test: use SNMP; # This is Net-SNMP.use Net::SNMP; # This is NOT. DO NOT USE WITH THIS TUTORIAL! Also, remember that the Net-SNMP package began life as UCD-SNMP, since it was originally sponsored and maintained by the University of California - Davis. It was renamed in version 5.0 and has moved to SourceForge. In fact, if you do install SNMP from CPAN, you get the 4.2.0 module from the UCD-SNMP package. It will probably work with most of what you see here, but I recommend getting the 5.1 package if you can. Try Some Trivial Queries Before we get to the advanced stuff, let's make sure it's working. You will need to have a device attached to the network that will respond to SNMP queries (you can use 'localhost' if snmpd is running). Edit the script below to suit your environment and try it. #!/usr/bin/perluse warnings;use strict;use SNMP;use Socket;# VARIABLES YOU SHOULD EDIT.my $comm = 'public'; # EDIT ME!my $dest = 'localhost'; # EDIT ME!my $mib = 'sysDescr'; # Toy with this to get different # results.my $sver = '2'; # EDIT ME!# VARIABLES YOU SHOULD LEAVE ALONE.my $sess; # The SNMP::Session object that does the work.my $var; # Used to hold the individual responses.my $vb; # The Varbind object used for the 'real' query.# Initialize the MIB (else you can't do queries).&SNMP::initMib();my %snmpparms;$snmpparms{Community} = $comm;$snmpparms{DestHost} = inet_ntoa(inet_aton($dest));$snmpparms{Version} = $sver;$snmpparms{UseSprintValue} = '1';$sess = new SNMP::Session(%snmpparms);# Turn the MIB object into something we can actually use.$vb = new SNMP::Varbind([$mib,'0']); # '0' is the instance.$var = $sess->get($vb); # Get exactly what we asked for.if ($sess->{ErrorNum}) { die "Got $sess->{ErrorStr} querying $dest for $mib.\n"; # Done as a block since you may not always want to die # in here. You could set up another query, just go on, # or whatever...}print $vb->tag, ".", $vb->iid, " : $var\n";# Now let's show a MIB that might return multiple instances.$mib = 'ipNetToMediaPhysAddress'; # The ARP table!$vb = new SNMP::Varbind([$mib]); # No instance this time.# I prefer this loop method. YMMV.for ( $var = $sess->getnext($vb); ($vb->tag eq $mib) and not ($sess->{ErrorNum}); $var = $sess->getnext($vb) ) { print $vb->tag, ".", $vb->iid, " : ", $var, "\n";}if ($sess->{ErrorNum}) { die "Got $sess->{ErrorStr} querying $dest for $mib.\n";}exit; Whew! That's a lot of code just for a couple of simple queries! There are a lot of comments, and the code demonstrates the two most common ways of getting SNMP data from an agent (single query or loop through some unknown number of instances). Your coding style may be more succint, and you may not need some of the error checking. Proceed without it at your own peril, though. And Now, A Few Words About MIBs It might be worth defining a few terms before we go on: MIB Strictly speaking, the Management Information Base or "MIB" is a database of information that you can query from an SNMP agent. In practice, the term 'MIB' by itself is confusing. It is much better to be more specific and use one of the other terms here. MIB module The actual specifications and definitions for a MIB, found in a file somewhere on your system. It begins with 'YOUR-MIB-NAME DEFINITIONS ::= BEGIN' and ends with 'END'. It is best to load MIB modules by name, since this allows Net-SNMP to do all of the file-searching for you, rather than hard-coding in file names. This puts the onus on you to make sure there's only one file in your search path with definitions for a given MIB. MIB file A MIB file is just a text file that contains one or more MIB modules. NOTE: Net-SNMP has problems loading files with more than one MIB module in them. In my experience, it only parses the first module properly. This is a bug in Net-SNMP. Please let me know if this has been solved so I can upgrade both my libraries and this file. MIB object A single item in a MIB specification such as 'sysDescr'. This is what people usually mean when they say they are 'looking for a MIB' or have been 'querying a bunch of MIBs'. Each MIB object has a type (integer, string, enumerated, etc.). MIB objects are queried by asking the agent to return one or more instances of that object (more on this later). Each instance of a MIB object has a value (which can be NULL). MIB tree Another, clearer term for describing the entire MIB. The MIB itself is laid out in a tree structure, with MIB objects as the leaf nodes. Each node is identified both by number (positive integers or zero) and by name (which is NOT guaranteed to be unique). The tree layout is very flexible and provides an absolute unique path to every MIB object. Each MIB module loaded adds new branches to the MIB tree and allows you to query the objects defined in the new module(s). And Now, a Few Other Terms I addressed 'MIBs' first because there is so much confusion about that term. There are also a few other things you'll need to recognize in order to use SNMP correctly: 'tag' - In this context, this is the same as the MIB object name. In your Varbinds, the tag value will get updated as part of a query, so keep an eye on it. If you do a getnext, you'll get an answer, even if the next object in the agent's MIB isn't in the same table. You might ask for the next physical in the ARP table and get the first IP address in the table. You've jumped to the next MIB object. Watch your tags. 'oid' - This is the Object ID. A fully qualified OID is a long dotted-decimal string that shows how to get from the root of the MIB tree to the particular MIB object you're working with. Example: The OID for 'sysDescr' is '.1.3.6.1.2.1.1.1'. Note the leading dot. Like in DNS, the optional leading dot makes the OID an absolute reference. OIDs can also be relative. Again, be careful. 'iid' - This is the Instance ID. For some MIB objects, there is only one possible value, or instance, like with 'sysLocation'. In those cases, the instance ID will be zero. In other cases there can be a list of values, like the different network interfaces on a system (eth0, eth1, eth2), so the instance numbers will be positive integers, probably - but not necessarily - incrementing in a simple way (e.g. '1', '2', '3'). In still other cases, the SNMP agent may decide to keep some data in a more hash-like way, like in the ARP table (think $ARP{'ip'} = $mac;). In that case, the instance ID will be complicated, like '0.10.4.15.2.45'. In every case, the Instance ID is the sub-identifier that gets tacked onto the end of the OID to specify that particular value. Here are some examples: sysDescr.0 - Only one instance, so the IID is zero. ifIndex.1 - Probably a simple list, so the IIDs start with one and increment. ipNetToMediaPhysAddress.2050.10.1.1.50 - This is the hash-like IID. In this case, '10.1.1.50' was the IP address learned on the interface whose ifIndex is '2050'. The value of this object is something like '00:08:ad:44:13:62'. So the IID is '2050.10.1.1.50' which is like a 'key' in the 'hash' for 'ipNetToMediaPhysAddress'.Your mileage will vary both among different MIB objects and different agents you query. I have seen different routers respond at least three different ways to queries for the same MIB object. (Each router answers the same all the time, but the different routers' answers differ from each other.) In theory, this shouldn't happen, since the same MIB object should be defined the same way in every case, so the routers should all respond in the same way. I have learned to be paranoid about this anyway, and make no assumptions about the returned data. And Now, We'll Add Enterprise MIB Files Net-SNMP comes with plenty of RFC-defined MIB modules, usually stored in /usr/share/snmp/mibs. However, most of the really good info you want from an SNMP agent is stored in the proprietary Enterprise MIBs (dum dum DUM!). These MIBs are stored in the 'enterprises' MIB subtree. Each vendor has its own identifier (e.g. 'cisco', 'nortel', 'rapidCity'), and under that, the vendor is free to create all the subtrees and objects they want. But for you to be able to get to them, you need to get Net-SNMP to parse the definitions for all this great stuff. You need to get it to load the MIB modules for your enterprise MIBs.This is really a two-part problem. First, where are you going to keep the MIB files themselves? Second, how are you going to get the files imported when you go to do SNMP queries? I'll tell you how I did it, and hopefully you'll e-mail me if you find some horrible deficiency in this method. Look, I Just Want to Load One File! Fine. Here's the fastest - and most unwise - way to do it. It works, of course, but you'll soon find that this method is rife with practical problems:&SNMP::addMibFiles("/path/to/some/file.mib");&SNMP::initMib(); So What's So Bad About That? Since you asked, I'll tell you.First, that's a hard-coded path to a particular file. The path may change. The file name may change, which happens a lot when vendors mark the version of a MIB module in the file name. This method is extremely resistant to change. Second, what if this MIB module requires that you load another module first? Done this way, you'll probably have to load all of the pre-requisite files by hand before this one will work, especially if the prereqs are other enterprise MIB modules. There's a better way. Let's go back to the beginning and pretend we want to do things the Right Way(tm). Where to Put the Files If you installed from RPM, the MIB files the come with Net-SNMP are put in /usr/share/snmp/mibs (or /usr/local/share/snmp/mibs if you installed from source). Every time I added a group of related MIBs files, I put them in a subdirectory under this one. For example, I wrote a program called JScan, and put several subdirectories named JScan/APC, JScan/BayStack, etc. for a full path of /usr/share/snmp/mibs/JScan/APC. This kept all of the files separate (so 'rm -r ..../JScan' would get rid of them all in a pinch), but in a predictable and sensible place.Then a second problem presented itself. I decided it was a pain to add that many search directories all of the time (discussed below), so I created a single directory /usr/share/snmp/mibs/JScan/everything that contains symbolic links to all of the actual files in all of the other directories. This is done at install time by this excerpt of the post-install script: # Where $destdir is /usr/share/snmp/mibs in most cases...system "mkdir -p $destdir/JScan/everything ; cd $destdir/JScan/everything ; find .. -type f -exec ln -sf {} \\;"; I then installed the MIB files for other packages in other subdirs under /usr/share/snmp/mibs. Again, keeps things separate, but still in more or less the Right Place. Known Problem: While this has not happened to me yet in practice, it is possible that two vendors may name their MIB files with the same name, in which case 'ln' above will return an error when it tries to create the second link. This has never happened to me yet, though I have the practice of pulling the RFC-based MIB files out of the vendor-supplied list before I split them up, which resolves a LOT of conflicts. Get Perl to Read Your MIB Files There are several ways to do this, but in my opinion the best way is as follows. Suppose I wanted to load the MIB modules 'S5-CHASSIS-MIB', 'RAPID-CITY', and all of their pre-requisites. I would do this:# Add the search directory.&SNMP::addMibDirs("/usr/share/snmp/mibs/JScan/everything");# Load the modules AND their pre-reqs.&SNMP::loadModules('S5-CHASSIS-MIB', 'RAPID-CITY');# Wonder-Twin powers, ACTIVATE!&SNMP::initMib(); In the example shown, the directories /usr/share/snmp/mibs AND /usr/share/snmp/mibs/JScan/everything will be searched for a file with the S5-CHASSIS-MIB module. It will then load that file. Since the S5-CHASSIS-MIB also requires the S5-ROOT-MIB, those same directories will be searched again for the file containing THAT MIB module, and so on until all the necessary modules have been loaded, or until something fails. If I load a non-existent module THIS-AND-THAT on my system, I get:Cannot find module (THIS-AND-THAT): At line 1 in (none) You can, of course, turn this off and make it fail silently, but by default it won't cause your script to fail. The MIB parsing errors can be turned on or off in your snmp.conf file.Other Useful Bits There are several other ways you can get Net-SNMP to add directories to your search path and/or automatically load MIB modules. See the snmp.conf(5) man page for more details, paying particular attention to the parts about the MIBS and MIBDIRS environment variables and the ~/.snmp/snmp.conf file, which might be more appropriate than making system-wide changes. Review At this time, I would like to suggest that you go back to Try Some Trivial Queries and play for a bit. Re-write this code in your own style, taking the time to understand as much of it as possible. Try loading some MIB modules and querying new stuff from those modules. Get used to OIDs, IIDs, values, and MIB object definitions before you proceed to the next section, in which we start doing the dangerous stuff (changing things on a remote agent). Setting MIB Object Values Okay, so we've covered how to get Net-SNMP, load new MIB modules, and query some MIB objects. Suppose now that you want to use Net-SNMP to set the value of a read/write MIB object, such as sysName or sysLocation. This is actually pretty simple... most of the time. Take these two objects for instance. Here's the code to set the value of sysName on a host:my $comm = 'ihavepower'; # Use read/write community.my $dest = '10.1.1.1'; # IP or DNS will work.my $sver = '2'; # Use 1 for simple devices, and 3 if you # really know your SNMP security.my %snmpparms;$snmpparms{Community} = $comm;$snmpparms{DestHost} = inet_ntoa(inet_aton($dest));$snmpparms{Version} = $sver;$snmpparms{UseSprintValue} = 1;my $sess = new SNMP::Session(%snmpparms);my $mib = 'sysName';my $instance = '0'; # There's only one instance of sysName.my $value = "New system name.";my $vb = new SNMP::Varbind([$mib,$instance,$value]);# This does it!$sess->set($vb);if ( $sess->{ErrorNum} ) { print "Got $sess->{ErrorStr} setting $mib on $host.\n";} This works for most things. However, I have run into a lot of trouble when trying to set values that aren't strings or integers when I have set UseSprintValue to true, which I usually do, since subsequent queries using the same session make FAR more sense with UseSprintValue (which translates enums and some packed binary values into readable strings for the user). Setting packed binary values, in particular, is a pain. Fortunately, all you need is a second session to cure this:my $comm = 'ihavepower'; # Use read/write community.my $dest = '10.1.1.1'; # IP or DNS will work.my $sver = '2'; # Use 1 for simple devices, and 3 if you # really know your SNMP security.my %snmpparms;$snmpparms{Community} = $comm;$snmpparms{DestHost} = inet_ntoa(inet_aton($dest));$snmpparms{Version} = $sver;$snmpparms{UseSprintValue} = 0;### NEW SESSION REQUIRED!my $sess2 = new SNMP::Session(%snmpparms);my $mib = 'some32BitMib'; # Suppose it takes a packed IP.my $instance = '0'; # Will vary with the MIB object.my $value = inet_aton($ipaddr);my $vb = new SNMP::Varbind([$mib,$instance,$value]);$sess2->set($vb);if ( $sess2->{ErrorNum} ) { print "Got $sess2->{ErrorStr} setting $mib on $host.\n";} Note that it's almost entirely the same except that UseSprintValue is set to zero when the SNMP session object is created. Using VarLists Sometimes you want to query a bunch of different SNMP values on the same device. You could query each of them one at a time, but if you want to conserve bandwidth or if you're trying to keep several variables in sync it's a lot easier to use a VarList.So what's a VarList? A VarList is a blessed reference to an array of Varbinds (so you can't just do push @varbinds, $vb; in a loop and expect that to work). So basically, a VarList is a bunch of Varbinds stuck together so you can make many queries at once. Let's walk through two examples of using VarLists and see how they work. Here we create a VarList and query a device for the variables 'sysName', 'sysDescr', and 'sysLocation'. We're assuming that the session is already created and we're going to just query instance 0, since we know from experience that this is the only instance that exists for these MIB objects. $MIB[0] = 'sysName';$MIB[1] = 'sysDescr';$MIB[2] = 'sysLocation';$vl = new SNMP::VarList([$MIB[0], 0], [$MIB[1], 0], [$MIB[2], 0]);@ANSWERS = $sess->get($vl); And that's it! Instead of using one array constructor with "MIB, instance, value" inside of it like with a Varbind, you just create a list of them. Now let's do that same query above, but this time we'll use a loop to create an array of Varbinds. For this example, it's trivial, but this can make for an elegant solution in some cases and save you a lot of code and a lot of bandwidth. @MIBS = ('sysName', 'sysDescr', 'sysLocation');foreach $mib ( @MIBS ) { push @bunchovbs, new SNMP::Varbind([$mib,0]);}# Now the magic!$vl = new SNMP::VarList(@bunchovbs);@ANSWERS = $sess->get($vl); This method is most useful when the instance number or the value you need in the Varbind is only known after some calculation AND you want to put several MIB objects in the same get or set action. Here's a more useful example of using a VarList:@MIBS = ('ifAdminStatus', 'ifOperStatus', 'ifSpeed');$vl = new SNMP::VarList([$MIBS[0]], [$MIBS[1]], [$MIBS[2]]);for ( $ifindex = 1 ; $ifindex < 25 ; $ifindex++ ) { @STATUS = $sess->getnext($vl); if ( $STATUS[0] eq 'up' ) { print "Port $ifindex enabled.\n"; } else next; print " Link status is $STATUS[1]. Speed is $STATUS[2].\n";} Now we skipped all the setup and there's absolutely no error checking in the loop shown, but you can see how using VarLists can drastically shorten the process of getting (or setting) several MIB objects at once.TIP: One problem I've come across when using VarLists in this way is that in some cases the getnext causes one of the MIB objects in the list to get a different instance number than the others. Suppose in the example above that the switch does not keep a value for 'ifOperStatus' at all if 'ifAdminStatus' is 'down'. If port 2 is disabled, then on the second query, the instance ID for $$vl[0] will be 2, but for the other two objects the instance will be 3 (assuming port 3 is enabled). The getnext is performed on all of the MIBs regardless of the success or failure or values of the other MIBs in the same query SNMP doesn't magically 'know' you want the objects in your VarList to be in sync. SO: When using VarLists, even though you're querying them all at once and they share a packet, they are separate queries, so if you want them to stay in sync, you may need to add code to make sure they actually do. Check that all of the instance IDs are the same after each query and then do whatever is appropriate to resolve it when they turn up unequal. Sometimes a getnext will skip an instance, but going back and doing a get on that same instance will return the information you want. Getting Many Values in ONE Query So far, we have been using SNMP commands that were defined in version 1 of the SNMP specification: GET, GETNEXT, and SET. In version 2, the SNMP designers decided that they wanted a way to send a single query that would return N values of a single object, like doing 20 "GETNEXTs" at once. To do this, they created the GETBULK command.The syntax for the getbulk method in the SNMP module is a little complicated. Here's what perldoc has to say about it: $sess->getbulk(, , ) do an SNMP GETBULK, from the list of Varbinds, the single next lex- ico instance is fetched for the first n Varbinds as defined by . For remaining Varbinds, the m lexico instances are retrieved each of the remaining Varbinds, where m is . So the first two arguments, non-repeaters and max-repeaters are integers that define how getbulk is going to behave, and the remaining arguments are Varbinds (or better, a VarList). Now getbulk is a little tricky. It's behaves like a bunch of getnext commands strung together. If non-repeaters is set to '4', it will take the first four Varbinds in the list given and get their next values exactly once (as if you had used getnext on each of them). Then if we suppose that max-repeaters is set to '10', getbulk will behave like a getnext on the remaining Varbinds 10 times as a list. So it doesn't get the next 10 of the first Varbind, then get 10 of the next Varbind, and so on, but rather it does 10 getnext's on the list (just as if you had used a for loop on a VarList). So let's take an example that I threw together that queries some basic stuff about a 24-port switch, and hopefully things will become clearer: use SNMP;use Socket;# Set up the SNMP session.my %snmpparms = ();$snmpparms{DestHost} = inet_ntoa(inet_aton($host));$snmpparms{Community} = 'public';$snmpparms{UseSprintValue} = '1'; # readable!$snmpparms{Version} = '2'; # MUST USE 2 for GETBULK!my $sess = new SNMP::Session(%snmpparms);# I prefer to use VarLists for this sort of thing, since# we have enough confusion without making the actual# getbulk() call complicated.my @vbs = ();foreach my $mib ( 'sysName', 'sysDescr', 'sysLocation', 'sysUpTime', 'ifIndex', 'ifAdminStatus', 'ifOperStatus' ) { push @vbs, new SNMP::Varbind([$mib]);}my $vl = new SNMP::VarList(@vbs);# We'll keep our answers in these.my %sysStuff;my @ANSWERS;# Query the first four objects ONCE EACH, and store the# answers in the appropriate places in %sysStuff.# Then get ifIndex and ifAdminStatus 24 times and store# all of those reponses in @ANSWERS.($sysStuff{Name}, $sysStuff{Descr}, $sysStuff{Location}, $sysStuff{UpTime}, @ANSWERS) = $sess->getbulk(4, 24, $vl); # AT LAST!# Always, always, always...if ( $sess->{ErrorNum} ) { die "Got ", $sess->{ErrStr}, " during getbulk.\n";}# So $ANSWERS[0] now contains the first value of ifIndex.# $ANSWERS[1] contains the FIRST VALUE OF ifAdminStatus,# NOT the second value of ifIndex.# The remaining code could be MUCH simpler, but it's done# this way to illustrate how the answers are returned.my @INDEXES;my @STATUS;for ( my $x = 0 ; @ANSWERS ; $x++ ) { # Smart people would probably use map() for this. # I'm not that smart... $INDEXES[@INDEXES] = shift @ANSWERS; $STATUS[@STATUS] = shift @ANSWERS; # So we round-robin between @INDEXES and @STATUS, # thus "unstriping" the responses stored in @ANSWERS.}print "Name: $sysStuff{Name}\n";print "Description: $sysStuff{Descr}\n";print "Location: $sysStuff{Location}\n";print "Uptime: $sysStuff{UpTime}\n";print "\n";# This now prints out clearly.for ( my $x = 0 ; $x <= $#INDEXES ; $x++ ) { print " INDEX: $INDEXES[$x] STATUS: $STATUS[$x]\n";} So we asked for four non-repeaters, sysName, sysDescr, sysLocation, and sysUpTime. We also ask for 24 instances of ifIndex and ifAdminStatus. The first four objects are queried once each, then the 24 answers for ifIndex and ifAdminStatus are "striped" together, and we use a simple for loop to break them apart again. Now, if this were a real program, we would have just used @ANSWERS directly in the outputfor loop at the bottom and done $x+=2 for each iteration and saved a lot of code and extra variables, but I digress... Using the getbulk command with max-repeaters set to less than '2' is silly, though it can be used with non-repeaters set to '0'. There is no requirement to have any non-repeaters in your query. WARNING: The getbulk command is not the Hold Grail of Supah-Queries. You can't just ask it to return 1000 instances, because SNMP will only send one packet in reply. SNMP can't fragment its responses into multiple UDP messages, and won't send a single UDP message that would cause the IP packet to be fragmented either, so you'll have to use getbulk with a little circumspection. I've found that I can safely pack about 75 small queries (for 'ifAdminStatus', say) into a single getbulk, but that's about it. CHECK YOUR RESPONSES! NOTE: It should be noted that I haven't tried to see if this limitation still exists in SNMP version 3 when using TCP instead of UDP. If anyone gets large queries to work using this - or any other - method, PLEASE let me know. You can imagine how much simpler it would make large queries. Planned: Using the callback (SNMP in the background!) Using SNMPv3 (NO MORE CLEARTEXT 'PASSWORDS'!) Quick and Dirty Synopses of Planned Stuff for the Impatient Heh. This is also to help motivate me to get this writeup finished. Perhaps it will help you make sense of the documentation you hopefully referred to already. Using the callback - The short version of this is you pass get(), getnext(), or getbulk() a reference to a subroutine that should be executed when the response arrives (works with the SET commands as well). Then you run a waiting function to sit and allow them all to be processed. Can seriously speed up things like querying many different devices. SNMPv3 - User names, passwords, authentication, and privacy. Using the authentication feature means you may or may not have to supply a user name and password (as opposed to a plain ol' community) when you query the device. Using the privacy feature means you can set up an encrypted session (typically TLS) for your queries, so people can't see your user/pass or communities or the data you asked for, any of which could be considered sensitive data.Sorry I don't have time (well, patience) to write more on these topics at the moment. I promise to get back to it, though. They say the best way to learn is to teach. Well, I've learned a bit myself while writing this. Suggestions on re-organizing and/or reformatting this document are welcomed. Flames and pointless criticisms can be sent to 127.0.0.1:25. Including files (Juerd) No include Some simple languages, like PHP, offer an include() to include a file literally. Perl does not. Then how can you still load code from other files? There are many ways to do this in Perl, but there is no easy way to get close to what most people expect of an include(). People who want to include files usually come from simpler languages, or have no programming experience at all. The hardest thing they will have to learn is that you should not want to include a file. That may sound harsh, but it's a Perl reality. In Perl, we don't include or link libraries and code reuse isn't usually done by copying and pasting. Instead, Perl programmers use modules. The keywords [use] and [require] are meant for use with modules. Only in the simplest of situations you can get away with abusing [require] as if it were some kind of include(), but it's easy to get bitten by how it works: it only loads any given file once. Creating a module What is a module, anyway? [perlmod] defines it as: just a set of related functions in a library file, i.e., a Perl package with the same name as the file. Creating a module is EASY, but it is a little more work than just creating a file with code in it. First, you need to think of a module name. This is the basis for both the filename and the package name, and these have to be synchronised for some features to work. For project specific modules, I always create a new top-level namespace with the name of the project. For example, NameOfTheProject/SomeModule.pm is a good filename (in real life, use something a little more meaningful). The corresponding package is NameOfTheProject::SomeModule. Use CamelCaps like this, because everyone else does too. The file must be in a directory that is listed in @INC. To find out what your @INC is, run perl -V. The current working directory (listed as its symbolic name . (a single dot)) should be listed. To begin with, putting the module in the script's directory is a good idea. It is the easiest way to keep things organized. If you want to put the module somewhere else, you will have to update @INC, so that perl knows where to find it. An easy way to do get code like this in the main script: use lib 'path/to/the/modules';# The example module could be path/to/the/modules/NameOfTheProject/SomeModule.pm What goes in the module itself doesn't require much explanation. I'll just give a complete example of a simple NameOfTheProject::SomeModule: use strict;package NameOfTheProject::SomeModule;sub some_function { # put sane code here return 123;}1; Just list all the subs as you usually would, put a [package] statement at the top and a true value at the bottom (1 will suffice). Obviously, [use] [strict] is a good idea. You should never code a module that does not have this. Beware: A use strict; statement in the main script has no effect on the module. A module runs only once. That means that for code to be reusable, it must be in a sub. In fact, it's considered very bad style to do anything (except declaring and initializing some variables) in the module's main code. Just don't do that. You can now load the module and use its sub, simply by doing: use NameOfTheProject::SomeModule;print NameOfTheProject::SomeModule::some_function(); # prints 123 You can have the module export its sub(s) to the caller's namespace (that is: the package the [use] statement is in. By default, this is main). For this, put after the [package] statement: use base 'Exporter';our @EXPORT_OK = ('some_function'); Then, when [use]ing the module, you can request that some_function be imported to your namespace with:use NameOfTheProject::SomeModule ('some_function');print some_function(); # prints 123 To have it exported automatically, use @EXPORT instead of @EXPORT_OK. This will eventually bite you if the function names are generic. For example, many people get bitten by [cpan://LWP::Simple]'s get function. It is not unlikely that you already have one. There are more ways to export functions. I of course prefer to use my own module [cpan://Exporter::Tidy]. Not only because it's smaller and often faster, but mostly because it lets the user of a module define a prefix to avoid clashes. Read its documentation for instructions. For the export/import mechanism, it is very important that the filename, the package name and the name used with [use] are equal. This is case sensitive. (Ever wondered why under Windows, use Strict; doesn't enable [strict], but also doesn't emit any warning or error message? It has everything to do with the case insensitive filesystem that Windows uses.) Stubbornly still wanting to include Sometimes, a module just isn't logical. For example, when you want to use an external configuration file. (Many beginners and people who post code online put configuration in the script itself for ease of use, but this makes upgrading the script harder.) There are many configuration file reader modules you can use, but why use one of those if you can just use bare Perl? This is where [do] comes in. What [do] does is very close to what an [include] would do, but with a very annoying exception: the new file gets its own lexical scope. In other words: a variable declared with [my] is not accessible externally. This follows all logical rules attached to lexical variables, but can be very annoying. Fortunately, this does not have to be a problem. [do] returns whatever the included script returned, and if you make that script just the contents of a hash, here's my favourite way to offer configurability: # This is config.plmirror => 'http://www.nl.example.com/mirror',path => '/var/www/example',skip_files => [ 'png', 'gif', 'jpg' ], (The last , is optional, but it's included to make adding a line easier.)# This is script.pluse strict;my %config = do 'config.pl';chdir $config{path};... Error checking is left as an excercise. Because we used only the return value of the script, and never even touched a variable in config.pl, the inaccessibility of lexical variables is no longer a problem. Besides that, the code looks very clean and we have a very powerful config file format that automatically supports comments and all kinds of useful functions. How about interval => 24 * 60 * 60, for self-documentation? :) Still not good enough [do] updates %INC, which you may or may not want. To avoid this, use [eval] [cpan://File::Slurp|read_file] instead. To find out if you want this, read [perlvar]. There is a way to get an include() the way other languages have it. This is a very ugly hack that uses an internal exception made for Perl's debugger, and is possibly not future proof. As said before, you should not want to include a file. Still, because it is possible, I feel I have to tell you how. Just don't actually use it. If you read the documentation for [eval] (which you of course should (don't use an operator without having read its documentation first)), you see that if it is called from within the DB package, it is executed in the caller's scope. This means that lexical values are made visible and the file behaves as a code block. Here is an example to get an include() function that actually works the way most people expect: use strict;package Acme::Include;use base 'Exporter';use File::Slurp ();our @EXPORT = 'include';{ package DB; # The sub's name is fully qualified to avoid getting a B::Include sub Acme::Include::include ($) { my ($filename) = @_; my $code = qq[#line 1 "$filename"\n] . File::Slurp::read_file($filename); eval $code; }}1; Documentation for the #line directive is in [perlsyn]. To test this new module, save it as Acme/Include.pm and create: # This is foo.pluse strict;use Acme::Include;my $lexical = 'set in foo.pl';include 'bar.pl';print $lexical; # Should print: set in bar.pl and:# This is bar.pluse strict;$lexical = 'set in bar.pl';# There is no "my" here, because that would create a *new* lexical# variable, hiding the existing one. and then run perl foo.pl. This example Acme::Include does not have any error checking. In practice, you will want to check $@ somewhere (but you also want to retain the value returned by the included file, and context to propagate properly. Good luck!). Learning more I wrote this tutorial to have an answer ready for the nth time someone in EFnet's #perlhelp asks why [require] works only once, or asks how to really include a file. Explaining the same thing over and over gets annoying over time. This is not a good guide to writing modules. For that, read chapter 10 of [http://learn.perl.org/library/beginning_perl/|Beginning Perl] and [perlmod] and [perlnewmod]. Of course, good code always comes with good documentation; so learn [id://252477]. One last thing If you name your module Test, don't be surprised if it doesn't work. The current working directory comes last in @INC, so the [perldoc://Test] module that is in the Perl distribution is probably loaded instead. This bites me at least once per year, this time while writing this tutorial :). Accessing Microsoft SQL Server from Linux using DBD::Sybase (CleverFox) Accessing Microsoft SQL Server from Perl by Lindsay Leeds (2004 Sep 20) Recently, I made yet another attempt to get Perl to access Microsoft SQL Server using DBD. Usually, when I want to connect to a Microsoft SQL Server, it is from Perl on Windows. So I take the easy route and use DBD::ODBC and use an ODBC connection. This time though, I wanted to connect to Microsoft SQL Server 2000 from a Linux box. Having no ODBC to fall back on, I looked for native DBD driver of some sort. It took me several hours of struggling to make it work. I almost gave up several times, so I am writing outline to help anyone else trying to accomplish this same task. In the end, we will use the DBD::Sybase perl module from CPAN to access the Microsoft SQL Server. Before we can do that however, we must first compile the freetds library. Note: From now on I will refer to Microsoft SQL Server as SQL Server. Please do not confuse this with a generic sql server. We can all now pause to gripe about the lack of imagination in product naming at Microsoft. Compiling Freetds Download and compile freetds fromhttp://www.freetds.org/. once you unzip and untar it, enter the directory and run: ./configure --prefix=/usr/local/freetds --with-tdsver=7.0 make make install Configuring Freetds Now we have the freetds compiled, but we still have configure it. This is the part that threw me off and is so different from other DBD drivers. The DBD::Sybase driver will ultimately be affected by the contents of the /usr/local/freetds/etc/freetds.conf file. If that file is not configured correctly, your DBD::Sybase connection will fail. Okay, now that we have established there is a relationship between the freetds.conf file and the DBD::Sybase module, let's edit the freetds.conf file. The strategic modifications I made to the freetds.conf file were: 1) uncomment the following lines and modify if necessary: try server login = yes try domain login = no Note: this forces the module to attempt a database login instead of a domain login. I could not get domain login to work, though I will admit I did not try very hard. 2) uncomment the following line and modify if necessary: tds version = 7.0 This supposedly sets the default tds version to establish a connection with. I have only SQL Server 2000 servers, and they won't talk at any lower version. So I set it to 7.0. If for some reason you had older SQL Servers, you might leave it at the default 4.2. 3) create a server entry for my server sql1: [sql1]host = sql1port = 1433tds version = 8.0 Note: My server here is sql1. Ping sql1 worked, so I am sure I can resolve it using DNS. You can also specifcy an ip address instead of the host name. The sql1 in the brackets is just a descriptor. It could be 'superduperserver' and it would still work as long as my 'host =' is set correctly. I tried 'tds version 7.0' for my SQL Sever 2000 and it worked. Version 5.0 though resulted in an error. You might want to verify your SQL Server is listening on port 1433 with a 'netstat -a -n' run from the command line on the SQL Server. At this point you can verify your configuration. /usr/local/freetds/bin/tsql -S sql1 -U sqluser You will then be prompted for a password and if everything is well, you will see a '1)' waiting for you to enter a command. If you can't get the 1) using tsql, I doubt your DBD::Sybase perl code is going to work. Please note that sqluser is not an Active Directory/Windows Domain user, but an SQL Server user. Compiling DBD::Sybase Now that we have the freetds library prerequisite for DBD::Sybase installed and configured, we can compile the DBD::Sybase perl module. Obtain it from www.cpan.org if you haven't already. once you have untarred it and are in the directory, run: export SYBASE=/usr/local/freetds perl Makefile.PL make make install Note: The export line is to let the compilation process know where to find the freetds libraries. Using DBD::Sybase You are now ready to test your DBD::Sybase module. #!/usr/bin/perl use DBI; $dsn = 'DBI:Sybase:server=sql1'; my $dbh = DBI->connect($dsn, "sqluser", 'password'); die "unable to connect to server $DBI::errstr" unless $dbh; $dbh->do("use mydatabase"); $query = "SELECT * FROM MYTABLE"; $sth = $dbh->prepare ($query) or die "prepare failed\n"; $sth->execute( ) or die "unable to execute query $query error $DBI::errstr"; $rows = $sth->rows ; print "$row rows returned by query\n"; while ( @first = $sth->fetchrow_array ) { foreach $field (@first) { print "field: $field\n"; } } Good luck! Calling .NET Assemblies with Win32::OLE (InfiniteSilence) This is a tutorial for calling a .NET assembly via Win32::OLE. I was looking for such a tutorial on the web and previously at PerlMonks but didn't find anything, so I elected to research the issue, get a quick example working, and submit it.Basically what you want to be able to do is: perl -e "use Win32::OLE; $hl = new Win32::OLE('HelloDot.HelloWorld') or die $!; $hl->SayHello();" Where HelloDot.HelloWorld is a .NET assembly registered in the system to look/act/smell like a regular COM component. The following are preliminary setup steps that do not require explanation: Step 1: You will have to install both the .NET Framework and the .NET SDK on your machine (type .net framework/sdk download in Google) Step 2: The installer does not set your path, so you will have to add the following to be able to reach gacutil.exe, regasm.exe, csc.exe (my cheezy example was written in C#), etc.: C:\Program Files\Microsoft.NET\SDK\v1.1\Bin\;C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\After mucking with your PATH, you should create a key file like this: sn -k personality.snk This creates a 'key pair' file which contains a public and a private key for entering the .dll we are about to create into the GAC, the Global Assembly Cache. Think of it as a Windows registry for .NET assemblies. There is a way to separate the public key part from the private one (using sn -p) in case you are interested. (Note: I'm not sure why this thing didn't offer to allow me a choice of ciphers or allow me to choose my own entropy engine. I remember reading that it is using SHA1 or something, but I don't know.)The first think you will notice when you run an example with the .NET framework is that it is terribly slow. A simple 'Hello World' takes about three seconds to run every time. It seems obvious to me that this thing was not written for quick one-liner-like execution, so be warned. Copy the following hello.cs file and compile it: using System;using System.Reflection;[assembly:AssemblyVersion("1.0.0.0")][assembly:AssemblyKeyFile("personality.snk")]namespace HelloDot { public class HelloWorld { public HelloWorld(){ //no param constructor for COM } public void SayHello(){ Console.WriteLine("Hello from DOT NET"); } }} You need a constructor with no params for the .NET assembly to be called like a regular COM component (as with Win32::OLE). There is some kind of wrapper that M$soft creates to allow COM components to interact with .NET assemblies and the constructor is necessary to make that happen. If you are interested on the why, more information on that is here. The only problem with this is that a third party .dll is probably not going to have this constructor, so at that point you will have to create a wrapper class that does have it before you try this.Anyway, you need to compile this into a .dll like so: csc /t:library /out:hellodot.dll hello.cs If you go back to to the hello.cs code, you will notice the funny lines before the namespace that stand out like a sore thumb: assembly:AssemblyVersion...yadda,yadda. These instructions tell the compiler that you are creating an assembly you are intending to share. If you remove the lines and recompile you will notice that the .dll becomes a little smaller. Remember to put it back in and recompile before you continue this tutorial.If the .dll compiled okay you now have to register it: gacutil /i hellodot.dll There is one more thing to do. Your .NET assembly still needs to look and act like a regular COM component. Normal COM components (i.e. Excel.Application, Microsoft.XML, etc.) are registered with regsvr32. This puts their GUIDs in the Window's Registry (see HKEY_LOCAL_MACHINE/Software/Classes for the ones you've got). Not so in this case. You need to use regasm.exe in order to 'register' your .NET .dll to be usable by everybody outside of the .NET camp:regasm hellodot.dll With all of this being done, you should be able to call the following:perl -e "use Win32::OLE; $hl = new Win32::OLE('HelloDot.HelloWorld') or die $!; $hl->SayHello();" You may read from various online sources that it is unncessary to load the assembly into the GAC for you to call it as a COM component, but this does not (at least for me) seem to work. Without registering in the GAC I had to copy the .dll to the Windows/System32 directory just to get it to work for the Window's Scripting Host. Win32::OLE simply could not find the bugger until I registered it in the GAC. Summary: Are you are asking yourself, "why is any of this important?" Well, it seems that the only other way to get Perl on Windows to interact with .NET is to pony up cash for Visual Studio.NET and Visual Perl. The above tutorial offers a (relatively) quick and (depending on your threshold) painless way to interoperate with .NET components. Troubleshooting Perl CGI scripts (brian_d_foy) This resource is intended as a general framework for working throughproblems with CGI scripts. It is not a complete guide to everyproblem that you may encounter, nor a tutorial on bug squashing. Itis just the culmination of my experience debugging CGI scripts for tenyears. This page seems to have had many different homes, and I seemto forget it exists, so I'm adding it to the Monastery's canon. Youcan send any comments or suggestions to me at comdog@panix.com. You may alsowant to see the CGIMeta FAQ for a list of references. Are you using Perl's built in features to help you find problems? If you have not turned on warnings with the -w switch and are not usingstrict, you should be. These things help you find problems. You may needa bit of time to get used to them, but they save you many hours of time.You need them to go through this troubleshooting procedure. Did you output a valid CGI header first? The server is expecting the first output from a CGIscript to be the CGI header. Typically that might be assimple as print "Content-type: text/plain\n\n";or with CGI.pm and its derivatives, printheader() . Some servers are sensitive to error output(on STDERR) showing up before standard output (on STDOUT). What did the error log say? Servers keep error logs (or they should, at least). Error output from the server and from your script shouldshow up there. Find the error log and see what it says.There isn't a standard place for log files. Look in the server configuration for their location, or ask the serveradmin. You can also use tools such as CGI::Carpto keep your own log files. What are the scripts permissions? If you see errors like "Permission denied" or "Method notimplemented", it probably means that your script is notreadable and executable by the web server user. On flavorsof Unix, changing the mode to 755 is recommended:chmod 755 filename. Never set a mode to 777! Are you using use strict? Remember that Perl automatically creates variables whenyou first use them. This is a feature, but sometimes cancause bugs if you mistype a variable name. The pragmause strict will help you find those sorts oferrors. It's annoying until you get used to it, but yourprogramming will improve significantly after awhile andyou will be free to make different mistakes. Does the script compile? You can check for compilation errors by using the -cswitch. Concentrate on the first errors reported. Rinse,repeat. If you are getting really strange errors, check toensure that your script has the right line endings. If youFTP in binary mode, checkout from CVS, or something else thatdoes not handle line end translation, the web server may seeyour script as one big line. Transfer Perl scripts in ASCIImode. Does the script give you warnings? You can check for warnings by using the -w switch whichI recommend you use during all development. Warnings arefully explained in the perldiag man page, or by using thepragma use diagnostics;. If you make yourscript "-w clean" you will have less trouble withit in the future. Is the script complaining about insecure dependencies? If your script complains about insecure dependencies, you are probably using the -T switch to turn on taint mode, which isa good thing since it keeps you have passing unchecked data to the shell. Ifit is complaining it is doing its job to help us write more secure scripts. Anydata originating from outside of the program (i.e. the environment)is considered tainted. Environment variables such as PATH and LD_LIBRARY_PATHare particularly troublesome. You have to set these to a safe valueor unset them completely, as I recommend. You should be using absolutepaths anyway. If taint checking complains about something else,make sure that you have untainted the data. See the perlsecman page for details. What happens when you run it from the command line? Does the script output what you expect when run from thecommand line? Is the header output first, followed by ablank line? Remember that STDERR may be merged with STDOUTif you are on a terminal (e.g. an interactive session), anddue to buffering may show up in a jumbled order. Turn onPerl's autoflush feature by setting $| to atrue value. Typically you might see $|++; inCGI programs. Once set, every print and write willimmediately go to the output rather than being buffered.You have to set this for each filehandle. Use select tochange the default filehandle, like so:$|++; #sets $| for STDOUT$old_handle = select( STDERR ); #change to STDERR$|++; #sets $| for STDERRselect( $old_handle ); #change back to STDOUT Either way, the first thing output should be the CGI headerfollowed by a blank line. What happens when you run it from the command line with a CGI-like environment? The web server environment is usually a lot more limitedthan your command line environment, and has extrainformation about the request. If your script runs finefrom the command line, you might try simulating a web serverenvironment. If the problem appears, you have anenvironment problem.Unset or remove these variables PATH LD_LIBRARY_PATH all ORACLE_* variables Set these variables REQUEST_METHOD (set to GET, HEAD, or POST as appropriate) SERVER_PORT (set to 80, usually) REMOTE_USER (if you are doing protected access stuff) Recent versions of CGI.pm ( > 2.75 ) require the -debug flag to get the old (useful) behavior, so you might have to add it toyour CGI.pm imports.use CGI qw(-debug) Are you using die() or warn()? Those functions print to STDERR unless you have redefined them. They don't output a CGI header, either. You can getthe same functionality with packages such as CGI::Carp. What happens after you clear the browser cache? If you think your script is doing the right thing, andwhen you perform the request manually you get the rightoutput, the browser might be the culprit. Clear the cacheand set the cache size to zero while testing. Remember thatsome browsers are really stupid and won't actually reloadnew content even though you tell it to do so. This isespecially prevalent in cases where the URL path is thesame, but the content changes (e.g. dynamic images). Is the script where you think it is? The file system path to a script is not necessarilydirectly related to the URL path to the script. Make sureyou have the right directory, even if you have to write ashort test script to test this. Furthermore, are you surethat you are modifying the correct file? If you don't seeany effect with your changes, you might be modifying adifferent file, or uploading a file to the wrong place. (This is, by the way, my most frequent cause of such trouble;) Are you using CGI.pm, or a derivative of it? If your problem is related to parsing the CGI input and youaren't using a widely tested module like CGI.pm, CGI::Request, orCGI::Lite, use the module and get on with life. CGI.pm has a cgi-lib.pl compatibility mode which can help you solve inputproblems due to older CGI parser implementations. Did you use absolute paths? If you are running external commands withsystem(), back ticks, or other IPC facilities,you should use an absolute path to the external program. Not only do you know exactly what you are running, but youavoid some security problems as well. If you are openingfiles for either reading or writing, use an absolute path. The CGI script may have a different idea about the currentdirectory than you do. Alternatively, you can do anexplicit chdir() to put you in the right place. Did you check your return values? Most Perl functions will tell you if they worked or notand will set $! on failure. Did you check thereturn value and examine $! for error messages? Did you check$@ if you were using eval? Which version of Perl are you using? The latest stable version of Perl is 5.8.3. Are you using an olderversion? Different versions of Perl may have different ideas of warnings. Which web server are you using? Different servers may act differently in the samesituation. The same server product may act differently withdifferent configurations. Include as much of thisinformation as you can in any request for help. Did you check the server documentation? Serious CGI programmers should know as much about theserver as possible - including not only the server featuresand behavior, but also the local configuration. Thedocumentation for your server might not be available to youif you are using a commercial product. Otherwise, thedocumentation should be on your server. If it isn't, lookfor it on the web. Consult the CGIMeta FAQ for a list of references. Did you search the archives of comp.infosystems.www.authoring.cgi? It's likely that someone has had your problem before,and that someone (possibly me) has answered it in thisnewsgroup. Archives are available from Google Can you reproduce the problem with a short test script? In large systems, it may be difficult to track down a bugsince so many things are happening. Try to reproduce the problembehavior with the shortest possible script. Knowing the problemis most of the fix. This may be certainly time-consuming, but youhaven't found the problem yet and you're running out of options. :) Did you decide to go see a movie? Seriously. Sometimes we can get so wrapped up in the problem that wedevelop "perceptual narrowing" (tunnel vision). Taking a break,getting a cup of coffee, or blasting some bad guys in Quake might give youthe fresh perspective that you need to re-approach the problem. Have you vocalized the problem? Seriously again. Sometimes explaining the problem aloudleads us to our own answers. Talk to the penguin (plush toy) becauseyour co-workers aren't listening. If you are interested in thisas a serious debugging tool (and I do recommend it if you haven't found the problem by now), you might also like to read The Psychologyof Computer Programming. Did you post an informative and well-developed question to comp.infosystems.www.authoring.cgi? Once you have gone through all of these steps, youshould have all of the information to ask a question thatcan elicit a good answer. Post in as much detail aspossible, and include the smallest bit of code thatreproduces the problem. -- brian d foy Edited by davido: Fixed HTML and formatting to eliminate horizontal scrolling in IE. Installing Perl on a Windows PC (giricredwolf) First, go to ActiveState's ActivePerl Site, http://www.activeperl.com. From here you can either click on the "Perl" link in the top banner, or hover your mouse pointer over "Languages" in the red bar and then click on "ActivePerl Family" in the dropbox that appears. On the next page, click on "ActivePerl" under "ActivePerl Family". (You're getting close. Don't give up yet!) At the bottom of the page, click "DOWNLOAD", then either fill in the blanks on the next page or not and click "Next". (ActiveState doesn't require contact info.)This page gives you several options. The first thing you should do is check out the "minimum requirements" link in the middle column. (The three columns being the download list, an info column, and then the "Register... Download" column. If you're running Windows XP, you're set and don't really need to worry about this. The left column should say "ActivePerl" and then a version number. Choose the most recent version and download the MSI package under the Windows heading. BEFORE CONTINUING: Make sure you have Administrator privileges on your computer. If you don't, you'll have more work to do after installing. Simply run the MSI (an executable) and follow the installation guidelines. If, for one reason or another, you cannot install from the MSI, go back to ActivePerl's web space and download the AS package (a .zip file). The ActivePerl site explicitly states, "The Windows AS Package provides NO uninstall functionality, and is recommended only if you are unable to install ActivePerl using the MSI installer." (What this basically means is that you'll have to manually uninstall it if you ever want to get rid of it.) You can now write Perl programs in any text editor (like Notepad, but turn wordwrap off) and run them through the Command Prompt using the "perl" command, just like all the other OSes. (Command Prompt is in Start > All Programs > Accessories OR Start > Programs > Accessories for non-XP systems.) This should work for any version of Windows. Please be sure to check the system requirements listed on ActiveState's download page to be sure your machine/OS can handle it. Good luck! ADDENDUM ActivePerl is not the only Perl for Windows out there, it is simply the first that I came accross. As noted by Joost, there is also CygWin at http://www.cygwin.com (directions listed in his reply below). CygWin is basically, for all intents and puposes, a Linix shell emulator for PC. See their site for more details. I also want to mention a very helpful tool for me when writing is the VI Improved (VIM) text editor, available at http://www.vim.org/. It's free and has many features to help you with coding, including (but not limited to) auto-indenting, color highlighting, and multiple computer language support. VIM is what I learned on in school, used when I had Linux, and is a great tool even on a Windows based machine. Last update 2004.07.31.0150 The Scalar Range Operator (pbeckingham) The Scalar Range Operator I have been playing with the scalar range operator, and it confused me so much that I started experimenting and reading about it,and here is what I wrote up. Numeric Values This operator, in scalar context, has two forms that act as a bistable or flip-flop. The first form looks like this: if ($left .. $right) { ... } This if statement works as follows:The condition evaluates false until $left evaluates true.Then the $left condition is ignored, and the condition continuesto evaluate true until $right evaluates true, at which pointthe condition evaluates false, and it goes back to check $left.In this way, it flip-flops between waiting for the left side to evaluate true,and then waiting for the right side to evaluate true. Very strange, untilyou see it operating in a program: while () { print if 2 .. 4; } __DATA__ first second third fourth fifth __OUTPUT__ second third fourth This program prints out the second and third line of the data.A numeric value in the scalar range operator is therefore compared to$.. Regular Expressions This example shows the use of two regular expressions in the scalarrange operator: while () { print if /start/ .. /end/; } __DATA__ ignore start first second third end ignore start fourth fifth end ignore __OUTPUT__ start first second third end start fourth fifth end It prints out lines in the data beginning with the line that first evaluatestrue (start), until the line that next evaluates true(end). All the lines that are not bracked by start/endpairs are ignored. Note that this data contains two blocks of lines that are between start and end markers, and the lines outside those ranges are ignored. Numeric and Regular Expressions Combining a numeric and a regex in the range operator also works as expected.In this example, the lines from $. == 1 until $_ =~ /end/are printed. while () { print if 2 .. /end/; } __DATA__ first second third end ignore __OUTPUT__ second third end Exluding Markers In order to exclude lines that contain start and end,a further condition is required. The condition is that the result returned bythe scalar range operator must be neither 1 (representing$. of 1), nor must it contain E. When the operatorencounters the line that evaluates true for the right-hand-side, it's returnvalue is (in the example below) 5E0. This number evaluates to5, but contains that E, which is the indicator thatthis line terminates the right-hand-side of the operator.This code prints all the lines between the start andend lines: while () { if (my $num = /start/ .. /end/) { print unless $num == 1 || $num =~ /E/; } } __DATA__ ignore start first second third end ignore start fourth fifth end ignore __OUTPUT__ first second third fourth fifth To better illustrate that, this program prints out that value, for alllines between start and end: while () { if (my $num = /start/ .. /end/) { print $num, "\t", $_; } } __DATA__ ignore start first second third end ignore start fourth fifth end ignore __OUTPUT__ 1 start 2 first 3 second 4 third 5E0 end 1 start 2 fourth 3 fifth 4E0 end Markers on Same Line This example places both the start and end tokenson the same line. From the output, it can be seen that the combined linehas a value of 1E0 which satisfies the test as both the firstand last line of the desired input. while () { if (my $num = /start/ .. /end/) { print $num, "\t", $_; } } __DATA__ ignore start first second end ignore start third end ignore __OUTPUT__ 1 start 2 first 3 second 4E0 end 1E0 start third end The Scalar ... Operator The other form of the scalar range operator is .... This operatorperforms as the .. operator does, but lines that meet one criteriaare not also evaluated for the other.So a line that contains both start and end is onlyevaluated once - in this case for the start line, causing thisdata to be considered as having a start but not an end, meaning that the data is not properly treated in this example. while () { if (my $num = /start/ ... /end/) { print "$num\t$_"; } } __DATA__ ignore start first end ignore __OUTPUT__ 1 start first end 2 ignore This form of the scalar range operator is more efficient only if it is known that bothconditions can never be true on the same line. Update: Changed examples to not include so many edge cases. Thanks to [hossman]. Perl Idioms Explained - !!expr (broquaint) Perl Idioms Explained - !!exprsub is_in_list { return !!grep { $_ eq $_[0] } @_[ 1 .. $#_ ];}print "baz is in list" if is_in_list 'baz', qw/ foo bar baz /;__output__baz is in list Even though perl doesn't have a native boolean type, sometimes all aprogrammer wants is a nice simple boolean value, and this is what the!!expr idiom provides. Given an expression, its resultingvalue is negated by the boolean not operator ! and thenthat value is negated to get the resulting boolean value. Let'sbreak that down a little use Data::Dumper; my $val = 'a string which evaluates to true'; print Dumper !$val; print Dumper !!$val; __output__ $VAR1 = ''; $VAR1 = '1'; So as we can see there the initial negation returns a false value(an empty string '') to signify the negated truthfulnessof the value. Then secondary double negation returns a true value(the integer 1) as the negated form of the false value.Caveats Because it is producing a boolean value from an expression it will not preserve any additional information from the expression. But that'sabout the only caveat, if you could consider it one, and it has the added plus of acting as a boolean internally as explored in[diotalevi]'s [id://367520]. Summary Because we are lacking a ¡ operator the !!expridiom serves to derive a boolean value from an arbitrary expression. Getting Matching Items From An Array (Limbic~Region) Purpose On a regular basis, people want to know if a particular thing, we will call it foo, is present in an array. The problem with just directing them to FAQ x is that each question usually varies enough to make a single answer unsatisfactory. The goal of this tutorial is to give enough information so that someone can choose the right solution to the problem. Is This Tutorial For You? A typical mistake is to assume that there is a built-in way of determining presence in an array like there is with a hash. A red flag should go up if you try using a string for an index as in print "gotcha\n" if $array['foo']. Perhaps you should be using a hash. An array gives no "meaning" between the index and the value (though the programmer might as in the case of matrices). If you are still unsure which to be using, see perldoc perldsc and perldoc perldata for more information. What Will Be Covered There are typically 4 answers to the problem of identifying if foo is present in an array. Convert the array to a hash Use the built-in grep Use List::Util's first IYAW (Invent Yet Another Wheel) There are a handful of things to consider and each solution has pros and cons accordingly. You will need to decide for yourself which is best. Convert The Array To A Hash Depending on your requirements, this can be a very attractive solution (print "It's in there\n" if exists $sauce{spaghetti}). There is a list of things to consider: How many items do you need to check? If you are only checking a single item, this is probably not the best solution.Will the array change between checks? If you need to rebuild the hash each time you check because you are not sure if the array has changed, this is probably not the best solution.Do you need something other than an exact match? Using a hash is a bad idea for non exact matches. The one noteable exception is perhaps case insensitivity. You can force the keys to a certain case during creation and foo to the same case when searching. Even then, it is questionable with regards to this being the best solution.How big is the array? Duplicating data structures for the convenience of searching can get quite expensive with regards to memory consumption. You will need to determine how large a footprint is acceptable to you.Do you need to know if there is more than one match? Remember that hash keys must be unique so using a hash when there is a possibility of duplicates is a bad idea if you need to know how many times foo is present in the array.Do you need to know foo's index? Typically for memory reasons, you would build your hash like:my %lookup = map { $_ => undef } @array;print "There it is\n" if exists $lookup{foo}; But if you have given some meaning to the relationship to the index and the value (or perhaps you want to use splice to remove it), then you should consider using the following instead:my %lookup = map { $array[$_] => $_ } 0 .. $#array;my $index = $lookup{foo}; Use The Built-In grep It is fast and powerful and deserves careful consideration: How many items do you need to check? If you are checking many items, this is probably not the best solution because it goes through the entire list even if the match is found the first time. Keep in mind that many is subjective and since it has been optimized for efficiency, it still may be acceptable.Will the array change between checks? You might want to use grep if the answer is yes or you are unsure since it is not checking against a copy that might be stale.Do you need something other than an exact match? You might want to use grep if the answer is yes or you are unsure. Since grep can accept a block, you can easily do a case insensitive search (grep { $_ =~ /^foo$/i } @array)How big is the array? If the array is very large, you may want to consider something other than grep. Of course very large is subjective. If you are not going to be checking numerous items and you can afford to wait a few extra seconds, grep might be the perfect choice.Do you need to know if there is more than one match? Since grep goes through the entire list, it is an ideal candidate if the answer to this question is yes. In list context, grep will return the list of matching items. In scalar context - it will return the number of matching items.Do you need to know foo's index? Since grep can take a block, it is very versatile and can easily be adapted to this situation:my @indices = grep { $array[$_] eq 'foo' } 0 .. $#array; Use [cpan://List::Util]'s first It works very much like grep except it returns on the first match, which depending on your situation can make it a perfect solution. How many items do you need to check? At first glance, you might say it does not matter. One issue is that the first function is not a compiled built-in like grep. A code block is dereferenced and executed for each element in the list until a match is found. A second issue is that first does not currently accept a reference as an argument so a list of aliases has to be generated. Be sure not to worry about premature optimization when the net difference in runtime is a few seconds unless it really matters.Will the array change between checks? Like grep, if the answer is yes or you are unsure, you should be considering first since it is not checking against a copy that might be stale.Do you need something other than an exact match? Like grep, if the answer is yes or you are unsure then first is a possibility since it takes a block.How big is the array? Again, you might say it doesn't matter at first glance since it returns on first match. The first function was built to be flexible accepting a code block that has to be dereferenced against each item in the list until a match is found. If you really need lightening speed then you might want to consider a roll-your-own version that is hard-coded.Do you need to know if there is more than one match? If the answer is yes, do not choose first since it is designed to return on first match.Do you need to know foo's index? The first function can be adapted to handle this situation just like grep. IYAW (Invent Yet Another Wheel) There is rarely a good reason to do this. Sanity checks such as profiling and benchmarking should be done before you spending valuable time trying to squeeze a couple of seconds off the runtime. I can only think of a couple of reasons you might want to do this: You can't afford the performance hit of alias construction and repeatedly dereferencing the code block passed to first You need to do some transformation before checking but need to keep the original array intact I freely admit that this falls out of the scope of checking the presence of an item in an array. By copying the array and then transforming it you have changed the problem. This does not stop people from asking and so I have included it here for an attempt at completeness. Update: I modified the code snippet in the "Is This Tutorial For You" section to remove exists per [rob_au]'s suggestion. It was not necessary to illustrate the point. Update 2: 2004-10-02 - [wolv] pointed out to me that the inefficiencies in [cpan://List::Util]'s first are in the pure perl version. The XS version is obviously much faster. How will my regular expression match? (hv) A common source of confusion is the issue of which possible match the regular expression will find in any given instance, and this gives rise to many queries on [Seekers of Perl Wisdom|SOPW] and many different attempts to explain what happens. A common theme in the explanations is to talk about preferences - the regular expression engine "prefers" longer or shorter matches, or leftmost matches. The reality is however very simple: the regular expression engine will always return the first match it finds, and if you understand the order in which the engine attempts matches, you need never be confused about which match will be found. A few simple rules (in no particular order) characterise the order in which attempts are made. 1: leftmost character first The engine will start trying to match the pattern against the string, starting with the first character of the string. Only if it cannot find any match against the beginning of the string will it start looking for matches starting with the second character of the string, and so on until the string is exhausted. Example: ($match) = "The longest word" =~ /(\w+)/; print $match; .. will print "The", since it matches at the beginning of the string. The fact that there is a longer match to find is irrelevant - a match against the beginning of the string succeeded, so this is the match that is returned. 2: leftmost alternation first Given a choice of alternates, the leftmost alternate is tried first. If a match is found against the leftmost alternate, the engine will attempt to match the rest of the pattern against the rest of the string; only if no match can be found will the next alternate be tried. Example: ($match) = "Mrs Smith" =~ /(Mr|Mrs)/; print $match; .. will print "Mr": the first alternate matched, and thus satisfied the entire pattern, so this is the match returned. The second alternate was never looked at. 3. Maximal (greedy) With any normal quantifier (ie any of ? * + {1,3}), the engine will first try to match the greatest number of iterations permitted (or the most available if that is fewer than permitted), and try to match the rest of the pattern against the rest of the string. Only if the rest of the pattern fails to match will it try matching one fewer iteration, and repeat until the minimum permitted number is reached. Example: ($match) = "/foo/bar" =~ m[.*/(.*)]; print $match; .. prints "bar": the engine tries to match the initial .* against "/foo/bar", then "/foo/ba", then "/foo/b", then "/foo/", then "/foo". At this point the remaining pattern matches, so this is the match returned. 4. Minimal (non-greedy) Adding a '?' after a quantifier (ie ?? *? +? {1,3}?) requests a minimal match, so the order is reversed: the engine first attempts to match the fewest number of iterations permitted and if it can, attempts to match the rest of the pattern against the rest of the string. Only if that fails does it try matching one more iteration, and continues increasing the number of iterations matched until the upper limit is reached. Example: ($match) = "foo/bar/baz" =~ m[.*?/(.*)]; print $match; .. prints "bar/baz": the engine tries to match the initial .* against "", then "f", then "fo", then "foo". At this point the rest of the pattern matches, so this is the match that is returned. 5. Pattern components: left to right Implicit in some of the above examples is that the components of the pattern are matched from left to right. So in the 'maximal' example above, the engine decides first (based on the rules above) how it is going to try to match the initial .*, and only after that is fixed does it start worrying about the remaining components of the pattern. 6. Nesting This is really just more of the "left to right" rule, best explained by example: ($outer, $inner) = "/foo/bar" =~ m[(/(.+))*]; print $inner; .. prints "foo/bar". The engine reaches the outer quantifier, knows it should match it as many times as possible, and attempts to match its innards. The first iteration of the innards reaches the nested quantifier, and tries to match it as many times as possible, giving "foo/bar". At this point, the outer quantifier cannot be matched a second time but that's fine - the pattern has been fully satisfied, and so this match is returned. That covers most of the standard cases. There are a few other possibilities to consider (eg anchors, pos(), and the various zero-width assertions). Also, the optimiser may sometimes cause the engine to skip some steps, but only if it is sure that the actual match found will be the same. I hope this will help you work out which match your regular expression will find. Hugo Using select and IO::Select (duff) Here's a tutorial I started on using [doc://select] (primarily because I saw a [id://370963|query] from [tachyon] on it and I figured it was a good thing to do). This is just a first cut, so be kind and send me your comments. :-)Also, is there a way for perlmonks.org to automagically handle POD format? =head1 NAMEperlselecttut - a tutorial on using select() and IO::Select=head1 DESCRIPTIONThis document attempts to explain how to use the 4-arg version ofC and the module C so that they are easier tounderstand. If anything is unclear, the authorof this document would appreciate hearing about it.=head2 What are C/C and why would you use them?Without going into too much detail (none at all in fact) C andC are useful for when you want to "watch" severalfilehandles at once to see if they are ready for reading or writing orif any of them have an exception condition. Now, when I say"filehandles" I really mean anything that can be read or written to asif it were a file: sockets, serial devices, pipes, fifos, etc. Anexample application that would use C to see what each clientsays having to wait on any particular client.Caveat lector! This document is mostly written from a unix-centricpoint of view, but similar ideas apply on other operating systems.=head2 All about CHere's the canonical C example that you will find in thedocumentation:($nfound,$timeleft) = select($rout=$rin, $wout=$win, $eout=$ein, $timeout);But what does it all mean? Why the assignments? Why those particularvariable names? The first 3 arguments to C tell it which filehandles to watchfor reading, writing, and exceptions respectively (thus the leading r,w, and e on each variable). These arguments are each a specialbitvector where each "on" bit corresponds to the filedescriptor numberof the filehandle that is being watched. The fourth argument toC is how long to watch the filehandles before giving up. TheC call returns a count of how many filehandles have triggeredone of the reading/writing/exception conditions (C<$nfound>) and theamount of time left in the timeout specified (C<$timeleft>).=head3 What are filedescriptors?Each time you open a file, the operating system makes an entry insomething called a file descriptor table so that it can keep track ofthe file (things like the current position, whether or not it'sbuffered, the contents of the buffer, etc.) By default the entry atindex 0 is STDIN, at index 1 is STDOUT and STDERR is at index 2. Theindex into the filedescriptor table is called the file descriptor numberor L for short. It's these indexes that are used as offsets intothe bitvector to identify to C which filehandles you wish towatch.=head3 Using C to build bitvectorsA bitvector is an odd thing for perl because it's so low level. Havingto fiddle with bitvectors shows how close C is to its C heritage.But luckily perl remembers its heritage through a function calledC. To create a bitvector for use with C with theproper bit turned on for STDIN you would write:vec($vector,fileno(STDIN),1) = 1;C is a routine that returns the index into thefiledescriptor table for a given filehandle (aka. the fileno). Sincewe know STDIN is at index 0, we could have writtenvec($vector,0,1) = 1;But that would be I unportable. If, for some reason, wehappened to run on a system that used 0 for some other filehandle outprogram wouldn't work as expected. This I happen if we closedSTDIN, then opened another file. The operating system may use the firstavailable free filedescriptor when you open a new file and since weclosed STDIN, descriptor 0 would be free.Anyway, the call to C means: treat $vector is a bitvector andaccess the bits starting at the bit position corresponding to the theindex into the filedescriptor table for the filehandle STDIN for 1 bitand assign that bit the value 1. So, to watch several filehandles youwould do this:vec($vector,fileno(FOO),1) = 1;vec($vector,fileno(BAR),1) = 1;vec($vector,fileno(BAZ),1) = 1;and then use C<$vector> in the call to C to watch the FOO,BAR, and BAX filehandles.See C for more information on C=head3 Why are we doing assignments in the C call?The reason you typically see assignments in the first three positions isthat C modifies its first 3 arguments to tell you Ifilehandles have data ready for reading or writing or exceptions and youusually want to continually watch the same filehandles over and overagain. Since the followingselect($rout=$rin, $wout=$win, $eout=$ein, $timeout);functions the same as $rout = $rin; $wout = $win; $eout = $ein;select($rout, $wout, $eout, $timeout);The assignments allow $rin,$win, and $ein to keep their original valuesso that you can call it in a loop without having to continually buildthe bit vectors. Contrast these two functionally equivalent snippets:# Example 1, the usual idiomvec($rin,fileno(FOO),1) = 1;vec($rin,fileno(BAR),1) = 1;vec($rin,fileno(BAZ),1) = 1;while (1) { ($found) = select($rout=$rin,undef,undef,$timeout); next unless $found; # Check $rout to see which handles are ready for reading}# Example 2, building the vectors each timewhile (1) { vec($rinout,fileno(FOO),1) = 1; vec($rinout,fileno(BAR),1) = 1; vec($rinout,fileno(BAZ),1) = 1; ($found) = select($rinout,undef,undef,$timeout); next unless $found; # Check $rinout to see which handles are ready for reading}Oh, btw, you'll notice that I used C for the second and thirdargument to C. If you don't care to check any filehandlesfor reading, writing, or exceptions you can pass C in therespective position and C won't bother paying attention tothat condition. You can also pass c for the timeout andC will wait forever for a filehandle to trigger theappropriate condition. =head3 Checking which filehandles are readyAfter C returns, the three bitvectors will have changed toreflect the actual filehandles that triggered the particular conditionyou were waiting for. One way to check which filehandle is ready isto just use C again to see if the particular bit is 1. Forexample:vec($rin,fileno(FH1),1) = 1;vec($rin,fileno(FH2),1) = 1;vec($rin,fileno(FH3),1) = 1;while (1) { ($found) = select($rout=$rin,undef,undef,$timeout); next unless $found; if (vec($rout,fileno(FH1),1) == 1) { # There is data waiting to be read on FH1 } if (vec($rout,fileno(FH2),1) == 1) { # There is data waiting to be read on FH2 } # and so on ...}Another method would be to use C again. vec($fh1,fileno(FH1),1) = 1;vec($fh2,fileno(FH2),1) = 1;vec($fh3,fileno(FH3),1) = 1;$rin = $fh1 | $fh2 | $fh3;while (1) { ($found) = select($rout=$rin,undef,undef,$timeout); next unless $found; if (select($fh1,undef,undef,$timeout)) { # There is data waiting to be read on FH1 } if (select($fh2,undef,undef,$timeout)) { # There is data waiting to be read on FH2 } # and so on ...}By building individual bitvectors for each filehandle and then combiningthem together using a bit-wise OR, we can check whether I of thefilehandles are ready with the combined bitvector or whether anindividual filahandle is ready with the individual bitvectors usingC.Note that several filehandles may be ready at once, so it would beprudent to service as many of the filehandles that you can beforecalling C again.=head3 I know which filehandles are ready. Now what?After you have setup C and determined which filehandles Areready, you'll want to read from those filehandles that are ready forreading and write to those filehandles that are ready for writing and dowhatever is necessary to those filehandles that have an exceptioncondition. [ To be honest, I've never used the ability to check forexception conditions on filehandles and I have little understanding ofwhat it may be for. The only reference I have handy at the moment,Stevens' U, says "... anexception condition corresponds to (a) the arrival of out-of-band dataon a network connection, or (b) certain conditions occuring on a psuedoterminal that has been placed into packet mode" ] But you must becareful how you read or write data to the filehandle. Buffered I/O likeC (aka, the diamond operator or <>) or C, won't workquite right, so you need to use C and C toread/write from/to the appropriate filehandles.=head2 IO::SelectAs you can tell by now, C isn't the friendliest of routinesto use. Luckily you have another option: C. Cis an object oriented interface that sits on top of the basicC routine such that you never have to see bitvectors andstrange assignments. You deal only with C objects and thefilehandles themselves. Here's a simple example:use IO::Select;my $sel = IO::Select=>new;$sel->add(\*FOO);$sel->add(\*BAR);$sel->add(\*BAZ);if (@fh = $sel->can_read($timeout)) { # Each filehandle in @fh is ready to be read from}The basic usage is simple: you create a IO::Select object (possiblyinitializing it with filehandles), then add new file handles to theobject using the C method, and when you're ready to "watch" thefilehandles you call one of the C, C, orC methods on the object. Each of these methodsreturns an array of filehandles such that you can read/write from/tothem.=head1 AUTHOR Jonathan Scott Duff duff@cpan.org

perltutorial

Threads: why locking is required when using shared variables (ikegami)

Big-O Notation - What is it good for? (Limbic~Region)

What Is The Big-O

What The Big-O Is Not

What The Big-O Is Good For

What Do Those Symbols Mean?

Common Causes for "Modification of a read-only value attempted" (imp)

Modifying $_ inside [doc://perlsyn#Foreach-Loops-for-foreach|foreach], [doc://map] or [doc://grep]

Modifying elements of @_ directly

Modifying $a or $b inside [doc://sort]

Autovivifying $a or $b inside [doc://sort]

Modifying an unlocalized $_

Guidelines to avoid read-only errors:

Notes

Lists With Constant Values

mod_perl / Apache::Registry accidental closures (imp)

mbito de variables en Perl: lo bsico (Hue-Bond)

mbito

Resumen

Espacios de nombres

my (y un poco ms sobre our) a.k.a mbito lxico

local a.k.a. mbito dinmico

POD en 5 minutos (Hue-Bond)

Plain Old Documentation en 5 minutos

La documentacin es importante

Documentacin en Perl

Encabezados en POD

Secciones habituales

Ejemplos de cdigo

Marcado

Entidades

Listas

Otras cositas de POD

Un ejemplo completo

Conclusin

perlunitut: Unicode in Perl (Juerd)

A Simple Socket Server Using 'inetd' (dwildesnl)

Gay (Anonymous Monk)

Module::Compile (or: what's this PMC thingy?) (Juerd)

History

What's going on?

Sad ending

Joyful rebirth of PMC and source filters

But we call them compilers now

Perl 6 again

Distribution

Perl 6 example

Final words

Using Look-ahead and Look-behind (Roy Johnson)

Syntax

Common tasks

Finding the last occurrence

Substituting before, after, or between characters

Matching a pattern that doesn't include another pattern

Nesting

Capturing

Creating COM and DCOM objects with Perl (JamesNC)

Test adding tutorial (wl69)

How A Function Becomes Higher Order (Limbic~Region)

Problem: We have a file containing a list of scores and we need to determine the highest score.

Stepping up from XML::Simple to XML::LibXML (grantm)

Installation

Some Sample Data

A Simple Problem

A More Complex Query

Modifying the XML

Other Operations

Resources

(P6) Why the tilde makes sense (Juerd)

handling multiple file handles for code generation (danmcb)

How to Ask a Regex Question (with Test::More) (repost, with Sitedocclan approval) (tphyahoo)

How to Ask a Question (With Test::More) (repost, now with Sitedocclan approval.) (tphyahoo)

How to Ask A Regex Question (With Test::More) (tphyahoo)

How To Ask a Question (With Test::More) (tphyahoo)

The extremely simple buffering tutorial (really just an example) (tphyahoo)

Not Exactly a Hash Tutorial (planetscape)

(A List of Resources, Definitely A Work in Progress, and Contributions Always Welcome :-)

Online:

Print:

`my` (y un poco ms sobre `our`) a.k.a mbito lxico

`local` a.k.a. mbito dinmico