patterns.module

<?php
/**
 * @file
 * Enables extremely simple adding/removing features to your site with minimal to no configuration.
 *
 * It works by reading a pattern file and then creating a form which contains already the values for
 * specific elements. The form is then validated and submitted, exactly as the 'submit' button was
 * pressed from the browser window.
 *
 * The following steps (operations) are performed sequentially:
 *
 * * Preparation Phase
 * -------------------
 *
 *  - 'prepare':      - Transform the patterns tags into the actual element of the form to be submitted.
 *                    - Add eventual standard values which are missing (this makes writing the pattern
 *                      easier and more synthetic).
 *                    - No errors are raised here.
 *
 *  - 'validate':      - Validate the data for the form_id and raise errors, if any.
 *
 *
 * * Batch Phase
 * -----------------
 *
 * - 'callbacks'      - Return the array of functions that need to be called sequentially in later stages.
 *                      Those functions which are among the form_ids returned by hook_patterns() will be
 *                      treated as form functions, while others will be treated as regular callback functions.
 *
 * - 'build':         - Get the form data for the action. This can either just be the form values, or
 *                      it can be the full //form_state object//.
 *
 * - 'params':        - Get any extra parameters required by the form function.
 *
 *
 * * Execution Phase
 * -----------------
 *  drupal_form_submit() is called. The arguments are supplied to the form (is it is expects extra arguments)
 *  and the data is passed to the form callback.
 *
 *
 * - 'cleanup':       - cleanup operations are performed, if any.
 *
 *
 * * Post Batch
 * ---------------
 *
 * // NOT USED NOW: Check if we need it later
 * - 'identifiers':    - ????? Get any primary identifiers from the action for further actions to take advantage of
 *
 */

module_load_include('inc', 'patterns', 'includes/config');
module_load_include('inc', 'patterns', 'includes/db');
module_load_include('inc', 'patterns', 'includes/error');
module_load_include('inc', 'patterns', 'includes/export');
module_load_include('inc', 'patterns', 'includes/io');
module_load_include('inc', 'patterns', 'includes/parser');
module_load_include('inc', 'patterns', 'includes/utils');
module_load_include('inc', 'patterns', 'includes/editor');
module_load_include('inc', 'patterns', 'includes/imports');
module_load_include('inc', 'patterns', 'includes/theme');

// Not used for now.
module_load_include('inc', 'patterns', 'includes/servers');
module_load_include('inc', 'patterns', 'includes/theme');

define('PATTERNS_SUCCESS', 1);
define('PATTERNS_WARN', 0);
define('PATTERNS_ERR', -1);

define('PATTERNS_CREATE', 'create');
define('PATTERNS_MODIFY', 'modify');
define('PATTERNS_DELETE', 'delete');

define('PATTERNS_FILES', 'files');
define('PATTERNS_INFO', 'descr');


define('PATTERNS_STATUS_OK', 0); // installed, not enabled
define('PATTERNS_STATUS_ENABLED', 1); // installed, enabled
define('PATTERNS_STATUS_INVALID', -1); // invalid
define('PATTERNS_STATUS_REMOVED', -5); // removed

// Add libraries for performing AJAX calls outside forms
//drupal_add_library('system', 'drupal.ajax');
//drupal_add_library('system', 'jquery.form');


/**
 * @todo:
 * @ Load (some) of the includes only when really needed
 * @ When you modify a pattern you always need to reload the main pattern page, so it noticed that the pattern is actually changed. In confirm form it is too late.
 * @ Enable pattern configurations
 * @ Enable components to analyze the current pattern for better validation
 * @ Allow module version restricting
 * @ Put in functionality to auto-download modules (and the correct version)
 * @ Enable backups before running patterns and reverting back to those backups
 * @ Implement a progress meter
 * @ Enable interactive actions by allowing patterns to resume from a saved position
 * @ Implement an export feature for all available form_ids
 * @ Allow resuming failed patterns
 * @ In the pattern details, list any sub-patterns directly on the patterns listing page
 * @ Create a Pattern class (?) check performance
 * @ Increase performaces, it seems still slow.
 */


