AtomicSoft free Perl library

Download useful and extensively tested functions that are used almost in every project.

Terms of usage

(1) You must include following reference in your copyright notice: "Portions are Copyright AtomicSoft - http://www.atomicsoft.com. Used with permission.".
(2) You are granted a permission to use and redistribute portions of the code listed below free of charge as long as notice mentioned in (1) is kept.
(3) Use it at own risk. The portions are supplied "as is" and no warranties, whether explicit or implied, are valid.

Free code listing

• GetFileLock
  subroutine name: GetFileLock
  Locks a file on flock-disabled systems like Win9x, so that no one
  else can get to it while it is being accessed.
  It checks for the existance of a lock file and if it finds it, it
  waits until the lock file disappears, but not more than 20 sec.
  After the lock file is gone, it opens the lock file up itself.
  
  Input:
        $lock_file = filename to use as a temporary lock file
  
  Global variables used:
      $no_flock - disable flock or not
      %LOCK_HANDLES - hash of locked file handles
  
   
• ReleaseFileLock
  subroutine name: ReleaseFileLock
  Releases the lock file created by subroutine GetFileLock() when we are
  done with the original file.
  
  Input:
        $lock_file = filename to use as a temporary lock file
  
  Global variables used:
      $no_flock - disable flock or not
      %LOCK_HANDLES - hash of locked file handles
  
   
• appenddata
  subroutine name: appenddata
  Appends passed string and newline char ("\n") to specified file
  If error occurs, makes CGI process exit with error
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• cgidie_and_log
  subroutine name: cgidie_and_log
  
  1. Displays error message
  2. Logs error to "logs/error.log".
  3. Exits from script immediately
  Calls stack is logged to "logs/error.log", but NOT displayed to visitors.
  
  Global variables used:
    $last_die_calls_stack - filled by &catch_die_call_stack() subroutine
    $admin_email - e-mail address of admin
  
  No operations should be performed after calling this subroutine
  
   
