<?php
// $Id: token.module,v 1.5.2.2 2007-01-11 17:35:07 eaton Exp $

include_once('token_node.inc');
include_once('token_user.inc');

/**
 * Return the value of $original, with all instances of placeholder
 * tokens replaced by their proper values.
 *
 * @param original
 *  A string, or an array of strings, to perform token substitutions
 *  on.
 * @param type
 *   A flag indicating the class of substitution tokens to use. If an
 *   object is passed in the second param, 'type' should contain the
 *   object's type. For example, 'node', 'comment', or 'user'. If no
 *   type is specified, only 'global' site-wide substitution tokens are
 *   built.
 * @param object
 *   Optionally, the object to use for building substitution values.
 *   A node, comment, user, etc.
 * @param leading
 *    Character(s) to prepend to the token key before searching for
 *    matches. Defaults to an open-bracket.
 * @param trailing
 *    Character(s) to append to the token key before searching for
 *    matches. Defaults to a close-bracket.
 * @return The modified version of $original, with all substitutions
 *   made.
 **/
function token_replace($original, $type = 'global', $object = NULL, $leading = '[', $trailing = ']') {
  $full = token_get_values($type, $object);
  $tokens = token_prepare_tokens($full->tokens, $leading, $trailing);
  $values = $full->values;
  $result = str_replace($tokens, $values, $original);
  return $result;
}

/**
 * Return a list of valid substitution tokens and their values for
 * the specified type.
 *
 * @param type
 *   A flag indicating the class of substitution tokens to use. If an
 *   object is passed in the second param, 'type' should contain the
 *   object's type. For example, 'node', 'comment', or 'user'. If no
 *   type is specified, only 'global' site-wide substitution tokens are
 *   built.
 * @param object
 *   Optionally, the object to use for building substitution values.
 *   A node, comment, user, etc.
 * @return
 *   A keyed array containing the substitution tokens and the substition
 *   values for the passed-in type and object.
 */
function token_get_values($type = 'global', $object = NULL) {
  static $tokens;

  if (!isset($tokens)) {
    $tokens = array();
  }

  $id = _token_get_id($type, $object);
  if (isset($tokens[$type][$id])) {
    $tmp_tokens = $tokens[$type][$id];
  }
  else {
    $tmp_tokens = module_invoke_all('token_values', $type, $object);
    $tokens[$type][$id] = $tmp_tokens;
  }

  // Special-case global tokens, as we always want to be able to process
  // those substitutions.
  if (!isset($tokens['global']['default'])) {
    $tokens['global']['default'] = module_invoke_all('token_values', 'global');
  }

  $all = array_merge($tokens['global']['default'], $tokens[$type][$id]);
  $result->tokens = array_keys($all);
  $result->values = array_values($all);

  return $result;
}

/**
 * For a given context, builds a formatted list of tokens and descriptions
 * of their replacement values.
 *
 * @param type
 *    The token types to display documentation for. Defaults to 'all'.
 * @return An HTML table containing the formatting docs.
 **/
function theme_token_help($type = 'all') {
  $full_list = module_invoke_all('token_list', $type);
  
  $headers = array(t('Token'), t('Replacement value'));
  $rows = array();
  foreach ($full_list as $key => $category) {
    $rows[] = array(array('data' => drupal_ucfirst($key) . ' ' . t('tokens'), 'class' => 'region', 'colspan' => 2));
    foreach ($category as $token => $description) {
      $row = array();
      $row[] = $token;
      $row[] = $description;
      $rows[] = $row;
    }
  }

  $output = theme('table', $headers, $rows, array('class' => 'description'));
  return $output;
}

/**
 * Sample implementation of hook_token_values(). 
 *
 * @param type
 *   A flag indicating the class of substitution tokens to use. If an
 *   object is passed in the second param, 'type' should contain the
 *   object's type. For example, 'node', 'comment', or 'user'. If your
 *   implemention of the hook inserts globally applicable tokens that
 *   do not depend on a particular object, it should only return values
 *   when $type is 'global'.
 * @param object
 *   Optionally, the object to use for building substitution values.
 *   A node, comment, user, etc.
 * @return
 *   A keyed array containing the substitution tokens and the substition
 *   values for the passed-in type and object.
 */
function token_token_values($type, $object = NULL) {
  global $user;
  global $base_url;

  switch ($type) {
    case 'global':
      $values['user-name']    = $user->uid ? $user->name : variable_get('anonymous', t('Anonymous'));
      $values['user-id']      = $user->uid ? $user->uid : 0;
      $values['user-mail']    = $user->uid ? $user->mail : '';
      $values['site-url']     = $base_url;
      $values['site-name']    = variable_get('site_name', t('Drupal'));
      $values['site-slogan']  = variable_get('site_slogan', '');
      $values['site-mail']    = variable_get('site_mail', '');
      break;
  }
  return $values;
}

/**
 * Sample implementation of hook_token_list(). Documents the individual
 * tokens handled by your module.
 *
 * @param type
 *   A flag indicating the class of substitution tokens to return
 *   information on. If this is set to 'all', a complete list is being
 *   built and your module should return its full list, regardless of
 *   type. Global tokens should always be returned, regardless of the
 *   $type passed in.
 * @return
 *   A keyed array listing the substitution tokens. Elements should be
 *   in the form of: $list[$type][$token] = $description
 */
function token_token_list($type = 'all') {
  $tokens['global']['user-name']    = t('The name of the currently logged in user.');
  $tokens['global']['user-id']      = t('The user ID of the currently logged in user.');
  $tokens['global']['user-mail']    = t('The email address of the currently logged in user.');
  $tokens['global']['site-url']     = t('The url of the current Drupal website.');
  $tokens['global']['site-name']    = t('The name of the current Drupal website.');
  $tokens['global']['site-slogan']  = t('The slogan of the current Drupal website.');
  $tokens['global']['site-mail']    = t('The contact email address for the current Drupal website.');
  return $tokens;
}

/**
 * A helper function that transforms all the elements of an
 * array. Used to change the delimiter style from brackets to
 * percent symbols etc.
 *
 * @param tokens
 *    The array of tokens keys with no delimiting chacaters
 * @param leading
 *    Character(s) to prepend to the token key before searching for
 *    matches. Defaults to an open-bracket.
 * @param trailing
 *    Character(s) to append to the token key before searching for
 *    matches. Defaults to a close-bracket.
 *  @return
 *    The array of token keys, each wrapped in the specified
 *    delimiter style.
 */
function token_prepare_tokens($tokens = array(), $leading = '[', $trailing = ']') {
  foreach ($tokens as $key => $value) {
    $tokens[$key] = $leading . $value . $trailing;
  }
  return $tokens;
}

// Internal utility function used for static caching.
function _token_get_id($type = 'global', $object = NULL) {
  if (!isset($object)) {
    return "default";
  }
  switch ($type) {
    case 'node':
      return $object->nid;
    case 'comment':
      return $object->cid;
    case 'user':
      return $user->uid;
    default:
      return md5(serialize($object));
  }
}