<?php
// $Id: helpers.module,v 1.18.4.8 2008-02-13 15:33:37 nancyw Exp $

/**
 * @file
 * This is a library of useful functions and methods.
 * please insert the link if you have a patch for core to introduce a function from this lib to core.
 */

/**
 * Implementation of hook_help().
 */
function helpers_help($section) {
  switch ($section) {
    case 'admin/modules#description':
      return t('A development library. Contains numerous useful functions and methods.');
  }
}

/**
 * implementation of hook_menu()
 */
function helpers_menu($may_cache) {
  if ($may_cache) {
    $items[] = array(
      'path' => 'helpers/void',
      'type' => MENU_CALLBACK,
      'callback' => 'void_page',
      'access' => TRUE,
    );
  }
  return $items;
}

/**
 * String and array functions.
 */

/**
 * Test if a string is empty, or equals another string. If so, return a themed
 *  empty placeholder. Else return the input string.
 * @param $string: The string we want to find out if its empty;
 * @param $test: Optionally you can test against this string; In case you want to redefine "empty".
 */
function test_empty_string($string, $test = '') {
  if ($string == $test) {
    return theme('empty_placeholder');
  }
  return $string;
}

/**
 * Formats a chopped off string of a certain length. Calls a theme function to
 * do the actual formatting. By default it will return strings in the form of
 * verylongstringwithsomecoo...
 * @param $string the original string.
 * @param $length Optional provide a length for the string
 * @param $count_addition Optional provide an amount for the additional
 * charachters. Giving this parameter, for example a value of 5, you will
 * receive a shortened string in the form of verylongstringwithsomec.....
 */
function format_shorten_string($string, $length = 15, $count_addition = 3) {
  if (drupal_strlen($string) > $length) {
    $out = theme('shorten_string', drupal_substr($string, 0, ($length - $count_addition)), $string, $count_addition);
  }
  else {
    $out = $string;
  }

  return $out;
}

/*
 * Function to parse tags (HTML) string into an array suitable for drupal_attributes.
 * @param $tags
 *   string containing HTML to be parsed.
 * @return
 *   array with attribute as key and value as value.
 */
function drupal_parse_html($tags) {
  $attrs = array();
  $arr = explode(' ', $tags);
  foreach ($arr as $tag) {
    if (!empty($tag)) { // Ignore extra blanks.
      $key_len = strpos($tag, '=');
      $attrs[substr($tag, 0, $key_len)] = trim(substr($tag, $key_len + 1), '\'"');
    }
  }
  return $attrs;
}

/*
 * Function to display an array.
 * @param $array
 *   array to be displayed.
 * @param $title
 *   heading to be displayed.
 * @return
 *   HTML string.
 */
function show_array($array, $title = null) {
  $output = null;
  if ($title) {
    $output .= theme('heading', $title, 2, array('class' => 'show_array'));
  }
  foreach($array as $key => $value) {
    $output .= theme('paragraph', $key .' => '. (is_string($value) ? $value : print_r($value, true)), array('class' => 'show_array'));
  }
  return $output;
}

/*
 * Function to display an object.
 * @param $array
 *   array to be displayed.
 * @param $title
 *   heading to be displayed. The object class will be appended.
 * @return
 *   HTML string.
 */
function show_object($object, $title = null) {
  $output = show_array((array) $object, $title .' ('. get_class($object) .')');
  return $output;
}

/**
 * Page functions. Render pages
 */

/**
 * Void. Render nothing. A blank page.
 */
function void_page() {
  return '';
}

/**
 * Common API functions
 */
/**
 * Get a block as object prepared to use in the theme_block function
 * @param $name the modulename (block name) to get the block from.
 * @param $delta the block delta. Each block in each module has a unique delta value. A number indicating that block.
 */
function get_block($name, $delta = 0) {
  if ($result = module_invoke($name, 'block', 'view', $delta)) {
    $block = (object)$result;
    $block->module = $name;
    $block->delta = $delta;
    return $block;
  }
}

/**
 * Find out if a user has a certain role or roles.
 * @param $user a user object. Must only contain the $user->roles array.
 * @param $roles an array of roles to check for.
 * @return TRUE if the user has a role you checked for, FALSE if the user is not
 * within any of the requested roles.
 */
function user_has_role($user, $roles) {
  foreach ($roles as $rid) {
    if (in_array($rid, array_keys($user->roles))) {
      return TRUE;
    }
  }
  return FALSE;
}