modules/drutex/drutex.module

<?php
// $Id: drutex.module,v 1.22 2007/09/09 18:57:38 darthsteven Exp $

/**
 * @file
 * DruTeX core functions and interaction interface with Drupal.
 */

/**
 * Implementation of hook_filter().
 */
function drutex_filter($op, $delta = 0, $format = -1, $text = '') {
  switch ($op) {
    case 'list':
      return array(0 => t('DruTeX'));

    case 'description':
      return t('Allows users to render LaTeX/TeX in many different ways.');

    case "process":
      return drutex_node2html($text, $format);

    case 'settings':
      return _drutex_filter_settings($format);

    default:
      return $text;
  }
}

/**
 * Implementation of hook_menu().
 */
function drutex_menu($may_cache) {
  $items = array();

  if ($may_cache) {
    if (drutex_submodule_is_active('remote')) {
      $items[] = array(
        'path' => 'drutex/remote',
        'title' => 'Drutex Remote Rendering',
        'access'=> TRUE,
        'callback' => 'drutex_remote_do_render',
        'type' => MENU_CALLBACK,
        );
  
      $items[] = array(
        'path' => 'admin/settings/drutex/remote',
        'title' => 'DruTeX Settings',
        'description' => 'Adjusts the settings for the remote LaTeX rendering interface',
        'callback' => 'drupal_get_form',
        'access' => user_access('administer site configuration'),
        'callback arguments' => array('drutex_remote_settings'),
        );
    }
  }
  else {
    if (drutex_submodule_is_active('pdf')) {
      $items[] = array(
        'path' => 'drutex/pdf',
        'title' => t('node2pdf'),
        'callback' => 'drutex_node2pdf_wrapper',
        'access' => user_access('access pdf files'),
        'type' => MENU_CALLBACK);

      $items[] = array(
        'path' => 'drutex/latex',
        'title' => t('node2latex'),
        'callback' => 'drutex_node2latex_wrapper',
        'access' => user_access('access latex source'),
        'type' => MENU_CALLBACK);
    }
  }


  drutex_set_stylesheet();

  return $items;
}

/**
 * Extended variable-get function.
 *
 * drutex_var_get('a_b_c') calls variable_get($ask, drutex_var_default($ask))
 * with $ask = 'a_b_c', $ask = 'a_b', $ask = 'a' ... until a return value != null is found.
 *
 * @param $ask
 *   The query string, e.g. "drutex_dpi_$format".
 */
function drutex_var_get($ask) {
  while ($ask) {
    $res = variable_get($ask, drutex_var_default($ask));

    if (!is_null($res)) {
      /* return drutex dirs and urls always without trailing slash */
      if (strpos($ask, 'drutex_dir') === 0 || strpos($ask, 'drutex_url') === 0) {
        return rtrim($res, '/');
      }
      else {
        return $res;
      }
    }

    $ask = substr($ask, 0, strrpos($ask, '_'));
  }

  return NULL;
}


/**
 * DruTeX default values.
 *
 * @param $ask
 *   The query string, e.g. "drutex_dpi".
 */
function drutex_var_default($ask) {
  /* Defaults Array */
  static $D = array();

  if (empty($D)) {
    $D['drutex'] = NULL;

    /* Directories */
    $D['drutex_dir']                  = dirname(__FILE__);
    $D['drutex_dir_images']           = variable_get('file_directory_path', 'files') .'/tex';
    $D['drutex_dir_temporary']        = variable_get('file_directory_temp', FILE_DIRECTORY_TEMP);
    $D['drutex_url_images']           = variable_get('file_directory_path', 'files') .'/tex';

    /* other */
    $D['drutex_dpi'] = '107';
    $D['drutex_imagetype'] = 'png';
    $D['drutex_stylesheet'] = drupal_get_path('module', 'drutex') .'/drutex.css';
    $D['drutex_conversion'] = 'dvipng';

    $D = array_merge($D, drutex_submodule_invoke_all('defaults'));
  }

  if (isset($D[$ask])) {
    return $D[$ask];
  }
  else {
    return NULL;
  }
}

