This is not a module, it's a script.

After going through most of my modules on CPAN to make sure that they will work on the soon to be Perl 5.8.1, I again realized that the low profile, but very handy cpan-upload utility script is a must-have for a module author.

What does it do? Well, not a lot, but it does it quickly and quietly. It uploads your files to CPAN as simple as:

    cpan-upload Your-Module-1.07.tar.gz

What do you need to do? Well, download it, then:

perl Makefile.PL
make
make test
make install

user CPANID
password xyuolskhj
mailto your@address.tld

Neil Bowers has made a very nice utility script that is well documented. Kudo's to Neil!

Liz

[feedback] testing ... is this thing on? ahem. Manipulating dates in Perl is a common task, and it's no wonder that there are a plethora of date modules in the Date namespace. As you can see in the following Power Point slide [show slide that makes the Bioperl Class Diagram look easy], determining which Date module to use is quite a chore. All of that just to find a date. Enter Acme::Current.

use Acme::Current;
printf "It's now %04d/%02d/%02d.\n",
    $Acme::Current::YEAR,
    $Acme::Current::MONTH,
    $Acme::Current::DAY
;
[download]

It's now 2003/07/15.

There, let's run that code again:

use Acme::Current;
printf "It's now %04d/%02d/%02d.\n",
    $Acme::Current::YEAR,
    $Acme::Current::MONTH,
    $Acme::Current::DAY
;
[download]

It's now 2003/07/16.

[feedback]

I would, however, like to see a module that is able to connect to the windows SMB shares and send and receive packets with out using the standard Windows API to do so. The reason being is that there is a hefty timeout delay for an incorrect password.

Per request, here are some source examples of how this can be useful:

1.) Make a connection to the IPC$ share.

