Wolfgang Wiese > web-1.35 > Web

Download:
web-1.35.tar.gz

Annotate this POD

View/Report Bugs
Source  

NAME ^

Web - A set of useful routines for many webworking purposes

SYSTEM REQUIREMENTS ^

This module was primarily made for UNIX/Linux-Systems. Parts of it cannot be used on other systems. E.g. the procedures for file locking demand systems that can use symlinks. If you use the modul on systems where symlinks cannot be used, fatal errors may happen.

SYNOPSIS ^

use web;

ABSTRACT ^

This perl module serves users with several useful routines for many purposes, like generating webpages, processing CGI scripts, working with XML datafiles and net-connections. It also uses own variants of routines, that was invented first in the famous libraries CGI.pm and cgi-lib.pl.

INSTALLATION ^

If you don't have sufficient privileges to install web.pm in the Perl library directory, you can put web.pm into some convenient spot, such as your home directory, or in cgi-bin itself and prefix all Perl scripts that call it with something along the lines of the following preamble:

        use lib '/home/myname/perl/lib';
        use web;

DESCRIPTION ^

NLock

This routine allows to set a filelock across NFS-boundaries. The common used perl-routine flock() fails at this point, so this routine is a useable alternative for bigger file-systems. It uses the modular functions link() and unlink() to mark a file locked. In addition to this, it also gives the locked file a counter: A file that is locked for more than $web::MAX_LOCKTIME seconds will be freed by the next process that calls NLock() on this file. A calling process gets either 0 or 1 as a return value, where 1 is returned if the file-locking was successful. 0 is returned only if the process waits for more than $web::MAX_WAITLOCK seconds or if symlink() fails.

Example 1:

        $filename = "data.txt";
        NLock($filename);
        open(f1,"$filename");
        # do something
        close f1;
        NUnlock($filename);

Example 2:

        #!/local/bin/perl5
        use web;

        $stat= &NLock("jump.pl");
        print "Lock: stat= $stat\n";
        $stat= &NLock("jump.pl");
        print "Lock this file again: stat= $stat\n";
        sleep 8;
        $stat= &NLock("jump.pl");
        print "Lock this file again: stat= $stat\n";
        $stat= &NUnlock("jump.pl");
        print "Unlock: stat= $stat\n";
        exit;

NUnlock

This routine removes the filelock that was set with NLock(). See NLock().

NUnlockAll

In using this command, you can remove all file-locks, that was set with NLock() and which wasn't removed before. It takes the list of file-locks out of the hash %web::lockliste.

GetYearDay

This routine can be used to calculate a day's position within the year in days. It returns -1 if the argument is no date.

Example:

        $today = "$web::tag.$web::monat.$web::jahr" || "14.9.1999";
        $number_of_days = GetYearDay($today);
        print "Date: $today; It is the ${number_of_days}th day in this year.\n";

GetWeekDay

By using this routine you'll get the weekday of a given date, which is a number between 0 (for sunday) and 6 (for saturday). If the argument is wrong, -1 will be returned.

Example:

        $today = "$web::tag.$web::monat.$web::jahr" || "14.9.1999";
        $weekday = GetWeekDay($today);
        print "It is $web::wochentag[$weekday], $today.\n";

isLeapYear

This function returns true, if the argument is a leapyear. If no argument is given, the current year is used.

Example:

        $this_year = 1999;
        if (isLeapYear($this_year)) {
          print "It's leapyear.\n";
        } else {
          print "No leapyear.\n";
        }
        # Returns 'No leapyear.'

GetDatebyYDay

This is the opposite of the GetYearDay() routine. It calculates the date from a day's position within a year. It returns nothing if the argument is out of range [1..365].

Example:

        $num_of_yearday = 32;
        $date = GetDatebyYDay($num_of_yearday);
        print "The date is $date\n";
        # Returns 'The date is 1.2.1999', if $web::jahr = 1999.

Add_Days_to_Date

Adds a number of days to a given date. Notice, that it works for adding only. Negative daynumbers might lead to errors in case of a number smaller than -365.

Example:

        $startdate = "1.11.1999";
        $modi_days = 119;
        $enddate = Add_Days_to_Date($startdate,$modi_days);
        print " $startdate + $modi_days Day(s) = $enddate\n";
        # Will return "28.2.2000".