/**
 * Implements hook_menu().
 */
function patterns_menu() {
  $items = array();

  $items['admin/patterns'] = array(
    'title' => 'Patterns',
    'description' => 'Administer patterns available for your site',
    'page callback' => 'patterns_list',
    'access arguments' => array('administer patterns')
  );
  $items['admin/patterns/list'] = array(
    'title' => 'List',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -10
  );

  $items['admin/patterns/edit/%'] = array(
    'title' => 'Edit Pattern',
    'page callback' => 'patterns_edit_page',
    'page arguments' => array(3),
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

  $items['admin/patterns/quickrun'] = array(
    'title' => 'Quick Run',
    'page callback' => 'patterns_editor',
    'page arguments' => array('patterns_quickrun'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );
  $items['admin/patterns/export'] = array(
    'title' => 'Export',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_export'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );

  $items['admin/patterns/create/%'] = array(
    'title' => 'Create a new Pattern',
    'page callback' => 'patterns_editor_create_page',
    'page arguments' => array(3),
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

  $items['admin/patterns/enable'] = array(
    'title' => 'Enable Pattern',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_enable_pattern'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

  $items['admin/patterns/trash'] = array(
    'title' => 'Move Pattern to Recycle Bin',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_trash_pattern'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

//  $items['admin/patterns/trash/%'] = array(
//    'title' => 'Move Pattern to Recycle Bin',
//    'page callback' => 'patterns_db_trash_pattern',
//    'page arguments' => array(3),
//    'access arguments' => array('administer patterns'),
//    'type' => MENU_CALLBACK
//  );

  $items['admin/patterns/remove'] = array(
    'title' => 'Remove Pattern',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_remove_pattern'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

    $items['admin/patterns/refresh'] = array(
    'title' => 'Refresh Patterns',
    'page callback' => 'patterns_io_get_patterns_service',
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

  $items['admin/patterns/settings'] = array(
    'title' => 'Settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_config_settings'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK,
    'weight' => 10
  );

  $items['admin/patterns/validate'] = array(
    'title' => 'Validate Pattern YAML Source',
    'page callback' => 'patterns_validate_service',
    'access arguments' => array('administer patterns'),
    'type' => MENU_CALLBACK
  );

  // TODO: Check admin/patterns/get
  // TODO: permission

  $items['admin/patterns/get'] = array(
    'title' => 'Download Pattern Source',
    'page callback' => 'patterns_get_source',
    'access callback' => TRUE,
    'type' => MENU_CALLBACK
  );

  /*
   * TODO: outdated, disabled for now.
  $items['patterns.xml'] = array(
    'title' => 'Published Patterns',
    'page callback' => 'patterns_feed',
    'access callback' => TRUE,
    'type' => MENU_CALLBACK
  );
  */

  // TODO: Check import.

  $items['admin/patterns/import'] = array(
    'title' => 'Import',
    'page callback' => 'patterns_editor',
    'page arguments' => array('patterns_import_source'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );

  // old
  //  $items['admin/patterns/import'] = array(
  //    'title' => 'Import',
  //    'page callback' => 'drupal_get_form',
  //    'page arguments' => array('patterns_import_source'),
  //    'access arguments' => array('administer patterns'),
  //    'type' => MENU_LOCAL_TASK
  //  );

  $items['admin/patterns/import/source'] = array(
    'title' => 'Import Source Code',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -10
  );

  $items['admin/patterns/import/file'] = array(
    'title' => 'Import File',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_import_file'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );
  $items['admin/patterns/import/url'] = array(
    'title' => 'Import from URL',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_import_url'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );
  $items['admin/patterns/import/module'] = array(
    'title' => 'Import from module (experimental)',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('patterns_import_module'),
    'access arguments' => array('administer patterns'),
    'type' => MENU_LOCAL_TASK
  );

  // Disable for Now.
  // TODO Check publish/unpublish

  //  $items['admin/patterns/publish'] = array(
  //    'title' => 'Publish Pattern',
  //    'page callback' => 'patterns_publish_pattern',
  //    'access arguments' => array('administer patterns'),
  //    'type' => MENU_CALLBACK
  //  );
  //  $items['admin/patterns/unpublish'] = array(
  //    'title' => 'Unpublish Pattern',
  //    'page callback' => 'patterns_unpublish_pattern',
  //    'access arguments' => array('administer patterns'),
  //    'type' => MENU_CALLBACK
  //  );

  //  $items['admin/patterns/server'] = array(
  //    'title' => 'Patterns Server',
  //    'page callback' => 'drupal_get_form',
  //    'page arguments' => array('patterns_import_server'),
  //    'access arguments' => array('administer patterns'),
  //    'type' => MENU_LOCAL_TASK,
  //    'weight' => -5
  //  );

  // This items were already commented.
  /////////////////////////////////////////////////////

  //     $items[] = array('path' => 'admin/patterns/configure',
  //       'title' => t('Configure Pattern'),
  //       'callback' => 'drupal_get_form',
  //       'callback arguments' => array('patterns_configure_pattern'),
  //       'type' => MENU_CALLBACK
  //     );

  //     $items[] = array('path' => 'admin/patterns/info',
  //       'title' => t('Pattern Details'),
  //       'callback' => 'patterns_info',
  //       'type' => MENU_CALLBACK
  //     );

  //     $items[] = array('path' => 'admin/patterns/disable',
  //       'access' => user_access('administer patterns'),
  //       'title' => t('Disable Pattern'),
  //       'callback' => 'drupal_get_form',
  //       'callback arguments' => array('patterns_disable_pattern'),
  //       'type' => MENU_CALLBACK
  //     );

  //  $items['admin/patterns/modules'] = array(
  //    'title' => 'Pattern Modules',
  //    'page callback' => 'patterns_modules_page',
  //    'access arguments' => array('administer patterns'),
  //    'type' => MENU_CALLBACK
  //  );

  //     $items[] = array('path' => 'admin/patterns/revert',
  //       'access' => user_access('administer patterns'),
  //       'title' => t('Revert Pattern'),
  //       'callback' => 'patterns_revert',
  //       'type' => MENU_CALLBACK
  //     );

  return $items;
}


/**
 * First function to be called for displaying the pattern list page.
 */
function patterns_list() {

  drupal_add_css(drupal_get_path('module', 'patterns') . '/css/patterns.css');
  drupal_add_js(drupal_get_path('module', 'patterns') . '/js/patterns.js');

  $form['commands'] = array(
    '#type' => 'fieldset',
    '#title' => 'Commands'
    );

//  $form['commands']['refresh'] = array(
//    '#type' => 'button',
//    '#value' => 'Refresh',
//    '#attributes' => array('style' => 'float:right'),
//    '#ajax' => array(
//      'callback' => 'patterns_io_get_patterns_service',
//      'wrapper' => 'all_patterns_div',
//    ),
//  );

    $form['commands']['refresh'] = array(
      '#type' => 'button',
      '#value' => 'Refresh All',
      '#attributes' => array('style' => 'float:right',
                             'id' => 'refresh-all',
                             ),
    );

  $form['commands']['create'] = array(
    '#type' => 'button',
    '#value' => 'Create New',
    '#attributes' => array('style' => 'float:right'),
    '#prefix' => '<a href="' . url('admin/patterns/import') . '">',
    '#suffix' => '</a>',
  );

  $form['commands']['export'] = array(
    '#type' => 'button',
    '#value' => 'Export',
    '#attributes' => array('style' => 'float:right'),
    '#prefix' => '<a href="' . url('admin/patterns/export') . '">',
    '#suffix' => '</a>',
  );

  $output = drupal_render($form);

  // Load the the pattern handlers from compontents directory
  // or from modules which implement hook_patterns().
  patterns_load_components();

  // Load the patterns from database.
  $patterns = patterns_get_patterns();

  $output .= theme('patterns_list', $patterns);

  return $output;
}

/**
 * Form constructor for the Patterns enabling form.
 *
 * It prompts the user with a submenu of options regarding default behavior with
 * sub-patterns.
 *
 * @TODO Find a way to skip this in pattern_list, to quickly execute the pattern.
 *
 * @param integer $pid The ID of the Pattern to enable.
 *
 * @see patterns_enable_pattern_submit()
 * @ingroup forms
 */
function patterns_enable_pattern($form, &$form_state, $pid) {

  $pattern = patterns_get_pattern($pid);
  if (empty($pattern)) {
    $form['not_existing'] = array(
      '#markup' => t('Invalid pattern ID.') . ' ' . l(t('Back'), 'admin/patterns'),
      '#prefix' => '<div id="important">',
      '#suffix' => '<br/></div>',
    );
    $form_state['redirect'] = 'admin/patterns';
    return $form;
  }

  $form['pid'] = array(
    '#type' => 'value',
    '#value' => $pid,
  );

  $options_mode = array(
    'extend' => 'Extend',
    'runover' => 'Run-Over',
  );

  $form['execution'] = array(
    '#type' => 'radios',
    '#title' => t('Execution mode:'),
    '#description' => t('Extend mode can only add new feature to your web-site, Run-over can also delete. At the moment \'Extend\' is the only mode permitted.'),
    '#options' => $options_mode,
    '#default_value' => 'extend',
    '#disabled' => 'true',
  );

  $options_run_mode = array(
    'batch' => 'Batch',
    'php' => 'PHP',
  );

  $form['mode'] = array(
    '#type' => 'radios',
    '#title' => t('Running mode:'),
    '#description' => t('Batch mode uses the Batch API provided by Drupal thus providing intermediate feedback about the progress. PHP will only return when every action has been processed (or there has been an error), which is easier to debug.'),
    '#options' => $options_run_mode,
    '#default_value' => variable_get('patterns_default_running_mode', 'batch'),
    '#element_validate' => array('patterns_mode_validate'),
  );

  $options = array(
    'first-update' => t('only if disabled or if updated since last run (recommended)'),
    'always' => t('always'),
    'update' => t('only if updated since last run'),
    'first' => t('only if disabled'),
    'never' => t("don't run sub-patterns at all"),
  );

  $form['run-subpatterns'] = array(
    '#type' => 'radios',
    '#title' => t('Run sub-patterns:'),
    '#description' => t("Decide when to run sub-patterns that are called by the currently run pattern. If unsure, stick to recommended setting. Note that your choice won't have any effect if your pattern doesn't contain sub-patterns or if this setting has been defined within the pattern file itself."),
    '#options' => $options,
    '#default_value' => 'first-update',
    '#disabled' => 'true',
  );

  $disclaimer = t('Please be sure to backup your site before running a pattern. Patterns are not guaranteed to be reversable in case they do not execute well or if unforseen side effects occur.');

  return confirm_form($form, t('Proceed with running pattern %pattern?', array('%pattern' => $pattern->title)), 'admin/patterns', $disclaimer);
}

function patterns_mode_validate($element, &$form_state, $form) {
  if (!in_array($form_state['values']['mode'], array('batch', 'php'))) {
    form_error($element, t('Mode must be one of \'batch\' or \'php\'.'));
  }
}

/**
 * Form submission handler for patterns_enable_pattern().
 *
 * Takes the values from the form enable_pattern and starts the whole process
 * by calling execute_pattern.
 *
 * @see patterns_enable_pattern()
 */
function patterns_enable_pattern_submit($form, &$form_state) {
  $pid = $form_state['values']['pid'];

  patterns_load_components();
  $pattern = patterns_get_pattern($pid);

  patterns_start_engine($pattern, $form_state['values'], $form_state['values']['mode']);

  $form_state['redirect'] = 'admin/patterns';
}


/**
 * Form constructor for the Patterns removing form.
 *
 * Creates a confirm_form to make sure the removing operation was intentional.
 *
 * @param mixed $pid The ID of the Pattern to enable.
 *
 * @see patterns_remove_pattern_submit()
 * @ingroup forms
 */
function patterns_trash_pattern($form, &$form_state, $pid = NULL) {

  $pattern = patterns_get_pattern($pid);
  if (empty($pattern)) {
    drupal_set_message(t('Pattern could not be moved into the trash bin.'), 'error');
    $form_state['redirect'] = 'admin/patterns';
    return $form;
  }

  $form['pid'] = array(
    '#type' => 'value',
    '#value' => $pid,
  );


  $disclaimer = t('Trashed patterns can be restored later on.');

  return confirm_form($form, t('Proceed with removing pattern %pattern?', array('%pattern' => $pattern->title)), 'admin/patterns', $disclaimer);

}

/**
 * Executes patterns_db_trash_pattern() and display a message.
 *
 * @see patterns_db_trash_pattern()
 */
function patterns_trash_pattern_submit($form, &$form_state) {
  $pid = $form_state['values']['pid'];
  print_r($form_state['values']);
  $result = patterns_db_trash_pattern($pid);

  if (!$result) {
    drupal_set_message(t('Pattern could not be moved into the trash bin.'), 'error');
  }
  else {
    drupal_set_message(t('Pattern succesfully moved into the trash bin.'), 'status');
  }

  $form_state['redirect'] = 'admin/patterns';
 }

/**
 * Form constructor for the Patterns removing form.
 *
 * Creates a confirm_form to make sure the removing operation was intentional.
 *
 * @param mixed $pid The ID of the Pattern to enable.
 *
 * @see patterns_remove_pattern_submit()
 * @ingroup forms
 */
function patterns_remove_pattern($form, &$form_state, $pid = NULL) {

  $pattern = patterns_get_pattern($pid);

  if (empty($pattern)) {
    $form['not_existing'] = array(
      '#markup' => t('Invalid pattern ID for removal.') . ' ' . l(t('Cancel'), 'admin/patterns'),
      '#prefix' => '<div id="important">',
      '#suffix' => '<br/></div>',
    );
    return $form;
  }

  $form['pid'] = array(
    '#type' => 'value',
    '#value' => $pid,
  );

  $disclaimer = t('This operation cannot be undone. Are you sure?');

  return confirm_form($form, t('Proceed with removing pattern %pattern?', array('%pattern' => $pattern->title)), 'admin/patterns', $disclaimer);
}

/**
 * Form submission handler for patterns_remove_pattern().
 *
 * @see patterns_remove_pattern()
 */
function patterns_remove_pattern_submit($form, &$form_state) {
  $pid = $form_state['values']['pid'];

  $result = patterns_db_remove_pattern($pid);

  //@TODO: Remove the file as well.

  if (!$result) {
    drupal_set_message(t('Pattern could not be removed.'), 'error');
  }
  else {
    drupal_set_message(t('Pattern was removed succesfully.'), 'status');
  }
  $form_state['redirect'] = 'admin/patterns';
}

/**
 * The beginning of the whole Patterns logic. Starts the execution in 'batch'
 * mode (default) or 'php' mode, which makes things easier for debugging.
 *
 * @param stdClass $pattern Pattern object as loaded by patterns_get_pattern().
 * @param array $params Parameters for executing the pattern. Array format is as follows:
 *
 * - pid => Pid of the pattern as it is in the database.
 * - run-subpatterns => ['first-update', always', 'update', 'first', 'never']
 *
 * If coming from form_confirm some other parameters are addes, such as:
 * - confirm [1]
 * - submit  [Confirm]
 * - form_build_id
 * - form_token
 * - form_id
 * - op  [Confirm]
 *
 * @param string $mode The running mode, one of {'batch', 'php'}.
 *
 * @return The result of the appropriate patterns_execute_pattern_$mode function.
 *
 * @see patterns_execute_pattern_batch()
 * @see patterns_execute_pattern_php()
 */
function patterns_start_engine($pattern, $params = array(), $mode = 'batch') {
  module_load_include('inc', 'patterns', 'includes/core.' . $mode);
  $fun = 'patterns_execute_pattern_' . $mode;

  drupal_set_time_limit(0);

  if (!isset($params['quickrun']) || !$params['quickrun']) {
    if (!is_object($pattern)) {
      $pattern = patterns_get_pattern($pattern);

      if (!$pattern) {
        return FALSE;
      }
    }
  }

  $pattern->subpatterns_run_mode = $params['run-subpatterns'];

  /////////////////////////////////////////
  // Get Patterns details
  $patterns_details = patterns_get_pattern_details($pattern);
  if ($patterns_details === FALSE) {
    drupal_set_message(t('There were errors while processing a pattern, aborting.'), 'error');
    return FALSE;
  }

  // TODO: handle multiple patterns correctly
  // Let us assume we have only one pattern in the returned array of details
  $pid = key($patterns_details);
  $pattern_details = current($patterns_details);

  $info = $pattern_details['info'];

  // Array of infos of multiple patterns (we have only one for now).
  $infos = array($pid => $info);

  $modules = $pattern_details['modules'];
  $sections = $pattern_details['sections'];

  // Ste: Actions_map seems to be used with includes. Probably we do not need it now.
  // $actions_map = array('patterns' => $pattern_details['info'], 'map' => $pattern_details['actions_map']);

  // TODO: Patterns details was returning this in case of recursive includes.
  //  $result['actions_map'][] = array(
  //          'pid'   => $pattern->pid,
  //          'index' => $key,
  //        );

  $actions_map = array('patterns' => $infos, 'map' => NULL); // Fix this.
  ////////////////////////////////////////

  // Install modules, if necessary.
  $results = patterns_install_modules($modules);
  if (!$results['success']) { // TODO: handle properly.
  drupal_set_message($results['error_message'], 'error');
  return FALSE;
  }

  // Execute the Pattern using the selected mode.
  return $fun($pattern, $params, $patterns_details, $actions_map);
}

// @TODO: Take care patterns_invoke does not return any more the tagmodules index.
// Use patterns_get_tagmodules_index() instead.

/**
 * Execute hook_patterns with the given operation and return the results.
 *
 * It also builds up, if necessary, the list of available action-tags and
 * binds them to the correct module.
 *
 * @param string $hook
 *   The hook to be called. One of {'prepare', 'validate', 'callbacks', 'build',
 *   'params', 'cleanup'}.
 * @param string $action
 *   The action to be executed. One of {'create', 'modify', 'delete'}.
 * @param array $data
 *   (optional) The data supplied as an associative array. Defaults to NULL.
 * @param mixed $form_id
 *   (optional) The name of the form to be used. Defaults to NULL.
 * @param array $a
 *   (optional) Extra parameters to pass. Defaults to NULL.
 *
 * @return array $return An array packed by patterns_results().
 */
function patterns_invoke($hook, $action, &$data = NULL, $form_id = NULL, &$a = NULL) {

  $tag_modules = patterns_get_tagmodules_index();

  // Unsetting it while the module performs operations.
  $tag = $data['tag'];
  unset($data['tag']);

  if (isset($tag_modules[$tag])) {
    $module = $tag_modules[$tag]['module'];
    $func = $module . '_patterns_' . $hook;
    if (function_exists($func)) {
      if ($form_id) { // We are past hook_patterns_build().
        $return = $func($action, $form_id, $data, $a);
      }
      else {
        $return = $func($action, $tag, $data, $a);
      }
    }
    else {
      $msg = t('Required patterns callback function %func does not exist.', array('%func' => $func));
      $return = patterns_results(PATTERNS_ERR, $msg);
    }
  }
  else {
    $msg = t('Required patterns tag %tag is not provided by any component.', array('%tag' => $tag));
    $return = patterns_results(PATTERNS_ERR, $msg);
  }

  // Check if the output is correctly formatted, and eventually try to correct it.
  if (!_patterns_is_patterns_results($return)) {

    if ($return === TRUE) {
      $return = array('status' => PATTERNS_SUCCESS);
    }
    elseif ($return === FALSE) {
      $msg = t('Unspecified error occurred in %func.', array('%func' => $func));
      $return = patterns_results(PATTERNS_ERR, $msg);
    }
    else {
      $msg = t('The return value of %func is not properly formatted.', array('%func' => $func));
      $return = patterns_results(PATTERNS_ERR, $msg);
    }
  }

  $return['details']['action'] = $action;
  $return['details']['hook'] = $hook;
  $return['details']['function'] = $form_id;

  $data['tag'] = $tag;
  return $return;

}

/**
 * Creates the list of modules implementing the pattern hook. Additional
 * information is provided such as the files or the forms needed by the tag. It
 * uses caching, unless a specific tag is being looked up.
 *
 * @param string $tag_name
 *   (optional) If set, only information about this specific tag is returned
 *   and the cache will be refreshed. Defaults to NULL.
 * @param array $data
 *   (optional) The data of the pattern. If $tag_name was set, $data must be
 *   set as well. Defaults to NULL.
 * @param integer $id
 *   (optional) If set, only this particular bit of information is returned. Defaults to NULL.
 *   Allowed values for $id are: 'descr', PATTERNS_CREATE, PATTERNS_MODIFY,
 *   PATTERNS_DELETE, and 'files'.
 *
 * @Note The return type has changed. It used to be an array of tag => module now
 * you get the info with $tag['module'].
 *
 * @return array $tag_modules The tag_modules index built according to the parameters.
 */
function patterns_get_tagmodules_index($tag_name = NULL, $data = NULL, $id = NULL) {
  static $tag_modules;

  // Index not yet built or $tag_name is set.
 if (!is_array($tag_modules) || $tag_name != NULL) {
    $tag_modules = array();
    // Get a list of tags and their modules.
    // TODO: Optimize: if $tag_name is set, and $tag_modules is not empty, look
    // for only the modules that we have seen before implement the tag.
    foreach (module_implements('patterns') as $module) {
      $tags = module_invoke($module, 'patterns', $data);
      foreach ($tags as $tag => $value) {
        // Add the reference to the module within the information which each
        // module is already returning
        $value['module'] = $module;
        $tag_modules[$tag] = $value;
      }
    }
  }

  if (empty($tag_name)) {
    return $tag_modules;
  }
  elseif (empty($id)) {
    return $tag_modules[$tag_name];
  }
  else {
    return $tag_modules[$tag_name][$id];
  }
}

/**
 * Constructs a Pattern object with default standard values.
 *
 * @param array $pattern Input array structure of the pattern. Defaults to an empty array.
 * @return StdClass $pattern The result object.
 */
function patterns_get_pattern_obj($pattern = array()) {

  $pattern = is_object($pattern) ? $pattern : (object) $pattern;

  $defaults = array(
    'pid' => '',
    'name' => '',
    'status' => 0, // disabled
    'public' => 0,
    'updated' => '', // when enabled
    'enabled' => '', // when enabled
    'title' => t('New Pattern'),
    'pattern' => '', // the pattern code
  );

  foreach ($defaults as $key => $value) {
    if (!isset($pattern->$key)) {
      $pattern->$key = $value;
    }
  }

  return $pattern;
}

/**
 * @TODO patterns_refresh().
 */
function patterns_refresh() {
}