The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Konstrukt-0.5-beta13
River stage zero No dependents
++
/ Konstrukt::Lib

NAME

Konstrukt::Lib - Common function library

SYNOPSIS

        $Konstrukt::Lib->some_handy_method($param);
        #see documentation for each method

DESCRIPTION

This is a collection of commonly used methods. For more information take a look at the documentation for each method.

CONFIGURATION

You may do some configuration in your konstrukt.settings to let the mail method know how it should work:

        #transport:
        #currently available: sendmail, smtp.
        #defaults to 'sendmail'.
        mail/transport      sendmail
        
        #the path of your mailer:
        #you may also specify some extra parameters.
        #defaults to 'sendmail'.
        mail/sendmail/path  /usr/sbin/sendmail -odb 
        
        #your smtp server:
        #defaults to 'localhost'.
        mail/smtp/server    some.smtp-server.com 
        
        #user and pass:
        #optional. when no user/pass is given, no auth will be tried.
        #defaults to 'undefined'
        mail/smtp/user      your username 
        mail/smtp/pass      your password
        
        #smtp authentication mechanism:
        #optional. may be: CRAM-MD5, NTLM, LOGIN, PLAIN.
        #when not specified every available method will be tried.
        mail/smtp/authtype  CRAM-MD5
        
        #defaults for the sender identification.
        #will be used when you don't specifiy it in your code.
        #defaults:
        mail/default_from   mail@localhost
        mail/default_name   Konstrukt Framework

METHODS

new

Constructor of this class

init

Initialization of this class

sh_escape

Escapes some critical sh characters

  • $string - Unescaped string

html_paragraphify

Converts \n-separated texts into to <p></p>-separated text.

  • $string - Unescaped string

html_escape

Escapes some critical HTML characters

  • $string - Unescaped string

html_unescape

Unescapes some critical HTML characters

  • $string - Escaped string

uri_encode

Encode a string into a sequence of hex-values as done in HTTP URIs.

