source: sipes/modules_contrib/token/API.txt @ c43ea01

Overview
========
In many cases, it's useful to allow users to define patterns or large
chunks of text that contain programmatically derived values. For example,
form email messages addressed to a given user, or url path aliases
containing the title of a given node. Both examples require bits of data
that vary each time the text is generated -- node titles, user ids, and
so on. Rather than forcing users to embed ugly snippets of PHP, or creating
elaborate and bizarre UIs for configuring the patterns via the browser,
it's most useful to give users a set of 'placeholder' tokens to place in
their text.

Token.module provides a shared API for exposing and using placeholder
tokens and their appropriate replacement values. It does nothing *by
itself* -- other modules can use it to avoid reinventing the wheel.

Using Token Replacement
=======================
To apply token replacement to a chunk of text, you have two options. The
first, and simplest, is:

  token_replace($original, $type = 'global', $object = NULL,
                $leading = '[', $trailing = ']')

$original is the source text to perform substitutions on: it can be either
a simple string, or an array of multiple strings.

$type and $object are to be used when performing substitution based on a
particular Drupal object. Replacing tokens in an email with values from
a particular user account, or replacing tokens in a path alias pattern with
values from the node being aliased, are two examples.

$type should contain the general object type (node, comment, user, etc.)
while $object should contain the object itself.

$leading and $trailing can be used to override the default token style.
For example, to replace tokens using %this style, pass in '%' and '' for
the $leading and $trailing values. Note that passing in a leading but NOT
trailing value can lead to false positives if two tokens are named in a
similar fashion (%node_term and %node_term_id, for example).



Altering The Replacement Values
===============================
If your module needs to perform additional cleanup work on the replacement
values before doing the actual substitutions (cleaning replacement values
to make them appropriate for path aliasing, truncating them to a particular
length, etc.) you can manually retrieve the list of tokens and replacement
values, then call str_replace() yourself.

  token_get_values($type = 'global', $object = NULL)

Pass in the $type and $object as you would with the simpler token_replace()
function. The return value will be an object containing one array of tokens
and one array of values as in this example:

stdClass Object {
  [tokens] => array(
    [0] => mytoken1,
    [1] => mytoken2
  ),
  [values] => array(
    [0] => value1,
    [1] => value2,
  )
}



Providing Placeholder Tokens
============================
Token.module provides a small set of default placeholders for global values
like the name of the currently logged in user, the site's URL, and so on.
Any module can provide additional tokens by implementing two hooks.

Security note: For tokens which include user input, users and modules
expect to see both a ['token-name'] and a ['token-name-raw'] value.


hook_token_values($type, $object = NULL)
========================================
This function should return a keyed array of placeholders, and their
replacement values. $type contains the current context -- 'node', 'user',
'global', etc. $object contains the specific node, user, etc. that
should be used as the basis for the replacements. *Only* generate and
return replacement tokens when $type is something that your module can
really deal with. That helps keep things speedy and avoid needlessly
searching for jillions of replacement tokens. The $options array can 
contain additional options (exact use is dynamic and not easily documented).

For example:

function my_user_token_values($type, $object = NULL, $options = array()) {
  if ($type == 'user') {
    $user = $object;
    $tokens['name']      = $user->name;
    $tokens['mail']      = $user->mail;
    return $tokens;
  }
}


hook_token_list($type = 'all')
==============================
This function is used to provide help and inline documentation for all
of the possible replacement tokens. 

As with hook_token_values, $type indicates the context that token help
is being generated for. Unlike hook_token_values however, you should
show ALL tokens at the same time if $type is 'all'. As such, the help
text should be keyed by the $type context your module will use when
doing the actual replacements. For example:

function my_user_token_list($type = 'all') {
  if ($type == 'user' || $type == 'all') {
    $tokens['user']['name']      = t("The user's name");
    $tokens['user']['mail']      = t("The user's email address");
    return $tokens;
  }
}

Examples of more elaborate token replacement setups can be found in the
token_node.inc file that's bundled with token.module.

Security Note
========
If  use any of the tokens in the ['raw'] sub-array then please note that these 
are unfiltered values which could conceivably contain XSS attacks or other 
malicious data.  Your module should then provide it's own filtering to ensure the 
safety of site users.