NAME

Para::Frame::Utils - Utility functions for ParaFrame and applications

FUNCTIONS

in

  in($string, @list)

Returns true if $string is a part of @list using string comparsion

trim

  $string = trim(\$string)
  $string_ref = trim( $string)

Removes preceding and proceding whitespace. Also removes duplicate whitespace.

excerpt

  excerpt(\$string, $limit, $min

Creates and returns an excerpt

escape_js

  escape_js($string)

Creates a string that can be placed in '' in javascript code. Not to be confused with CGI/escape or CGI/escapeHTML.

This code uses \uxxxx format for escaping everything that isn't ascii.

Returns: The escaped string

make_passwd

  make_passwd( $length, $type)

  $length defaults to 8

Supported type easy (default) hard

Returns a string meant as a password

random

  random()
  random($max)

Creates a integer number $x: 1 <= $x < $max

throw

  throw( $error, $info, $output )
  throw( $error, $info )
  throw( $info )
  throw( $exception )
  throw( $error, \%args )

$error is the name of the exception. $info tells whats went wrong. $output shows where things get wrong, if its related to a place in a block of text.

Use your own or one of the standard exceptions from Para::Frame::Result::Part/Exceptions

Supported args are:

  info
  output
  error_template
  data

catch

  catch( $error )
  catch( $error, $output )
  catch( ['errtype1', 'errytpe2'], $output )

Returns (a true) Template::Exception object if $error.

But if the input is a Para::Frame::Result::Part, use that instead, since that is a cointainer of the error.

Appends $output to object.

If an arrayref of scalars is given, each scalar is compared to the type of the exception object found in $@. Returns the object if any of the types matches. Throws an exception if none of the types matches.

Example 1

  eval
  {
    ,,,
  };
  if( my $err = catch($@) )
  {
     die unless $err->type eq 'this';

     ... # Handle 'this' error
  }

Example 2

  eval
  {
    ,,,
  };
  if( my $err = catch(['this']) )
  {
     ... # Handle 'this' error
  }

Example 3

  eval
  {
    ,,,
  };
  if( my $err = catch(['this','that']) )
  {
     if( $err->type eq 'this' )
     {
        ... # Handle 'this' error
     }
     else
     {
        ... # Handle 'that' error
     }
  }

run_error_hooks

create_dir

  create_dir( $dir )

  create_dir( $dir, \%params )

Creates the directory, including parent directories.

All created dirs is chmod and chgrp to ritframe standard.

Passes %params to create_dir and chmod_dir.

create_file

  create_file( $filename )
  create_file( $filename, $content )

Creates the file, including parent directories.

All created files is chmod and chgrp to ritframe standard.

chmod_tree

  chmod_tree( $dir );

  chmod_tree( $dir, \%params );

Chmod and chgrp all files in dir tree to ritframe standard.

Passes %params to /chmod_file.

chmod_file

  chmod_file( $filename, $mode, \%params )
  chmod_file( $filename, \%params )

Chgrp file according to Para::Frame/paraframe_group.

If $mode isn't given, falls back on %params.

Using perlfunc/umask for setting all modes. That umask is set in Para::Frame/configure using Para::Frame/umask.

That umask can be overridden for this file by param umask.

The mode for dirs will be the first defined of $mode or param dirmode of param mode or 02777.

The mode for nondir files will be the first defined of $mode or param filemode or param mode or 0666.

For example, with a default umask of 07 and a default dirmode of 02777, the dir will be set to mode 02770 that would be read/write access for user and group and no access for anyone else.

If we fail to change the mode or group (because of permission problems) we will throw an exception with an analysis of the problem and a suggested solution.

chmod_dir

  chmod_dir( $dir )

  chmod_dir( $dir, $mode )

  chmod_dir( $dir, \%params  )

  chmod_dir( $dir, $mode, \%params )

Does nothing if param do_not_chmod_dir is true.

$mode, if existing, is copied top param dirmode.

Calls /chmod_file with the given $dir and %params.

package_to_module

  package_to_module( $package )

Returns the correspondoing praxis filename of the module.

module_to_package

  module_to_package( $module )

Returns the corresponding praxis package name for the filename.

uri_path

  uri_path()

  uri_path($url)

Returns the absolute path for the $url. Defaults to the current template.

uri

  uri()

  uri( $url )

  uri( $url, \%params )

Creates a URL with query parameters separated by '&'.

Relative URLs will be expanded relative the current Para::Frame::Request/page.

$url should not include a '?'.

$url defaults to Para::Frame::Site/home.

dirsteps

  dirsteps( $path, $base )

$base is the website URL home path.

$base defaults to ''.

Returns a list with all dirs from $path to the dir before $base.

$path must both end and begin with /.

$base must not end with /.

Example: dirsteps('/one/two/three/') returns ('/one/two/three/', '/one/two/', '/one/').

Example: dirsteps('/one/two/three/', '/one') returns ('/one/two/three/', '/one/two/', '/one/').

Example: dirsteps('/one/two/three/', '/one/two') returns ('/one/two/three/', '/one/two/').

compile

passwd_crypt

  passwd_crypt( $password )

Returns an encrypted version of the given string, uses the current clients C-network IP as salt. The encrypted password will be diffrent if the client comes from a diffrent net or subnet.

If the page is sent through a proxy, the original address may be the first in a comma-separated list given in HTTP_X_FORWARDED_FOR. But that part of the header may be faked. If we are going to use it for authentication, we have to establish a trust of the proxy given by REMOTE_ADDR, as well as all other proxies listed in HTTP_X_FORWARDED_FOR.

HTTP_CLIENT_IP should be used rather than REMOTE_ADDR, if availible.

deunicode

  deunicode( $text )

Checks the text. If it's in UTF8, converts it to ISO-8859-1.

Handles UTF8 mixed in with ISO-8859-1

Note: Do not send in objects.

returns: a string in Latin-1

repair_utf8

  repair_utf8( \ $text )

paraframe_dbm_open

  paraframe_dbm_open( $dbfile )

REturns a referens to a hash tied to database file.

Uses BerkeleyDB/BerkeleyDB::Hash.

Creates the file if it doesn't exist.

elapsed_time

  elapsed_time( $duration )

TODO: Move to Para::Frame::Time

Returns an informal string representation of the duration.

$duration can be the number of seconds or a DateTime::Duration object.

idn_decode

  idn_decode( $domain )

Decode international domain names with punycode.

Returns the decoded domain as a string.

idn_encode

  idn_encode( $domain )

Encode international domain names with punycode.

Returns the encoded domain as a string.

store_params

  store_params()

Returns a hash with all the CGI query params.

clear_params

  cleare_params( @list )

  clear_params

Clears the CGI query params given in list, or all params if no list given.

add_params

  add_params( \%saved )

Adds to the CGI query with the params given in the hashref.

restore_params

  restore_params( \%saved )

Remove all the CGI query params and replace them with those in the hashref given.

debug

  debug( $level, $message, $ident_delta )

  debug( $level, $message )

  debug( $message )

  debug( $ident_delta )

  $level = debug()

If no params are given, just returns the current debug level.

$level specifies the minimum debug level required to display this debug message. Default is 0.

The $message is sent to STDERR.

$ident_delta changes the current identation level. Each level equates to a space prefixed the message. The $ident_delta can be a positive or negative integer.

reset_hashref

  reset_hashref( $hashref, \%params )

Removes all the data from $hashref and copies all %params to it.

The point is to keep the thingy.

Returns the hashref.

timediff

  timediff( $label )

Returns the time since last usage of timediff, prefixed with the param, as a text string.

fqdn

  fqdn()

Gets the FQDN (fully qualified domain name). That is the hostname followed by the domain name. Tha availible perl modules fails for me. ( Sys::Hostname and Net::Domain )

retrieve_from_url

    retrieve_from_url( $url )

Gets the page/file in a fork.

Returns the page content on success or throws an action exception with an explanation.

get_from_fork

  get_from_fork( \&coderef )

Run given coderef in a fork an retrieve the results.

validate

  validate( $value, $type )

TODO: Not implemented...

Validate that a value is of the specified type

Returns true if validate and false otherwise

datadump

  datadump( $value, $maxdepth )

client_send

  client_send($client, \$data, \%args )

  client_send($client, $data, \%args )

Supported args are:

  req

It will try many times sending part by part.

If req is given; for each chunk of data that couldn't be sent, we will see if the req has been cancelled and then yield, by doing a Para::Frame::Request/yield. After that, we will try to send the chunk again.

Tries 100 times per chunk.

Returns: The number of characters sent. (That may be UTF8 characters.)

client_str

validate_utf8

  validate_utf8(\$data)

Returns: a string with info about the utf8-status of the string

parse_perlstruct

Recursive array-refs implemented

TODO: hashrefs

SEE ALSO

Para::Frame