NAME

XAO::Utils - Utility functions widely used by XAO suite

SYNOPSIS

  use XAO::Utils (:all);    # export everything

  or

  use XAO::Utils (:none);   # do not export anything

DESCRIPTION

This is not an object, but a collection of useful utility functions.

KEYS HANDLING

Utility functions in this group can be imported by using 'keys' tag:

 use XAO::Utils qw(:keys);

Here is the list of functions available:

generate_key (;$)

Generating new 8-characters random ID. Not guaranteed to be unique, must be checked against existing database.

You can pass additional argument to add some more randomness, but it is not required and is kept for compatibility.

Generated ID is relativelly suitable for humans - it does not contain some letters and digits that could be easily misunderstood in writing:

0 (zero)

Looks the same as letter O.

1 (one)

Is almost undistinguishable from capital I

7

Written by american is often taken as 1 by europeans and vice versa.

V

Is similar to U.

Examples of generated IDs are E5TUVX82, ZK845LP6 and so on. Id would never start from digit!

repair_key ($)

Repairing human-entered ID. Similar letters and digits are substituted to allowed ones.

Example:

 my $ans=<STDIN>;
 my $id=repair_key($ans);
 die "Wrong ID" unless $id;
 print "id=$id\n";

If you enter "10qwexcv" to that script it will print "IOQWEXCU".

DEBUGGING

Utility functions in this group are imported by default, their tag name is `debug'. In the rare event when you need everything but debug functions you can say:

 use XAO::Utils qw(:all !:debug);

Here is the list of functions available:

dprint (@)

Prints all arguments just like normal "print" does but 1) it prints them to STDERR or uses the handler provided by set_logprint_handler() and 2) only if you called set_debug(1) somewhere above. Useful for printing various debug messages and then looking at them in "tail -f apache/logs/error_log".

Once you debugged your program you just turn off set_debug() somewhere at the top and all output goes away.

Example:

 @arr=parse_my_stuff();
 dprint "Got Array: ",join(",",@arr);

Note: Debugging status is global. In case of mod_perl environment with multiple sites under the same Apache server you enable or disable debugging for all sites at once.

eprint (@)

Prints all arguments to STDERR or using the handler provided by set_logprint_handler() like dprint() does but unconditionally. Great for reporting minor problems to the server log.

set_logprint_handler ($)

Installs a handler to be used by eprint() and dprint(). Useful when STDERR is not available or should not be used.

Example:

 my $s=Apache->request->server;
 XAO::Utils::set_logprint_handler(sub { $s->log_error($_[0] });
 dprint "Using Apache error logging";

get_debug ($)

Returns boolean value of the current state of the debug flag.

set_debug ($)

Turns debug flag on or off. The flag is global for all packages that use XAO::Utils!

Example:

 use XAO::Utils;

 XAO::Utils::set_debug(1);
 dprint "dprint will now work!";

HTML ENCODING

Utility functions in this group can be imported by using 'html' tag:

 use XAO::Utils qw(:html);

Here is the list of functions available:

t2hf ($)

Escapes text to be be included in HTML tags arguments. Can be used for XAO::Web object arguments as well.

 " ->> "

All symbols from 0x0 to 0x1f and from 0x80 to 0x9f are substituted with their codes in &#NNN; format.

t2hq ($)

Escapes text to be be included into URL parameters.

All symbols from 0x0 to 0x1f and from 0x80 to 0xff as well as the symbols from [&?<>"=%#+] are substituted to %XX hexadecimal codes interpreted by all standard CGI tools. The same conversion may be used for URLs themselves.

t2ht ($)

Escapes text to look the same in HTML.

 & ->> &
 > ->> >
 < ->> &lt;

ARGUMENTS HANDLING

Utility functions in this group are imported by default, their tag name is `args'. For example if you need everything but them you can say:

 use XAO::Utils qw(:all !:args);

Here is the list of functions available:

get_args ($)

Probably one of the most used functions throughout XAO tools. Understands arguments in the variety of formats and always returns a hash reference as the result.

Undrestands arrays, array references and hash references.

Should be used as follows:

 use XAO::Utils;

 sub my_method ($%) {
     my $self=shift;
     my $args=get_args(\@_);

     if($args->{mode} eq 'fubar') {
         ...
 }

Now my_method could be called in either way:

 $self->my_method(mode => 'fubar');

 $self->my_method( { mode => 'fubar' } );

Or even:

 $self->my_method( { mode => 'fubar' }, { submode => 'barfoo' });

 sub other_method ($%) {
     my $self=shift;
     my $args=get_args(\@_);

     if(some condition) {

        return $self->my_method($args);
     }
     ...

 sub debug_my_method ($%) {
     my $self=shift;
     dprint "will call my_method with our arguments";
     $self->my_method(@_);
 }

Note, that in the above examples you could also use "get_args(@_)" instead of "get_args(\@_)". That's fine and that will work, but slower.

merge_refs (@)

Combines together multiple hash references into one without altering original hashes. Can be used in situations when you want to pass along slightly modified hash reference like that:

 sub some_wrapper (%) {
     my $args=get_args(\@_);
     real_method(merge_args($args,{ objname => 'Fubar' }));
 }

Any number of hash references can be passed, first has lowest priority.

MATH

Utility functions in this group can be imported by using 'math' tag:

 use XAO::Utils qw(:math);

Here is the list of functions available:

fround ($$)

Rounds a floating point number according to the given precision.

Precision is given as X in 1/X, for instance to round to two digits after decimal point use precision 100.

Examples:

 fround(0.25,10)        => 0.3
 fround(0.01234,1000)   => 0.012

EXPORTS

eprint(), dprint().

AUTHORS

Copyright (c) 2000-2001 XAO Inc.

Andrew Maltsev <am@xao.com>, Bil Drury <bild@xao.com>.

SEE ALSO

Have a look at XAO::Base for overview.

cpanm XAO::Base

perl -MCPAN -e shell
install XAO::Base