NAME

UtilFunctions - Additional shared functions

SYNOPSIS

This module provides an interface to utility type functions that are used by all or some of the other Luci library modules. These functions are grouped together here for easy usage and maintainabitlity instead of duplicated in each module that requires the functionality.

Even though these are only utility functions, a utility object must be created first which stores data that is required for some of the fuctions to operate. This is done because a calling module might not have access to the required information to pass into the utility function.

USAGE

First, a UtilFunctions object must be created to store the needed member data required by the functions. Create the object while providing a reference to the system configuration as the only constructor parameter:

 my $utils = UtilFunctions->new($config);

Then, give the object some addtional data to work with:

 # notice that @allowlist, @denylist and @list_of_file_extensions are
 # lists/arrays containing the allowed/deny urls/file extensions
 # that are normally grabbed from the config.
 $utils->{_allowlist} = @allowlist;
 $utils->{_denylist} = @denylist;
 $utils->{_extensions} = @list_of_file_extensions;

Next call a member function of this $utils object like so:

 if( $utils->is_parsable("http*://luci.sourceforge.net/thepage.html") ){ 
        echo "We can use luci to simplify this page!!!"; 
 }

DESCRIPTION

is_allowed

Determines if the given URL is allowed wrt the list of allow/deny lists (defined in the _(allow|deny)list member variables.)

 is_allowed(string url)

returns true if url is allowed, false otherwise.

example:

 if( $utils->is_allowed("http*://www.example.com") ){
        echo "We might be able to parse this page!";
 } else {
        echo "Outsider!";
 }

is_internal

Determines if the given URL is an internal page as compared to the app_root_url configuration setting

note: www.yourdomain.com and yourdomain.com differ, and so will not be flagged as internal

 is_internal(string url)

returns true if url is internal, false otherwise.

example:

 if( $utils->is_internal("http*://www.example.com") ){
        echo "is internal";
 } else {
        echo "is external";
 }

is_parsable

Determines if the given URL is a document that we are able to parse (parsable extensions are defined in the _extensions member variable.)

 is_parsable(string url)

returns true if url is parsable, false otherwise.

example:

 if( $utils->is_parsable("http*://www.example.com/dir/oops.pdf") ){
         echo "Luci is capable of parsing this page!";
 } else {
         echo "What a farce, we can't parse!";
 }

create_app_url

Takes a URL and provides a Luci parseable link:

 create_app_url(string document_url, string url_from_html);
 # document_url = the URL of the document that contains the link
 # url_from_html = the link URL as presented in the document

returns the url to be displayed in the browser

example:

 my $url = $utils->create_app_url("http*://www.example.com/dir/test.html", 
                                  "../docs/new/report.html");
 # if example.com is internal, $url will hold
 # [luci_script_url]http*://www.example.com/docs/new/report.html
 # if example.com is not internal, $url will hold
 # http*://www.example.com/docs/new/report.html

abs_url

Given an absolute URL, abs_url transforms a potentially relative URL into an absolute URL with respect to the given known absolute URL. Keep in mind that the potentially relative URL may actually be absolute, in which case it would remain unchanged.

 abs_url(string absolute_url, string url_to_resolve)

returns the absolute version of url_to_resolve

example:

 $url = $utils->abs_url("http*://www.example.com/dir/", "test/script.cgi");
 # $url contains http*://www.example.com/dir/test/script.cgi
 $url = $utils->abs_url("http*://www.example.com/dir/",
                        "http*://web.test.com/sendmoney.html");
 # $url contains http*://web.test.com/sendmoney.html

error

This is the main error reporting fuction. It should be noted that this function is not a member function, and should not be used by calling it with a UtilFunctions object. error puts the error message into a standard Luci error html template that can be displayed to the user.

 error(hashref config, string error_msg [, integer error_code])
 # config is a hash reference to the configuration variables for Luci
 # (optional) error_code is an integer representing a fatal error

returns the html that contains the error message and should be displayed to the user.

or

dies with provided error_msg

example:

 # $config is a hash reference to a previously created hash of
 # configuration variables
 $html = UtilFunctions::error($config, "You can't view this page.");
 echo $html;
 UtilFunctions::error($config, "bad url sructure", 12);
 # this will kill the application with fatal error 12

qmeta

Version of quotemeta that ignores escape of specific characters that are required to perform the regex as is necessary on allow/deny urls.

example:

 	# will return url as http\:\/\/www\.yourdomain\.com(\/.*?|)
 	$escaped = qmeta('http://www.yourdomain.com/*>');

LUCI DOCUMENTATION

See Luci Documentation for more information.

AUTHORS