/**
 * Filter-settings page.
 */
function _drutex_filter_settings($format = -1) {
  $form['drutex_submodules'] = array(
    '#type' => 'fieldset',
    '#title' => t('DruTeX :: Submodules'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE
  );

  $submodule_objects = drutex_submodule_objects($format);
  usort($submodule_objects, '_drutex_weight_sort_cmp');

  /* list all submodules that can be (de)activated */
  foreach ($submodule_objects as $obj) {
    if ($obj->toggle) {
      $form['drutex_submodules']["drutex_{$obj->submodule}_active_{$format}"] = array(
        '#type' => 'checkbox',
        '#title' => $obj->title,
        '#default_value' => $obj->active,
        '#description' => $obj->description
      );
    }
  }

  /* try to create the image directory and set the rights
     if not done already
  */

  $image_dir = drutex_var_get("drutex_dir_images_$format");

  if (!is_writable($image_dir)) {
    if (file_exists($image_dir)) {
      chmod($image_dir, 0777);
    }
    else {
      mkdir($image_dir);
    }
  }

  /* global settings
     that means: settings all submodules can share
     but it remains filter specific
  */

  $form['drutex_base'] = array(
    '#type' => 'fieldset',
    '#title' => t('DruTeX :: Base Settings'),
    '#collapsible' => TRUE,
    '#collapsed' => FALSE
  );

  /* determine whether temporary dir is writeable */
  $is_writable = is_writable(drutex_var_get("drutex_dir_temporary_$format"));

  $form['drutex_base']["drutex_dir_temporary_$format"] = array(
    '#type' => 'textfield',
    '#title' => t('Temporary directory'),
    '#size' => 80,
    '#maxlength' => 100,
    '#default_value' => drutex_var_get("drutex_dir_temporary_$format"),
    '#description' => t('Directory for temporaray actions. Has to be writable by apache.'),
    '#attributes' => $is_writable ? array() : array('style' => 'border-color:red')
  );

  /* determine whether image dir is writeable */
  $is_writable = is_writable(drutex_var_get("drutex_dir_images_$format"));

  $form['drutex_base']["drutex_dir_images_$format"] = array(
    '#type' => 'textfield',
    '#title' => t('Image directory'),
    '#size' => 80,
    '#maxlength' => 100,
    '#default_value' => drutex_var_get("drutex_dir_images_$format"),
    '#description' => t('Directory where images are saved. Has to be writable by apache.'),
    '#attributes' => $is_writable ? array() : array('style' => 'border-color:red')
  );


  $form['drutex_base']["drutex_url_images_$format"] = array(
    '#type' => 'textfield',
    '#title' => t('Image URL'),
    '#size' => 80,
    '#maxlength' => 100,
    '#default_value' => drutex_var_get("drutex_url_images_$format"),
    '#description' => t('URL that points to the Image directory. Can be a complete URL or a path relative to the Drupal base dir (recommended).')
  );

  $form['drutex_base']['note2'] = array(
    '#value' => t('The image directory may be used by some submodules to place
      other files in there, e.g. pdf and tex files.')
  );


  /*
     provide submodule-specific settings
  */

  foreach ($submodule_objects as $obj) {
    if (drutex_submodule_hook($obj->submodule, 'filter_settings')) {
      $form["drutex_{$obj->submodule}"] = array(
        '#type' => 'fieldset',
        '#title' => "DruTeX :: {$obj->title}",
        '#collapsible' => TRUE,
        '#collapsed' => !$obj->active
      );

      $form["drutex_{$obj->submodule}"] = array_merge(
        $form["drutex_{$obj->submodule}"],
        drutex_submodule_invoke($obj->submodule, 'filter_settings', $format)
      );
    }
  }

  return $form;
}

/**
 * Set DruTeX stylesheet to HTML head.
 */
function drutex_set_stylesheet() {
  static $done = FALSE;

  if (!$done) {
    $css = drutex_var_get("drutex_stylesheet");
    if (!empty($css)) {
      drupal_add_css($css, 'module');
    }
    $done = TRUE;
  }
}

/**
 * Convert DruTeX content to HTML, applying LaTeX2HTML filters and so on.
 *
 * @param $text
 *   The text to convert to HTML, e.g. the content of a node.
 * @param $format
 *   The input format to look for the DruTeX settings.
 * @return
 *   The text after applying all transformation rules.
 */
function drutex_node2html($text, $format = -1) {
  /* preprocess */
  foreach (drutex_submodule_implements('node2html_preprocess', $format) as $submodule) {
    $text = drutex_submodule_invoke($submodule, 'node2html_preprocess', $text, $format);
  }

  /* main cycle */
  $A = drutex_submodule_invoke_all('node2html', "format=$format");
  $B = module_invoke_all('drutex2html');
  $entities = array_merge($A, $B);
  usort($entities, '_drutex_weight_sort_cmp');

  foreach ($entities as $entity) {
    list($pattern, $replacement) = _drutex_create_regex($entity, $format);
    $text = preg_replace($pattern, $replacement, $text);
  }

  $text = _drutex_unhide_all($text);

  /* postprocess */
  foreach (drutex_submodule_implements('node2html_postprocess', $format) as $submodule) {
    $text = drutex_submodule_invoke($submodule, 'node2html_postprocess', $text, $format);
  }

  return $text;
}

/**
 * Helping function to sort a list of objects by their ->weight attributes.
 */
function _drutex_weight_sort_cmp($a, $b) {
  if (!isset($a->weight)) {
    $a->weight = 1000;
  }
  if (!isset($b->weight)) {
    $b->weight = 1000;
  }
  if ($a->weight == $b->weight) {
     return 0;
  }
  return ($a->weight < $b->weight) ? -1 : 1;
}


/**
 * Convert entity (transformation description) object to regular expression (pattern + replacement).
 *
 * @param $entity
 *   An entity object (this includes a transformation description).
 * @param $format
 *   The input format to look for the DruTeX settings.
 * @return
 *   array($pattern, $replacement)
 */
function _drutex_create_regex($entity, $format = -1) {
  $pattern = $entity->pattern;
  $replacement = preg_replace('@<var>([^<]+)</var>@se', "$$1", $entity->replacement);

  switch ($entity->type) {
    case 'latex-command':
      $pattern = "/\\\\$pattern\\{(.*?)\\}/s";
      return array($pattern, $replacement);

    case 'tag':
      $pattern = "@<$pattern( [^>]*)?>(.*?)</$pattern>@s";
      return array($pattern, $replacement);

    case 'tag2command':
      $pattern = "@<$pattern( [^>]*)?>(.*?)</$pattern>@s";
      $replacement = "\\\\$replacement\{\$2}";
      return array($pattern, $replacement);

    case 'regex':
    default:
      return array($pattern, $replacement);
  }
}

/**
 * Convert string with XML style attributes to array.
 *
 * For instance drutex_parse_attributes('dpi="100" cLaSs="Math"') will give
 * array('dpi' => '100', 'class' => 'Math').
 *
 * @param $entity
 *   An entity object (this includes a transformation description).
 * @param $format
 *   The input format to look for the DruTeX settings.
 * @return
 *   Array with attribute-names as keys and attribute-values as values.
 */
function drutex_parse_attributes($subject) {
  $matches = array();
  preg_match_all('/([a-zA-Z]+)="([^"]*)"/', $subject, $matches, PREG_SET_ORDER);

  $attributes = array();
  foreach ($matches as $match) {
    $attributes[strtolower($match[1])] = $match[2];
  }

  return $attributes;
}

/**
 * Do the reverse of drutex_parse_attributes().
 *
 * For instance drutex_merge_attributes(array('dpi' => '100', 'cLaSs' => 'Math')) will give
 * 'dpi="100" class="Math"'.
 */
function drutex_merge_attributes($A) {
  $str = '';
  foreach ($A as $key => $val) {
    $str .= strtolower($key) . "=\"$val\" ";
  }
  return trim($str);
}

/**
 * Hide some chunks of text from further processing.
 *
 * This is an important function to aim the parsing process.
 * Let's say, you want to replace [tex]$x^2$[/tex] by
 * [img src="xxx.png" alt="[tex]$x^2$[/tex]" /].
 * This would result in a failure, when the $xyz$ environment is processed now.
 *
 * The solution is to hide "[tex]$x^2$[/tex]" from further processing.
 * Just write:
 *   '[img src="xxx.png" alt="' . _drutex_hide('set', '[tex]$x^2$[/tex]') . '" /]'
 *
 * This would result in something like:
 *   [img src="xxx.png" alt="1f3870be274f6c49b3e31a0c6728957f:5:" /]
 *
 * The subject is saved, e.g. in the above example _drutex_hide('get', 5) is == '[tex]$x^2$[/tex]'.
 *
 * All hidden strings are automatically unhidden by DruTeX after the main processing is done.
 *
 * @param $cmd
 *   Either 'set' a string to hide or 'get' the string corresponding to a number.
 * @param $subject
 *   If 'set', the text to hide. If 'get', the number that identifies the string (without the secret hash key).
 * @return
 *   If 'set', a string of the form "secret:number:". If 'get', the originally hidden text.
 */
function _drutex_hide($cmd = 'get', $subject = '') {
  static $hidden = array();
  static $count = 0;

  if ($cmd == 'set') {
    $hidden[$count] = _drutex_unescape($subject);
    return _drutex_secret() . ':' . $count++ . ':';
  }
  else if ($cmd == 'get') {
    $subject = (int)$subject;
    return $hidden[$subject];
  }
}

/**
 * Unhide all hidden strings.
 *
 * @param $text
 *   The $text in which to replace the hidden-keys by the originally hidden strings.
 *   This is normally the node's content after applying all transformation rules.
 * @return
 *   The text with the original strings.
 */
function _drutex_unhide_all($text) {
  $key = _drutex_secret();
  return preg_replace("/$key:(\\d+):/se", "_drutex_hide('get', '$1')", $text);
}

/**
 * Generate a secret (unguessable) key.
 *
 * This is used for some parsing, see _drutex_hide().
 *
 * @return
 *   The secret key. It remains the same within one Drupal instance.
 */
function _drutex_secret() {
  static $key = '';

  if (empty($key)) {
    for ($i = 0; $i < 10; $i++) {
      $key .= mt_rand();
    }
    $key = md5($key);
  }

  return $key;
}

/**
 * Unescape what was escaped by preg_replace() when using the 'e' flag.
 *
 * E.g. print preg_replace('/(.*)/se', "'$1'", '\'hi\' "mum"') yields 'hi' \"mum\"
 * and print preg_replace('/(.*)/se', '"$1"', '\'hi\' "mum"') yields \'hi\' "mum".
 *
 * In DruTeX we should always use the first variant to avoid confusion.
 *
 * @param $text
 *   The text to unescape.
 * @param $quote
 *   Either "'" or '"'.
 * @return
 *   The unescaped text.
 */
function _drutex_unescape($text, $quote = '"') {
  return str_replace("\\$quote", "$quote", $text);
}

/**
 * Create temporary directory.
 *
 * This directory should normally be deleted automatically.
 */
function _drutex_create_temporary_dir($format = -1) {
  static $n = 1;
  $dir = drutex_var_get("drutex_dir_temporary_$format") . '/drutex-' . _drutex_secret() . '-' . $n++;
  mkdir($dir);
  return $dir;
}

/**
 * Delete directory with contents.
 *
 * No subfolders are supported since DruTeX doesn't needs this.
 */
function _drutex_delete_dir($dir) {
  if ($handle = opendir($dir)) {
    while ($item = readdir($handle)) {
      if ($item != '.' && $item != '..') {
         unlink("$dir/$item");
      }
    }
    closedir($handle);
    rmdir($dir);
  }
}

/**
 * Copy the contents (only files) of one directory to another.
 */
function _drutex_copy_dir($source, $dest) {
  if ($handle = opendir($source)) {
    while ($item = readdir($handle)) {
      if ($item != '.' && $item != '..') {
        if(is_file("$source/$item")) {
          copy("$source/$item", "$dest/$item");
        }
      }
    }
    closedir($handle);
  }
}

/**
 * Get URL where the images are saved.
 */
function drutex_get_image_url($format = -1) {
  $path = drutex_var_get("drutex_url_images_$format");

  /* different behaviour for absolute and relative paths */
  if (strpos($path, 'http') === 0) {
    return rtrim($path, '/');
  }
  else {
    return base_path() . trim($path, '/');
  }
}

/**
 * Implementation of hook_nodeapi().
 *
 * Notify all submodules when a node changed.
 */
function drutex_nodeapi(&$node, $op, $arg) {
  drutex_submodule_invoke_all('nodeapi', $node, $op, $arg, "format={$node->format}");
}

/**
 * Implementation of hook_perm().
 */
function drutex_perm() {
  return drutex_submodule_invoke_all('perm');
}

/**
 * Test if a DruTeX submodule is marked active in a given input format.
 *
 * @param $submodule
 *   Name of the submodule, e.g. "latex".
 * @param $format
 *   ID of the input format.
 * @return
 *   If $format is -1, the submodule only needs to be installed to make the function return TRUE.
 *   If the input format specified by $format doesn't use DruTeX at all, the result will be FALSE.
 *   In every other case, the function returns TRUE, if the submodule is installed and
 *   marked active in the specified input format.
 */
function drutex_submodule_is_active($submodule, $format = -1) {
  if (is_file(drupal_get_path('module', 'drutex') . "/drutex_{$submodule}.inc")) {
    if ($format == -1) {
      return true;
    }
    else if (_format_uses_drutex($format) && drutex_var_get("drutex_{$submodule}_active_{$format}")) {
      return true;
    }
  }

  return false;
}

/**
 * Test if a given input format uses DruTeX at all.
 *
 * The format '-1' always 'uses' DruTeX.
 */
function _format_uses_drutex($format = -1) {
  static $cache;

  if (!isset($cache)) {
    $cache = array();
    $result = db_query("SELECT format from {filters} WHERE module = 'drutex'");

    while ($obj = db_fetch_object($result)) {
      $cache[$obj->format] = true;
    }

    /* the format -1 always 'uses' DruTeX */
    $cache[-1] = true;
  }

  return isset($cache[$format]);
}


/**
 * Collect a list of submodule object.
 *
 * This is done by hooking over the subhook 'info'.
 *
 * If $format is specified, the objects will have an ->active attribute
 * that states if the submodule is active in the given input format.
 *
 * @param $format
 *   The optional input format id.
 * @return
 *   Array of info objects.
 */
function drutex_submodule_objects($format = -1) {
  static $objects;

  if (!isset($objects[$format])) {
    $objects[$format] = array();

    foreach (drutex_submodule_implements('info') as $submodule) {
      $obj = drutex_submodule_invoke($submodule, 'info', $format);
      $obj->submodule = $submodule;
      $obj->active = drutex_submodule_is_active($submodule, $format);
      $objects[$format][] = $obj;
    }
  }

  return $objects[$format];
}

/**
 * Determine whether a submodule implements a hook.
 *
 * @param $submodule
 *   The name of the submodule (without the .inc extension).
 * @param $hook
 *   The name of the hook (e.g. "info").
 * @return
 *   TRUE if the submodule is installed and the hook is implemented.
 */
function drutex_submodule_hook($submodule, $hook) {
  return function_exists("drutex_{$submodule}_{$hook}");
}

/**
 * Invoke a hook in a particular submodule.
 *
 * @param $submodule
 *   The name of the submodule (without the .inc extension).
 * @param $hook
 *   The name of the hook to invoke.
 * @param ...
 *   Arguments to pass to the hook implementation.
 * @return
 *   The return value of the hook implementation.
 */
function drutex_submodule_invoke() {
  $args = func_get_args();
  $submodule = array_shift($args);
  $hook = array_shift($args);

  if (drutex_submodule_hook($submodule, $hook)) {
    return call_user_func_array("drutex_{$submodule}_{$hook}", $args);
  }
}

/**
 * Collect a list of all DruTeX submodules.
 *
 * Submodules have the form drutex_submodulename.inc and reside in the DruTeX directory.
 *
 * @param $format
 *   If $format is specified, only the active submodules in this input format will be listed.
 *   If $format is -1, all installed submodules are listed.
 * @return
 *   An associative array whose keys and values are the names of the submodules.
 */
function drutex_submodule_list($format = -1) {
  static $list;

  if (!isset($list[$format])) {
    $list[$format] = array();
    $path = drupal_get_path('module', 'drutex');
    $files = file_scan_directory($path, '^drutex_.*\.inc$');

    foreach ($files as $file) {
      $submodule = substr($file->name, strlen('drutex_'));
      if (drutex_submodule_is_active($submodule, $format)) {
        $list[$format][$submodule] = $submodule;
      }
    }
  }

  return $list[$format];
}

/**
 * Determine which submodules are implementing a hook.
 *
 * @param $hook
 *   The name of the hook (e.g. "defaults").
 * @param $format
 *   ...
 * @return
 *   An array with the names of the modules which are implementing this hook.
 */
function drutex_submodule_implements($hook, $format = -1) {
  static $implementations;

  if (!isset($implementations[$hook][$format])) {
    $implementations[$hook][$format] = array();

    foreach (drutex_submodule_list($format) as $submodule) {
      if (drutex_submodule_hook($submodule, $hook)) {
        $implementations[$hook][$format][] = $submodule;
      }
    }
  }

  return $implementations[$hook][$format];
}

/**
 * Invoke a hook in all (active) submodules that implement it.
 *
 * @param $hook
 *   The name of the hook to invoke.
 * @param ...
 *   Arguments to pass to the hook.
 * @return
 *   An array of return values of the hook implementations. If submodules return
 *   arrays from their implementations, those are merged into one array.
 */
function drutex_submodule_invoke_all() {
  $args = func_get_args();
  $hook = array_shift($args);
  $return = array();
  $format = _drutex_rewrite_format_call($args);

  foreach (drutex_submodule_implements($hook, $format) as $submodule) {
    $result = call_user_func_array("drutex_{$submodule}_{$hook}", $args);
    if (isset($result) && is_array($result)) {
      $return = array_merge($return, $result);
    }
    else if (isset($result)) {
      $return[] = $result;
    }
  }

  return $return;
}


function _drutex_rewrite_format_call(&$args) {
  $last = array_pop($args);
  $matches = array();

  if (is_string($last) && preg_match('/^format=([-]?\d+)$/', $last, $matches)) {
    return $matches[1];
  }
  else {
    array_push($args, $last);
    return -1; // no filter
  }
}

$path = drupal_get_path('module', 'drutex');


/* load the submodules */
foreach (drutex_submodule_list() as $submodule) {
  include_once("{$path}/drutex_{$submodule}.inc");
}