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
 " ->> \"
 \ ->> \\

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

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