Home Wendy
Web engine software

Wendy Home Page / Docs / API
 download   mods   docs   contact 

This document describes Wendy API. It was last edited on 5 Mar 2008. It should always describe lastest version.

Note: not all of listed variables, constants, methods are exported by default. Better specify what symbols you need in use argument. Example:

use Wendy::Util 'meta_get_records';
use Wendy::Config ( 'CONF_NOCACHE', 'CONF_MEMCACHED' );
use Wendy::Hosts qw( get_host_languages all_hosts );

Wendy consists of several modules:

See also:


Wendy not exports anything. Only one method is available:



  • CONF_MYPATH - Wendy installation directory. Formed at install time.
  • CONF_VARPATH - constant, path to Wendy var directory, which is catdir( <wendy installation directory>, var)
  • CONF_DEFHOST - default host name. Specified during installation.
  • CONF_DBNAME - database name
  • CONF_DBUSER - database user name
  • CONF_DBHOST - database host name. Can be array reference, in this case first working server is used.
  • CONF_WDBHOST - separate write database host name. Can be array reference, in this case first working server is used.
  • CONF_DBPASSWORD - database to run on
  • CONF_NOCACHE - completely disables disk cache (not recommended)
  • $WENDY_VERSION - string, Wendy version
  • CONF_MEMCACHED - specifies is memcached caching enabled. Implemented with Cache::Memcached
  • CONF_MC_SERVERS - array reference, memcached servers list
  • CONF_MC_THRHOLD - memcached parameter, compress_threshold
  • CONF_MC_NORHASH - memcached parameter, norehash



Wendy provides support for several read-only and write-only DB servers. Write functions named with 'w' prefix. These functions will automatically work with "write"-server -- or with default (CONF_DBHOST) if CONF_WDBHOST not set.

IMPORTANT: use appropriate functions in your module. Call w-functions for modifying queries! For read queries better call meta_get_records.

  • dbconnect() - connects to db specified in Config file. Called on initialization automatically.
  • wdbconnect() - connects to WRITE db server specified in Config file. You should call it in your handler yourself.
  • wdbbegin() - "BEGIN WORK" - starts a transaction (on WRITE server)
  • wdbcommit() - "COMMIT" - commits a transaction (on WRITE server)
  • wdbrollback() - "ROLLBACK" - cancels transaction (on WRITE server)
  • dbprepare( $sql ) - prepares statement. Returns statement handle ($sth). Do not use this for modifying queries like INSERT, UPDATE, DELETE - use wdbprepare in this cases!
  • wdbprepare( $sql ) - prepares statement on write server. Returns statement handle ($sth)
  • dbdisconnect() - disconnects from db, called automatically
  • wdbdisconnect() - disconnects from write db, called automatically
  • dbquote( $arg ) - quotes argument for safe db operating
  • dbgeterror() - returns last db error
  • wdbgeterror() - returns last write db server error
  • dbdo( $sql ) - simple execute query, no data needed. Not exported by default. Do not use this for modifying queries like INSERT, UPDATE, DELETE - use wdbdo in this cases!
  • wdbdo( $sql ) - simple execute query (on write server), no data needed
  • dbselectrow( $sql ) - selects one row, returns hash reference, (selectrow_hashref)
  • seqnext( $name ) - returns next value of sequence $name (queries write server)
  • wtransaction( ARRAY ) - run each of pre-formed SQL queries on write server in a single transaction.

    Return value: HASHREF with fields:
    • error = <0 or 1> error occured?
    • req failed request, if any
    • msg error message from db

  • wseqnext( SCALAR ) - alias to seqnext, with more logic name, as it queries write server



