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.

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.

The generated ID will never start with a digit!

The default generated key length is 8. This can be changed by supplying an optional argument -- generate_key(20) for example.

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

Unicode is encoded into UTF-8 (unless a different encoding is specified in the second argument).

t2ht ($)

Escapes text to look the same in HTML.

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

t2hj ($)

Escapes text to look the same in JavaScript.

' ->> \u0027
" ->> \"
\ ->> \\
< ->> \u003c
> ->> \u003e

Single quote is escaped into a hex code because that is acceptable in both Javascript and JSON strings, whereas \' is not valid in JSON.

Angle brackets are escaped because otherwise a value of </script> inside a field would close the outer script tag even though it's encountered in the middle of a literal.

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