ExSite::Misc -- miscellaneous utility functions needed by ExSite::

This package contains routines and functions that have no dependence on other ExSite code.

Hash Encoding Tools

For purposes of decoding input, these tools are deprecated. See ExSite::Input for better input management. These tools may still be used for general-purpose hash encoding, however.

EncodeHash(%hash)
Converts a hash to a URL-encoded string. If the hash contains array references, those are converted to comma-delimited lists of values. If the hash contains hash references, those are recursively converted using &EncodeHash.

DecodeString($string)
Converts a URL-encoded string to a hash. DecodeString can also be used to parse any string with key=value pairs delimited by character X, if X is supplied as the 2nd argument.

Multiply-defined keys have their values appended to each other, separated by the value of $multi_sep (``; '' by default).

DecodeQuery()
Decodes the QUERY_STRING. (Passes $ENV{QUERY_STRING} through &DecodeString().)

DecodePost()
Deprecated - use ExSite::Input instead.

Decode the POST data. For URL-encoded form data, passes the data though &DecodeString(). Multipart-encoded data is more complex (and required for file uploads); in that case, the CGI:: package is used to parse the data.

DecodeInput()
Deprecated - use ExSite::Input instead.

Decodes the input to the page. Decodes either the POST or QUERY data, depending on the REQUEST_METHOD.

Datahash Array Conversion Functions:

columnwise($ref)
Convert a list of datahashes into a hash of datalists.

input: an array of hash references with identical keys.

output: a hash of arrays, indexed by the same keys. For instance, ( { a=>1, b=>2 }, { a=>3, b=>4 }, { a=>5, b=>6 } ) becomes ( a => [1,3,5], b => [2,4,6] )

keywise($key,$ref)
Convert a list of datahashes into a hash of datahashes.

input: a hash key to index on, and an array of hash references

output: a hash of hashes, indexed by one of the keys. It is assumed that the value associated with this key is unique across all the hashes. If not, the last such key is used.

For example, taking ( { a=>1, b=>2 }, { a=>3, b=>4}, { a=>5, b=>6 } ) and indexing it by key ``a'', gives { 1=>{a=>1,b=>2}, 3=>{a=>3,b=>4 }.

Text Encoding/Decoding Functions

url_escape($text,$escape_chars)
Uses URL-escaping conventions to modify $text by escaping the characters in $escape_chars. If $escape_chars is not given, escapes these characters by default:
    %+ &@"?#

url_unescape($text)
Removes URL-escape codes from $text, restoring the plaintext.

html_escape($text,$escape_chars,$use_wierd_amp_esc)
Uses HTML-escaping conventions to modify $text by escaping the characters in $escape_chars. If $escape_chars is not given, the following characters are escaped by default:
    &<>"

$use_wierd_amp_esc is a flag, which if true, causes ``&'' to be escaped with a non-standard escape code ``<!amp>''. This is sometimes necessary to prevent the HTML editor from mangling our escape codes, as some client browsers will rewrite the HTML against our wishes.

html_unescape($text,$escape_chars,$use_wierd_amp_esc)
This reverses the escape codes inserted by html_escape().

safetext($text)
Converts arbitrary data into a string consisting only of the characters a-z, A-Z, 0-9, and _. Such strings are safe(er) for use as variable names or field IDs.

unsafetext($text)
Converts a safe string back to its original representation.

General Text-Processing Functions

substitute($subhash,$startmark,$endmark)
Performs simple text substitutions.

Replaces marker tags such as ``[[tag]]'' with the value in $subhash{"tag"}. Does so for all such tags in the text. Tags may contain word characters only (alphanumeric plus _).

$text
string to perform substitutions on

$subhash
hash of marker keys=>values

$startmark
substring denoting the start of a marker tag (``[['' default)

$endmark
substring denoting the end of a marker tag (``]]'' default)

html_to_plaintext($html)
Converts HTML to plaintext, simplistically. It does not attempt to preserve any formatting other than linebreaks.

randtext($len,$src)
Generates strings of random text. Generated strings will be of length $len, and composed of characters from $src. Both parameters are optional. Default length is 7-10 characters, and the default source string includes most of the printable ASCII character set.

This is useful as a secure pasword or passkey generator.

Miscellaneous other functions...

MimeType($filename)
Guess the MIME type of a file. This routine uses the filename (in particular, the suffix) to guess the MIME type of the file.

MimeToFile($mimetype)
Guess the file extension for a mime type. The routine returns a standard/common file extension for files with the given mime type.

ShowHash()
Display a hash's contents in HTML format. A hash or hash reference may be passed to this routine; a block of HTML is returned.

get_file($opt)
Return contents of a file. $opt is a hash reference, which presently only accepts one key:
imgpath
adds this path value in front of any IMG SRC= attributes found in the file. (Presumably the file is HTML.)

relink(%param)
Generates a recursive link back to same URL, with modified query parameters.

To set a new parameter, give the parameter a value in %param. To clear a parameter, set its value in %param to undef.

relink() returns the new URL to link to.

To link back to the same URL, use &relink();, not &relink;.

See also Modules::BaseDCD::link(), which is better for relinking into a dynamic content module.