Encodes every character but [0-9A-Za-z-_.!~*'()]. If the $enc_all parameter is true, all characters will be encoded.

  • $string - String to encode

  • $enc_all - Encode all characters

xml_escape

Escapes some critical XML characters

  • $text - Unescaped string

  • $esc_all - Boolean. Shall all chars besides letters and numbers be escaped?

crlf2br

Converts \r?\n to <br />\n

  • $text - Unescaped string

mail

Send out an email using the "sendmail" app on your system or directly via SMTP. You may specify some settings in your konstrukt.settings. See above.

Uses Mail::Sender for SMTP, which in turn uses Digest::HMAC_MD5 for auth type CRAM-MD5 and Authen::NTLM for auth type NTLM. So you might want to install those modules, if you use these auth types.

  • $subject - The mail's subject

  • $text - The body

  • $to - The recipient

  • ($cc) - Optional: Carbon copy

  • ($bcc) - Optional: Blind carbon copy

  • ($from) - The senders email address (e.g. john@doe.com). If not specified the defaults from your settings will be used.

  • ($FROM) - The sender full name (e.g. "John Doe") If not specified the defaults from your settings will be used.

mail_sendmail

Send out an email using the "sendmail" app on your system. Generally only used internally. You probably want to use "mail".

mail_smtp

Send out an email using an SMTP server. Generally only used internally. You probably want to use "mail".

random_password

Generates a random password consisting of characters and digits of a given length.

  • $length - The passwords length

  • $lowercase - Optional: Only use lowercase letters. Defaults to 0.

date_w3c

Returns the specified local time in the w3c date/time format. Actually, it's ISO 8601. Returns the diffence in the format as specified in http://www.w3.org/TR/NOTE-datetime YYYY-MM-DDThh:mm:ssTZD

  • $year - Either the years since 1900 (e.g. 1996 = 96, 2004 = 104) or the absolute year (e.g. 1996)

  • $month - Jan = 1, Feb = 2, ...

  • $mday - 1,2,3,...

  • $hour

  • $minute

  • $second

date_rfc822

Returns the specified local time in the date/time format specified in RFC 822: Day, DD Mon YYYY hh:mm:ss TZD

  • $year - Either the years since 1900 (e.g. 1996 = 96, 2004 = 104) or the absolute year (e.g. 1996)

  • $month - Jan = 1, Feb = 2, ...

  • $mday - 1,2,3,...

  • $hour

  • $minute

  • $second

plugin_dbi_install_helper

May be used to do the installation work of a DBI backend of some plugins.

The backend modules themselves pass a string containing SQL-statements (among others) to create the needed tables.

The section for the creation is named dbi: create. The section must be declared using the scheme described in "extract_data_sections".

The statements in each block are separated through semicolons.

Example:

        -- 8< -- dbi: create -- >8 --
        
        CREATE TABLE IF NOT EXISTS foo ( <definition> );
        CREATE TABLE IF NOT EXISTS bar ( <definition> );

The backend plugin stores these SQL-statements in it's __DATA__-section at the end of the file.

The install method of the backend module then can get as simple as:

        sub install {
                my ($self) = @_;
                return $Konstrukt::Lib->plugin_dbi_install_helper($self->{db_settings});
        }

This method returns true on success.

Parameters:

  • $db - Either an array reference containing the DBI source, user and password of the database your backend uses or a database handle to this db.

plugin_file_install_helper

May be used to do the installation work of the necessary files (like templates or images) of some plugins.

The section for the each text file (e.g. a template) is named textfile: subfolder/name.extension. The section must be declared using the scheme described in "extract_data_sections". The section for a binary file must be named binaryfile: subfolder/name.extension. The content of the binary file must be base64 encoded and put into the section. (You can use the supplied script base64enc.pl which reads from STDIN and writes the encoded data to STDOUT.)

The path/filename of template files should follow this scheme:

        <template type>/<name of the template>.template

template type should be used to group different types of templates. This may be:

  • layout: Templates to display the data

  • messages: Templates to display messages like errors (e.g. "permission denied") and confirmations (e.g. "entry successfully created")

Of course you can use other "directory names".

If the filename starts with a slash (/), the path will not be prepended by the basepath. It will be put into the document root.

Example:

        -- 8< -- textfile: layout/display.template -- >8 --
        
        This is the data:
        <+$ data $+>(no data specified)<+$ / $+>

        -- 8< -- textfile: layout/display_something_else.template -- >8 --
        
        -- 8< -- binaryfile: /gfx/some_icon.gif -- >8 --
        
        R0lGODlhEAAQAKIAAEuVzf+MO////v96G/fMrdDj8v/izf+1fyH5BAAAAAAALAAAAAAQABAAAANE
        KLrcziQMOZ8gI2sCOliYNhmC9wmHWCkmqh6MGWpw7M0D4cgi2fCi2qKVCto6iqIm4GspcCNBYVpg
        GFQ5i8AgoQy0jwQAOw==
        
        ...

The plugin stores these files in it's __DATA__-section at the end of the file.

The install method of the plugin then can get as simple as:

        sub install {
                my ($self) = @_;
                return $Konstrukt::Lib->plugin_file_install_helper($self->{template_path});
        }

This method returns true on success.

Parameters:

  • $basepath - The base path for all the files of your plugin.

extract_data_sections

Some plugins store some additional data at the end (after __DATA__) of the module file.

This method takes all this data and returns multiple sections of this data (which might represent some files or SQL statements and the like) as an hash:

        {
                name_of_section1 => 'content1',
                name_of_section2 => 'content2',
                ...
        }

Where the text after __DATA__ is organized like that:

        -- 8< -- name_of_section1 -- >8 --
        
        content1
        
        -- 8< -- name_of_section2 -- >8 --
        
        content2

The sections have to be separated by "-- 8< --" followed by the identifier of the section followed by "-- >8 --" all on one line.

Parameters:

  • $package - The name of the package whose __DATA__ section should be read and parsed

xor_encrypt

Encrypt/Decrypt a string with a defined key using XOR encryption.

  • $text - String to en-/decrypt

  • $key - The key to use for en-/decryption

quoted_string_to_word

Splits a given string into word. Multiple words which are surrounded by doublequotes will be parsed into one word.

Returns an array of words/word sequences.

  • $string - String to parse

AUTHOR

Copyright 2006 Thomas Wittek (mail at gedankenkonstrukt dot de). All rights reserved.

This document is free software. It is distributed under the same terms as Perl itself.

SEE ALSO

Konstrukt