Provides methods to store scalar data. Data stored in memory if CONF_MEMCACHED is set, or in the file <host_dir>/cache/dc_<calculated_id> otherwise.

  • datacache_store( Id => $id, TTL => $ttl, Data => $data )
  • datacache_retrieve( $id ) returns stored scalar, undef if not found or expired.
  • datacache_clear( $id ) deletes record from cache



  • http_host_init( $hostname ) - check and initializes host named $hostname as Wendy host. Returns hash with id, host, and defaultlng fields. If supplied host is bad, returns default host data.
  • form_address( $str ) - forms and returns a template, or Wendy handler address from a string. For example /hello/world/ path becomes a hello_world Wendy address. So, hello_world template is processed, or hello_world.pl handler is looked for hello_world::wendy_handler function.
  • get_host_languages( $host_id ) - returns hosts languages as hash
  • get_host_aliases( $host_id ) - returns array, with aliases for host $host_id
  • get_aliases() - returns all aliases. You may pass ( Host => $host_id ) or ( Host => [ $hid1, $hid2, $hid3, ...] ) to get aliases only for specific host(s). Returns hash alias_id => { id, host, alias }
  • is_alias( $name ) - checks to see if $name is alias for some host, returns host id or undef
  • all_hosts() - pulls out all hosts. Returns hash reference, id => { id, host, defaultlng }



For arguments on mc_get, mc_set and mc_delete methods, see set, get, and delete methods in Cache::Memcached documentation.

  • mc_init() - initialize memcached, parameters taken from Config file
  • mc_set - store cache
  • mc_get - get cache
  • mc_delete - delete cache



  • installed_modules( Host => $host_id, Id => $id ) - get installed modules, all arguments are optional, returns hash $installation_id => { $module_name, $host_id }
  • register_module( Host => $host_id, Module => $module_name ) - registers a module as installed on host
  • unregister_module( Host => $host_id, Module => $module_name ) - un-registers module from host
  • is_installed( $module_name ) - looks if module_name is installed, returns hash as installed_modules does


This module is primarily for handling PROC: procedures in templates.

  • get_all_proc_names() - just gets all procedures, returns hash reference ( $id => { id, name, body } )
  • get_proc( Id => $proc_id, Name => $proc_name ) - same, but with parameters only one of Name od If should be passed.



This is what you will use most. It handles templates, macros contents, etc.

  • data_process( $WOBJ or $scalar or undef ) - process a raw data as a template.

    If nothing passed, acquires $WOBJ with Wendy::__get_wobj().

    If $WOBJ is passed, field "TDATA" is checked (like $w -> { "TDATA" }) for template data - ARRAY REF must be placed there. Deletes "TDATA" field on exit.

    If array ref is passed, it is used as "TDATA" value.

    If scalar is passed, is it split by lines and processed.

    Hash reference returned (if no errors), with all output-specific attributes: data, ctype, code, headers, ttl, expires, etc See Output object part.

  • template_process( $WOBJ or $scalar or undef ) - process a template. If $WOBJ is passed, template name taken from $WOBJ -> { "HPATH" }, If $scalar - that is template name itself, else Wendy::__get_wobj() called. Hash reference returned (if no errors), with all output-specific attributes: data, ctype, code, headers, ttl, expires, etc See Output object part.
  • load_macros(HostId => $host, Address => $address, Lng => $language ) - loads a macros from database. Complex method, see it's shortcut:
  • sload_macros( $addr or undef ) - loads macros for current host, current language and current addr ( $WOBJ -> { "HPATH" } if unspecified )
  • unset_macros( @a ) - unsets macros. Without any arguments, unsets all macros.
  • quoter( $str ) - quotes a sting, so it will not match replaces or functional keywords. Currently, this adds a space (or two) so data is simply not matched by Wendy::Templates regexps. Useful when user data gets processed inside template, like:

    add_replace( "FORM_ENTRY", $user_entered_data );

    which is more safe written as

    add_replace( "FORM_ENTRY", quoter( $user_entered_data ) );

  • add_replace( %h ) - adds replaces. Argument must contain pairs macros_name => macros_value
  • get_replace( $name ) - returns $name macros contents
  • kill_replace( @_ ) - same as unset_macros, but safer, as it will not delete all macros in case of empty @a



  • get_user( Login => $login, Id => $id, Password => $pass) - get user record. Returns hash reference.