if (ConnectIPC($server, "", "", "")) {
    $this->{f_resultsTB}->AppendText("Null Session to $server successf
+ul.  \n");
    # Now try getting some information
    $this->{f_resultsTB}->AppendText("Connecting to Registry...\n");
    $this->{f_resultsTB}->AppendText("Succesful!\n");
    \&RegConnect($server);
[download]

What have we done here? We've established a connection to the server's ($server) IPC$ share with null credentials, i.e., ConnectIPC(server, user, pass, domain), with null for user, pass, and domain.

$this->{f_resultsTB}->AppendText("[Local Users]  \n");
    @users = GetLocalUsers($server);
    if (@users) {
        foreach (@users) {
            $this->{f_resultsTB}->AppendText("$_  \n");
            $user = (split(/:/,$_))[1];
            $l_user = (split(/\\/,$user))[1];
            \&GetUserInfo($server,$l_user);
        } 
    }
    else {
        $this->{f_resultsTB}->AppendText("Did not retrieve local users
+.  \n");
    }
[download]

Its important to recoginize that this should be within the if(ConnectIPC(...)) block. I will post the whole code bellow.

if (ConnectIPC($server, "", "", "")) {
    $this->{f_resultsTB}->AppendText("Null Session to $server successf
+ul.  \n");
    # Now try getting some information
    $this->{f_resultsTB}->AppendText("Connecting to Registry...\n");
    $this->{f_resultsTB}->AppendText("Succesful!\n");
    \&RegConnect($server);

        $this->{f_resultsTB}->AppendText("[Local Users]  \n");
    @users = GetLocalUsers($server);
    if (@users) {
        foreach (@users) {
            $this->{f_resultsTB}->AppendText("$_  \n");
            $user = (split(/:/,$_))[1];
            $l_user = (split(/\\/,$user))[1];
            \&GetUserInfo($server,$l_user);
        } 
    }
    else {
        $this->{f_resultsTB}->AppendText("Did not retrieve local users
+.  \n");
    }
}
else {
        $this->{f_resultsTB}->AppendText("Could not establish null ses
+sion with $server.  \n");
}
[download]

I apologize, this code has been made for Visual Perl.NET, hopefully some of you will find that helpful. Here is a link to the actual Perl script I used to help me figure out the module: Null.pl

I have a number of utilities written in Perl that take a while to complete -- e.g. scaling a large number of digital images. It would be nice to know when the task is finished, but usually the script is too small to warrant extravagant code for monitoring progress.

Fortunately, there's Term::ProgressBar. It lets you add a fancy wget/scp-style progress bar to your own ap, with only a few lines of code. Martyn J. Pearce has really made an effort to make things easy for us: For basic usage, you just need to call one function to set up the progress bar and another one to update it. He even threw in ETA (estimated time of arrival) calculation.

Let's look at some code. I like the ETA display, so I'm making it a bit more complicated than the very basic usage (two more lines added, horrors!). This is taken from my image scaling script:

use Term::ProgressBar;

my $progress = Term::ProgressBar->new({name  => 'Scaling images',
    count => scalar @imgfiles,
    ETA   => 'linear'});

# update ETA once per second at most
$progress->max_update_rate(1);

foreach (@imgfiles) {
    perform_imaging_ops($_);

    $progress->update();
}
[download]

The output looks somewhat like this (note: I shortened the output here to make it fit on one code line):

crenz@tiffy:~ > scaleimages /my/directory
Scaling images:  19% [=========                                       
+ ]ETA  23:35
[download]

I'm using a German locale, so the script displays 23:35 instead of 11:35pm -- just in case you're wondering. When the estimated time needed is short, the display automatically changes:

Scaling images:  92% [============================================    
+ ]5m14s Left
[download]

I'm using the module on Mac OS X, but it should work on all standard Unix terminals. Not sure whether it works on Windows.

Name

Net::IMAP::Simple

Author

Joao Fonseca

Version

0.93

Description

Perl extension for simple IMAP account handling. This module leaves a possibility to create, delete or rename IMAP mailboxes, read, copy, delete mail messages.

Methods

new(host, opt_par1 => val1, opt_par2 => var2, ...)

Method new create a new object  Net::IMAP::Simple Parameter host defines a IMAP host name, another parameters are optional and pass to

 
    IO::Socket::INET
[download]

directly. Usually, it uses parameter Timeout but you can see other parameters in IO::Socket::INET documentation
The method new returns an object which connected to the IMAP server in successful case or it returns undef and stores an error code into variable $!:

	my $imap = Net::IMAP::Simple->new($my_host, Timeout => 30) or die "Can't connect to $my_host: $!";
	

login(user_name, user_passw)

This method tries to login on IMAP server using a pair  user_name and user_passw. This method returns a number of messages in the default user's mail box (usually this is INBOX) or undef (at that, you can use a hash for defining of user_name and user_passw):

	defined (my $num_msgs = $imap->login($my_name => $my_passw)) or die "Can't login!";
	

mailboxes()

This method returns a list of all user's mailboxes:

	my $mailbox_list = $imap->mailboxes;
	

select(mailbox_name)

This method selects a mailbox according to mailbox_name and return a number of messages which consist in this mailbox (if mailbox is empty the method select returns 0) or undef if mailbox doesn't exist:

	defined(my $num_msgs = $imap->select($mailbox)) or die "Mailbox $mailbox is invalid!";
	

get(message_number)

Method get returns a reference on array which consists lines of message with number message_number:

	print "Message No 10:\n";
	map { print $_ ."\n" } @{ $imap->get(10) };
	

getfh(message_number)

This method returns the lines of defined message alike previous method but stores result into temporary file. This means that the message transfers early on user's computer and then you can read it from file:

	my $fh = $imap->getfh(10);
	print "Message No 10:\n";
	print <$fh>;
	close $fh;
	

delete(message_number)

This method marks a defined message as delete but, in fact, this message will be delete when method quite will be called. Net::IMAP::Simple doesn't leave to possibility of undelete of message which were marked as delete:

	$imap->delete(10);
	

top(message_number)

Method top returns a header of defined message as an array reference:

	my $header = $imap->top(10);
						
	my $head_obj = Mail::Header->new($header);
	my $subj = $head_obj->get('Subject');
	my $from = $head_obj->get('From');	
	

list()

If this method is called without a parameter, it returns size for all messages in the mailbox as hash reference where key is message ID and value is message size:

	my $all_sizes = $imap->list;
					
	map { print "Message No $_: $$all_sizes{$_} bytes!\n" } keys %$all_sizes; 

	or

	my $msg_size = $imap->list(10);
	print "Message No 10: $msg_size bytes!\n";
	

seen(message_number)

This method returns 'true' if defined message was read and 'false' if not. You can use method seen for determination of list of new messages in your mailbox:

	for(1 .. $num_msgs) { push @new_msgs, $_ unless $imap->seen($_);
	print "You have ".scalar @new_msgs." in your mailbox!\n";
	

quit()

Method quit deletes all marked messages and close a connection with IMAP server:

	$imap->quit;
	

Others methods

You can manipulate a mailbox by using following methods:

• $res = $imap->create_mailbox(mailbox_name);
• $res = $imap->delete_mailbox(mailbox_name);
• $res = $imap->rename_mailbox(old_mailbox_name, new_mailbox_name);

    $res = $imap->copy(message_number, mailbox_name);
[download]

Resume

This module will be useful in case of creation a mail checker or simple mail interface to IMAP server. In more complex case preferably use more power modules

• Net::IMAP leaves larger set of methods for intercept and interpretation of server responses, management of mailboxes and messages etc.
• Mail::IMAPClient leaves most full interface to the IMAP server but you should be ready to interpret some responses of server by yourself using RFC 2060.

More recently, I attended a Perl monger tech talk, at which Schwern was presenting "MakeMaker is doomed!". Prior to the talk, I was somewhat skeptical. After all, Makefile.PL works, Nearly all of CPAN uses a recognised and recognisable installation process:

perl Makefile.PL
make
make test
make install
[download]

Portability

• make
• the shell

This is indeed what Module::Build is, and it calls no modules which use XS. The steps are replaced with:

perl Build.PL
perl Build
perl Build test
perl Build install
[download]

I came away from Schwern's talk convinced that Module::Build is the future. Also, there is talk that it is entering the core of 5.10, which will greatly help the advocacy cause.

Complex configuration

Module::Build uses an OO interface, and the actions that you want to do in configuration are method calls. For doing _really_ clever stuff you can subclass Module::Build.

Using Module::Build for other than modules

Conclusion

Update, October 2004

• Automated installs with CPAN don't happen. Though they might if you are lucky and the module author has provided a compatibility Makefile.PL that does everything Build.PL does. Apparently CPANPLUS supports Module::Build builds, but I have had problems getting CPANPLUS working at all on some platforms.

• Build.PL does not have the standard command line options that Makefile.PL uses. In particular, there is not an equivalent of PREFIX=x, which I need for builds where I am installing to platforms where I don't have root.

• Some module kits have a Build.PL and a Makefile.PL which build differently. This may well be an oversight on the part of the module author, but it does not reflect well on the underlying build mechanism.

• I have also had issues building XS code with Module::Build.

Mandatory background story

I had an end-of-day job that was taking too much time, and it turns out that the problem was retrieving the closing time values from several textual log files, using a sequential scan.

I knew the answer was to do a binary search, but I was fairly certain someone else HAD to have run into this problem before, so I typed text file binary search in the Search box here, and got Binary Searches on Sorted Text Files.

runrig's reply in that thread pointed me to File::SortedSeek.

Module overview

File::SortedSeek implements binary searches through large sorted text files, using string, numeric, or timestamp keys.

It's ideal for finding a particular time in large logs, for instance.

The module was authored by Dr. James Freeman, better known around here as tachyon.

Usage example

The files I have to deal with use a non-standard integer timestamp. Each line looks like

{timestamp} {value} {value} {value} {value}

Using the module to find the right line couldn't be easier!

#!/usr/bin/perl -w
use strict;
use File::SortedSeek ':all';

my $targetTS=1234567789;  # for instance
open(FILE,"<data.in") or die "Can't open data.in, error $!";

# File::SortedSeek::numeric looks for a numeric key
# It takes an optional sub ref argument to "massage" the
# line from the file to extract the key.
numeric(*FILE,$targetTS,sub {$_[0]=~/^\s*(\d+)/ or return 0; return $1
+});

# this will return the line that matches $targetTS, or the first line 
+>
$line=<FILE>;

close(FILE);
[download]

Conclusion

tachyon rules!!! :)

Taken from the CPAN docs HTML::Template:

Create a simple HTML page, with two template variables HOME and PATH, name it test.tmpl.
We will fill the variables with data below.

  <html>
  <head><title>Test Template</title>
  <body>
  My Home Directory is <TMPL_VAR NAME=HOME>
  <p>
  My Path is set to <TMPL_VAR NAME=PATH>
  </body>
  </html>
[download]

Now, lets build a program to fill in those previously named variables. The result is displayed below

  #!/usr/bin/perl -w
  use HTML::Template;

  # open the html template
  my $template = HTML::Template->new(filename => 'test.tmpl');

  # fill in some parameters
  $template->param(HOME => $ENV{HOME});
  $template->param(PATH => $ENV{PATH});

  # send the obligatory Content-Type and print the template output
  print "Content-Type: text/html\n\n", $template->output;
[download]

Make sure its all ready to go, then point your browser to the script you just created, now, you should have output that looks kinda like this:

  My Home Directory is /home/some/directory
  My Path is set to /bin;/usr/bin
[download]

It Gets Better

Not only does it support simple variables, you can also:

I found this module when I was looking for a solution to easily and intelligently format some data in text-based tables in an e-mail message. After a lot of wrestling, I'm here to report that Data::ShowTable was not a good choice for this. Here's why:

• First, It should have a clue that the module hasn't been updated since August, 1997.
• I noticed that several standard column types weren't supported that appeared to fit in with author's intended support of SQL character types in this capacity. The author's email address bounced when I sent a suggestion to update this area.
• The interface is at least partly broken. I was trying to use a syntax that was documented as valid, but was getting "not a CODE ref" errors, even though I wasn't using CODE refs. I switched to an equivalent syntax and it worked.
• My most substantial complaint against the module is that it insists on printing the results to STDOUT. In an era where using templates is common, this seems archiac to me. I hacked up support this to get my project done. A patch for this is here.

Since then, I've learned about a module named Text::FormatTable. If I need to address the same problem space instead, I'll try this module instead.

To it's credit Data::ShowTable seems well written and has some decent features. However, after my various annoyances with it, I've come to feel it's no longer being developed by anyone because there is a better solution out there.

During my daily http://search.cpan.org/recent ritual, I came across a new module called Slurp.

Slurp provides three functions: slurp, to_array and to_scalar. slurp is exported by default, the other two can be exported too.

Object orientation

Again, fake object orientation. You can use either slurp($filename) or Slurp->slurp($filename) to do exactly the same thing. I fail to see how Slurp->to_array is any better than Slurp::to_array. Both can be used.

Naming

This module handles files, so it should be in the File:: namespace. It is, however, just called Slurp. A much better name would be File::Slurp. But that module already exists.

File::Slurp

File::Slurp provides exactly the same functionality, plus some extra handy functions. It has been around since 1996 and is does its job well. Slurp has no advantage over File::Slurp. The author clearly didn't search CPAN, or wants to compete.

Documentation

The only positive sound about this module you'll hear from me is: nice documentation! Every function is docmented in detail.

Conclusion

Slurp does what it is supposed to do and is documented quite well. However, it should not be on CPAN, for two reasons: it is not in the correct namespace and another module already provides the functionality. This module adds nothing to CPAN but needless confusion for people in search of a file slurping module.

I think it should be removed from CPAN, or at least be renamed to something in File::.

Apache's .htpasswd files consist of user/password pairs, one pair per line, eg:

username1:unixcryptpassword
username2:unixcryptpassword
[download]

Drawbacks:There is no way to list all the users in a passwd file. There is no method to find out if a specific user has an account. The fetchInfo() method can be bent to this purpose, but it returns "0" for an invalid account, otherwsise any info that is stored for that user or undef, to test for a user I wrapped it in a sub like this-

sub is_user {
        my $user = shift || return;
        my $info = $htpasswd->fetchInfo($user);
        return 0 if ($info eq '0');
        return 1;
}
[download]

Sample code