• cookie
  subroutine name: cookie
  Returns cookie string for output to browser
  Input:
  $name - cookie name
  $value - cookie value
  $expires - expiration date or time increment
               (understands also time offset
               "12345s" - seconds
               "1234h" - hours
               "122d" - days
               "12w" - weeks
               "14m" - months
               "1.5y" - year
  $path - cookie path
  $domain - cookie domain
  $secure - secure cookie (true/false)
  
   
• copy_struct
  subroutine name: copy_struct
  Input: reference to Perl structure (without loops!!!)
  Returns: reference to copy of structure
  
   
• cprintf
  subroutine name: cprintf
  Input: string with %1,%2,%3... meta-strings, meta-string replacements
  Replaces these meta-strings with next parameters,
  passed to routine, and returns processed string
  Usage example: cprintf("I %2 free scripts, do %1?", "you", "like");
          Result: "I like free scripts, do you?"
  
   
• escape
  subroutine name: escape
  URL-encode string
  
   
• evaluate
  subroutine name: evaluate
  Evaluates perl code. If execution status is successful, returns result
  of execution. If execution status is error, makes process to die with error
  Usage example: evaluate("2+2");
          Result: "4"
  
   
• evaluate.demo
  subroutine name: evaluate
  Evaluates perl code. If execution status is successful, returns result
  of execution. If execution status is error, makes process to die with error
  "demo" edition allows usage of pre-defined strings only
  Usage example: evaluate("2+2");
          Result: "4"
  
   
• format_gmtdatetime
  subroutine name: format_gmtdatetime
  Formats GMT date/time as required to send with cookie
  
   
• get_cookies
  subroutine name: get_cookies
  Extracts all cookies from 'COOKIE' or 'HTTP_COOKIE' environment variable
  Returns: hash of cookies (cookie_name => cookie_value)
  
   
• getcounter
  subroutine name: getcounter
  Reads content of a counter file and returns an integer.
  If counter file doesn't exist, returns "0".
  If error occurs, makes CGI process exit with error
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• inccounter
  subroutine name: inccounter
  Increments content of counter and safely writes it back to file.
  Returns incremented value in counter file
  Creates file if it doesn't exist.
  If error occurs, makes CGI process exit with error
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• list_dir
  subroutine name: list_dir
  Input:     absolute path to directory
              files filter regexp [if empty, filter is ignored]
              minumal age (in days since last modification time) [if empty,
                           filter is ignored]
  Returns: array of found files (path included in filename)
  
   
• log
  subroutine name: LOG
  Appends message to log file. Before message timestamp is added.
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• macro_process
  subroutine name: macro_process
  Input: string
  If input string starts with "&", all the rest text
  is considered as perl script to be executed, and
  subroutine returns result of script work.
  Otherwise returns passed input string unchanged.
  Usage example: macro_process("Plain text");
          Result: "Plain text"
  Usage example: macro_process("& 2+2");
          Result: "4"
  
   
• max
  subroutine name: max
  Input: number1, number2
  returns greater of 2 numbers
  
   
• min
  subroutine name: min
  Input: number1, number2
  returns less of 2 numbers
  
   
• process_email_template
  subroutine name: process_email_template
  Input:     template filename,
              reference to hash tag_name=>tag_value
              use admin's email for "from" if "from" stays empty
              use admin's email for "to" if "to" stays empty
  Processes <!--$tag_name--> tags and <!--%% "perl commands" %%--> tags inside
  template file. <!--$tag_name--> tags are replaced with corresponding values.
  Parses processed file and extracts mail headers "from", "to", "subject",
  "bcc" and  message body.
  Returns:
  ARRAY to be passed to &send_mail() function: ($from, $to, $subject, $body, $bcc)
  
  Global variables used:
      %template_subst - hash for templates substitutions
      %templates_cache - caching hash for small templates (<5000 bytes)
      $templates_dir - filesystem path to templates dir
     $admin - admin works with script (disable template substitution feature)
     $admin_email - admin's email address
  
   
• process_template
  subroutine name: process_template
  Input: template filename, reference to hash {tag_name=>tag_value}
  Processes <!--$tag_name--> tags and <!--%% "perl commands" %%--> tags
  inside template file. <!--$tag_name--> tags are replaced with corresponding values.
  Returns: string (result of tempate file processing).
  Global variables used:
      %template_subst - hash for templates substitutions
      %templates_cache - caching hash for small templates (<5000 bytes)
      $templates_dir - filesystem path to templates dir (without trailing slash)
     $admin - admin works with script (disable template substitution feature)
  
   
• process_text
  subroutine name: process_text
  Input: template text, reference to hash {tag_name=>tag_value}
  Processes string using an input template text and <!--$ANYTHING--> tag values hash.
  Supports also <!--%% "perl commands" %%--> tags.
  Usage example: process_text('I <!--$WORDTWO--> free scripts, do <!--$WORDONE-->?', {WORDONE => "you", WORDTWO => "like"});
          Result: "I like free scripts, do you?"
  
   
• readdata
  subroutine name: readdata
  Reads all data from datafile
  If error occurs (e.g. file doesn't exist), makes CGI process exit with error
  Returns: reference to the array of lines, trailing "\n" in each
            line is not removed
  Global variables used:
      $no_flock - disable flock or not
  
   
• readdata_nolock
  subroutine name: readdata_nolock
  Reads all data from datafile without file locking
  If error occurs (e.g. file doesn't exist), makes CGI process exit with error
  Returns: reference to the array of lines, trailing "\n" in each
            line is not removed
  
   
• readhash
  subroutine name: readhash
  Reads all the data from $datafile
  Returns: reference to the HASH
  File format required: <key>\t<value>
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• readhash_nolock
  subroutine name: readhash_nolock
  Reads all the data from $datafile
  Returns: reference to the HASH
  File format required: <key>\t<value>
  
   
• readstruct
  subroutine name: readstruct
  Input: file name
  Returns: data structure, which is read from file specified by $filename,
  previously created with writestruct
  
   
• safe
  subroutine name: safe
  URL-encode [;,% \\"'\[\]\x00-\x1F] characters in string
  
   
• safe_tag
  subroutine name: safe_tag
  HTML-encodes string (prepare data for HTML output)
  Replaces:
  & -> &
  < -> <
  > -> >
  " -> "
  \x0D -> remove
  
   
• safe_tbl
  subroutine name: safe_tbl
  URL-encode \x00-\x1F characters in string
  
   
• send_mail
  subroutine name: send_mail
  Sends e-mail message via sendmail (standard Unix program) or
  via SMTP server (requires sendmail.pm module).
  Input:
     $from - "from" (sender) e-mail address
     $to - "to" (recipient) e-mail address
     $subject - subject of message
     $message - e-mail message body
     $bcc - reference to array of BCC recipients
     $bcc_max_addresses - max. number of BCC recipients in one envelope
  
  If mailing variables ($mailprog, $smtp_server) are set incorrectly,
  makes CGI process exit with error.
  
  Returns: string containing errors during sending e-mails (empty is successful).
  
  Global variables used:
      $mailprog - path to sendmail program (or compatible)
     $smtp_server - SMTP server address
      $log_emails - enable/disable logging of all e-mails sent
      $x_mailer - content of X-Mailer header
  
   
• send_mail_template
  
   
• struct2text
  subroutine name: struct2text
  Input:
        $struct - reference to any perl structure (no loops allowed!!!)
        $store_empty_values - store hash pairs with empty values or not
        $separator_char - lines separator (default is "\n"), used to write
                          structure in one line
  Returns: string, which represents passed data structure in Perl language
  Usage example: struct2text( {"key1" => "val1", "key2" => "val2",
                                "empty_value_key" => "",
                                "arr_key" => [4,5,6,8,"abc"]},
                       1, "\n");
          Result: '
                   {"arr_key"=>["4",
                   "5",
                   "6",
                   "8",
                   "abc",
                   ],
                   "empty_value_key"=>"",
                   "key1"=>"val1",
                   "key2"=>"val2",
                   }'
  
   
• sysreaddata
  subroutine name: sysreaddata
  Reads all data from datafile
  If error occurs (e.g. file doesn't exist), makes CGI process exit with error
  Returns: reference to the content variable (\$content)
  Global variables used:
      $no_flock - disable flock or not
  
   
• syswritedata
  subroutine name: syswritedata
  Writes in all the data to $datafile.
  Owerwrites file, if already exists
  If error occurs, makes CGI process exit with error
  Returns: nothing
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• text2struct
  subroutine name: text2struct
  Input: string with structure written in Perl language
  Returns: data structure, which is parsed from passed text,
  previously created with struct2text
  Note: old_text2struct is kept for compatibility with older versions.
  Subroutine without older format support will look like this:
  sub text2struct {
       my ($text) = @_;
       return &evaluate($text);
  }
  
   
• unescape
  subroutine name: unescape
  decode URL-encoded string
  
   
• unsafe
  subroutine name: unsafe
  decode URL-encoded chars, except "+" sign
  
   
• updatecounter
  subroutine name: updatecounter
  Writes new content to a file
  Utilizes function syswritedata(), which does the same job
  Global variables used:
      $no_flock - disable flock or not
  
   
• writedata
  subroutine name: writedata
  Writes in all the data from passed array of lines to $datafile.
  Input:     filename, reference to array of file lines
  Owerwrites file, if already exists
  If error occurs, makes CGI process exit with error
  Returns: nothing
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• writehash
  subroutine name: writehash
  Input: filename, hash reference
  Writes hash to file in format: <key>\t<value>
  
  Global variables used:
      $no_flock - disable flock or not
  
   
• writehash_nolock
  subroutine name: writehash_nolock
  Input: filename, hash reference
  Writes hash to file in format: <key>\t<value>
  
   
• writestruct
  subroutine name: writestruct
  Saves structure in file in native Perl language format
  Input:
  $filename - target file name
  $struct - reference to any perl structure
  $store_empty_values - store empty values of hashes or not
  $separator_char - lines separator (default is "\n"), used to write structure in one line
  Returns: nothing