Get_Seconds

Returns the number of seconds elapsed since midnight of a given time or 0 if the time format isn't valid (hour:minute:second).

Example:

        $jetztzeit = $web::stunde.":".$web::minute.":".$web::sek;
        $textzeit = "12:00:00";
        $diff_sekunden = abs(Get_Seconds($jetztzeit)-Get_Seconds($textzeit));
        print "Time differs with $diff_sekunden seconds.\n";

GetPassedDaysbyMonth

Returns the number of days that have passed by the inputvalue, which represend the number of a month.

Example:

        $month = 8;
        $passed_days = GetPassedDaysbyMonth($month);
        print "$passed_days days have passed, before the $month. month came\n";

Check_Name

Sometimes you need to get file names or other data from the internet. Due to the fact that you'll never know who can touch the data, you need to make sure that no one can send special chars which allow the execution of system commands. CERT gave out a set of characters that are harmless. They are set in the variable $web::OKCHARS as "a-z, A-Z, 0-9 _-.@/". This routine will check the argument for other characters and remove them from the string. That way, you can take filenames from the web without being afraid that someone else sends a dangerous string.

Example:

        $insecure_filename = $ENV{'QUERY_STRING'};
        $secure_filename = Check_Name($ENV{'QUERY_STRING'});
        
        if (length($secure_filename) != length($insecure_filename)) {
          print(PrintHeader);
          print "The query-string contains invalid signs.";
          exit;
        } else {
          open(f1,"<$secure_filename") || Fehlermeldung("File $secure_filename not found.");
          # do something
          close f1;
        }

Using Check_Name(), query strings like "/tmp/something|+'/bin/term+-display+131.188.3.9" won't work.

PrintHeader

Returns the string "Content-type: text/html\n\n", if it wasn't returned before. Additionally it can reset cookies if there were some before on this domain or set new cookies by using a hash-reference. The additional parameters are:

Arguments:

           1            Activates the setting of cookies. If new cookies
                        are defined by argument 3, these will be set. Otherwise
                        the cookies as given by $ENV{'HTTP_COOKIES'} are
                        used.
           2            On default, PrintHeader() will return nothing, if it
                        was called before. By setting this argument unlike 1
                        it will ignore previous calls.
           3            A hash-reference, which defines the cookies to be set.
           4            The path-value for the cookies. On default its set to
                        "/".
           5            The lifetime-value for cookies in days. On default its
                        set to 30.

ReadParse

Reads the query string and/or the standard input and returns them as a hash. If the content-type is marked as multipart, it allows file uploads as long the variable $web::allowuploads is true. In this case, the new file is stored under its name, or to be precise, what Check_Name() makes of its name.

Example:

        %in = ReadParse;
        print(PrintHeader);
        print "<ul>\n";
        foreach $key (keys %in) {
          print "<li><b>$key</b>  &nbsp;  $in{$key}</li>\n";
        }
        print "</ul>\n";

Fehlermeldung

This routine can be used to print out error messages. It also replaces CgiDie() from cgi-lib.pl. In addition to the former CgiDie(), this routine can also take a layout file to produce a better designed output. It takes the error message, the error title and the file name of an optional layout file as arguments.

This layout file is a common HTML file, but it can contain the strings #ZEIT#, #ERRORTEXT# and #TITEL#. These strings will be replaced with the arguments. In using the global variable $web::errorlayout_file you can predefine a layout-file till the end of the program.

The routine checks for the environment variables HTTP_USER_AGENT and SERVER_NAME to see whether it was called from of a CGI script. If so, it also prints the content-type. To avoid file-locking problems, this routine also executes NUnlockAll.