All stuff goes here.

  • abs2rel_compat - compatibility method. Does File::Spec -> abs2rel, returns empty string when abs2rel returns '.' (as in earlier versions).
  • build_directory_tree( $path ) - builds directory tree starting at $path, returns @array. Recursive.
  • download_url(URL => $url, Referer => $ref, Agent => $user_agent ) - download URL. Uses LWP. Supports redirects. Only URL parameter is mandatory. Returns hash reference:
    		$outcome = {
    			code     => $response_code,
    			size     => $file_size,
    			ctype    => $content_type,
    			file     => $temp_file_saved_in,
    			msg      => 'ok'

  • meta_get_records( Table => $t,
    Fields => [ 'id', $f1 ],
    Where => $sql,
    Limit => $int,
    OrderField => $fieldname,
    OrderMode => 'DESC' or 'ASC',
    Offset => $offset,
    Memcache => 1 or 0, better CONF_MEMCACHED
    MemcacheTime => $<time_to store in memcached> )
    - generic method for DB queries with built-in memcached support. Just add Memcache => CONF_MEMCACHED in arguments hash. Returns hash. $id => { @fields }. Table must contain 'id' field as PRIMARY KEY. Use it. :-)
  • meta_get_record(...) - same, but returns one record
  • in( $val, @arr ) - checks wherever $val inside @arr or not
  • perl_module_available - checks if a certain Perl module installed and available. example:

    if( &perl_module_available( "IO::String" ) )

  • rand_array( @A ) - returns random element from @A
  • send_mail( From => $from, To => $to, Subject => $subj, RawSubj => $_8bitutfsubj, Text => $utfbody ) - sends a e-mail message. Not exported by default.


$WOBJ Object

$WOBJ is object used to get access to Wendy state, initialization information, modules and handlers. Sometimes $WOBJ gets modified, for example template_process puts there a list of processed templates, not to cycle.

How to get $WOBJ

$WOBJ is passed to your wendy_handler as first argument.

Or you can get $WOBJ, by calling Wendy::__get_wobj() method.

What $WOBJ is:

Look ad it's dump:

$VAR1 = { 'HPATH' => 'somepath',
          'LNG' => 'en',
          'HOST' => { 'defaultlng' => '1',
              'id' => '1',
              'host' => 'www.myhost.com' },
          'COOKIES' => {},
          'TPLSTORE' => '/var/www/wendy/var/hosts/www.myhost.com/tpl',
          'RLNGS' => { 'en' => '1' },
          'CGI' => CGI object,
          'DBH' => DBI object, 
          'HANDLERSRC' => '/var/www/wendy/var/hosts/www.myhost.com/lib/somepath.pl',
          'REQREC' => Apache2::RequestRecord object };

It contains information about current host, language and also references to some objects you may need.

CGICGI object. Use to get POST/GET parameters, form headers, etc. see perldoc CGI
DBHDatabase handle. I think you don't need it, look at Wendy::Db, for selecting data with memcached support, use meta_get_records
REQRECmod_perl Apache2::RequestRecord object


Output Object

Output object is a hash reference, in fields of which any output parameter can be customized. The following fields are available now:

dataData to be sent to client. HTML, text, binary, etc
filePath to file, which contents will be sent ( with $r -> sendfile() )
file_offsetfile offset, second argument for $r -> sendfile()
file_lengthfile length, third argument for $r -> sendfile()
ctypeCustom content-type. Default is text/html.
charsetCustom charset. Default is UTF-8. Unset manually when sending binary files or something other than text/*
codeCustom HTTP response code. Default is 200.
rawmodeIf this field is set in handler's return value, Wendy does not outputs anything, just exists. This can be used to gain complete full control over handler output.
ttlSeconds, how long can this page live in cache. Default - forever.
expiresUgly version of ttl, specifies exact expiration timestamp (in seconds).
headersHash-reference to any custom headers header_name => header_value. Cookies are to be set this way currently.

Array reference can be passed also (usable fot setting several headers with same name):

$VAR1 = [ { 'One' => 1 }, { 'Two' => 2 }, { 'Three' => 3 }, { 'One' => 4 } ];

nocache1 or 0 Dont cache my output!
msgStatus message to show after http code.

Full output object can be returned from wendy_handler. But if handler returns scalar (string data) it is assumed to be data part:

return "Hello, world!";
Equals to:
my $output_object = { data => "Hello, world!" };
return $output_object;


eugene kuzin, 2007-2011