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:

• $WOBJ object
• Output object

Wendy.pm

Wendy not exports anything. Only one method is available:

• Wendy::__get_wobj() - Returns WOBJ object, which is a hash reference. More details on $WOBJ.

Top

Wendy::Config

• 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

Top

Wendy::Db

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

Top

Wendy::DataCache

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

Top

Wendy::Hosts

• 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 }

Top

Wendy::Memcached

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

Top

Wendy::Modules

• 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

Wendy::Procs

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.

Top

Wendy::Templates

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

Top

Wendy::Users

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

Top

Wendy::Util

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.

Top

$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.

Top

Output Object

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

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!";

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

Top