Example:

        if (not (-r "hallo.html")) {
          Fehlermeldung("Die Datei hallo.html konnte nicht gelesen werden. 
          Bitte ueberpruefen Sie die Dateirechte.","Datei nicht lesbar");
        }

isURL

Checks if the argument has a valid URL syntax. Returns true if the syntax is ok.

Example:

        $url = "http://www.xwolf.com";
        if (isURL($url)) {
          print "Valid URL: $url\n";
        }

isMail

Checks if the argument's syntax is allowed for email addresses. Returns true if it looks ok. Notice that it doesn't check whether the email really exists!

Example:

        $mail = 'xwolf@xwolf.com';
        if (isMail($mail)) {
          print "Mail address $mail looks correct.\n";
        }

isDatum

Checks if the argument is a valid German date. The syntax for a date was set to: DD.MM.YYYY.

isIP

Checks the given argument for a valid IP-syntax. It returns TRUE on success. (This routine was invoked by Rolf Rost, http://www.-i-netlab.de)

isZeit

Checks if the argument is a valid time. The syntax of a time was set to: HH:MM:SS.

Read_Parafile

In Unix many people define configuration files in a way that variable names and arguments are divided by one or more tabs and comments are preceded by a '#'. Variable names start with the first char of a line.

This routine allows reading such a file and returns its content within a hash. Comments of variables are saved into the hash too, but with the string $web::PARACOMMENT_SIGN as appendix (Notice that comments here are put after the variables, not before).

If the file could not be read, the hash value 'status' is set to 400, otherwise it is set to 200.

Example:

        $configfile = "config";
        %CONFIG = Read_Parafile($configfile);
        if ($CONFIG{'status'}==400) {
          Fehlermeldung("Could not read the config file.");
        }
        foreach $key (keys %CONFIG) {
          if (not ($key =~ /$web::PARACOMMENT_SIGN/i)) {
            print "$key \t $CONFIG{$key}\n";
          }
        }

ReadLayout

Reads a file and returns its content in an array.

ReturnFlagContent

Returns everything between a given HTML flag.

Example:

        $text = "<b>Startseite</b>";
        $content = ReturnFlagContent("b",$text);
        print "$content\n";
        # Prints 'Startseite'

ReplaceText

This function does two things: It replaces the string #TEXT# with a given string and sets a <a href=""></a> around every URL within the text. This routine was made mainly because a simple search and replace for s/#TEXT#/$newtext/gi needs a long time if $newtext contains linebreaks. Therefore, all linebreaks are first replaced with <_BR_>, then the text will be replaced and after this all <_BR_>'s are set to linebreaks again. It's a small and dirty trick, but it works.

Example:

        $text = "Here\n is\n something\n many\n lines.\n Insert here: #TEXT#\n\n";
        $insert = "This was inserted.";
        $text = ReplaceText($insert, $text);

WriteLog

This routine puts a line into a file together with the time and the IP/host which the script was executed on.

Example:

        WriteLog("debug.log","Files updated.");

GetSentence

This procedure was made as an additional search-procedure for textparsing. It will return the full sentence of a long text, if a the search-word is in it. Notice, that this function fails, if there are shortcuts of words and the sentence was defined as something between two dots.

Example:

        use web;
        $text = "It's an old story of a lost world, calling itself the
                Realm of Magic. Duncan Idaho, the famous warrior killed
                one elven maid too much. The mortals gathered and
                formed a powerful group to kill him. But then something
                happened...";
        $search = "Duncan";
        print(GetSentence($text,$search));
        # Returns "Duncan Idaho, the famous warrior killed  
        #          one elven maid too much"

RemoveHTML

RemoveHTML() will remove all HTML-Tags and Specifications out of a given string.

Example:

        $asciitext = RemoveHTML($htmltext);

HtmlTop

Returns a HTML head. Stolen out of cgi-lib.pl. Use with print(HtmlTop);

HtmlBot

Returns the ending tags of a HTML-document. Stolen out of cgi-lib.pl. Use with print(HtmlBot);

Redirect()

Makes a redirection towards another URL.

Example:

        Redirect("http://www.xwolf.com/");
        # will tell the server to set the location to the given url.

AUTHOR INFORMATION ^

Copyright 1999-2000 Wolfgang Wiese. All rights reserved. It may be used and modified freely, but I do request that this copyright notice remain attached to the file. You may modify this module as you wish, but if you redistribute a modified version, please attach a note listing the modifications you have made.

Address bug reports and comments to: xwolf@xwolf.com

CREDITS ^

Thanks very much to:

Johannes Schritz (johannes@schritz.de)
Gert Buettner (g.buettner@rrze.uni-erlangen.de)
Manfred Abel (m.abel@rrze.uni-erlangen.de)
Rolf Rost (rolfrost@yahoo.com)
syntax highlighting: