For resolving 960.gs classes in the NineSixty Drupal theme. (new version)

ns_class.php

<?php

/**
 * @file
 * Functions related resolving grid classes.
 */

// Used by the ns_resolve_class() function.
define('END', 999);
// Class delimiter.
define('DELIMIT', '-');

/**
 * Contextually resolves 960 Grid System classes.
 * 
 * There are two modes of behavior depending on the first parameter or default
 * class.
 * 
 * Mode 1:
 *
 * The first parameter passed is the *default class*. It is broken into three
 * parts. The first is the class type. Valid values are grid, push, pull
 * prefix and suffix for the 960 Grid System but this function is generic
 * enough to use with any type of class as long as it follows an expected
 * pattern.
 *
 * The second part is the delimiter separating the type from the unit count.
 * The default is the hyphen '-' for this Drupal adaptation. The original 960
 * Grid System uses underscores. To use the underscore, your theme must set it
 * through the DELIMIT constant above.
 *
 * The third part is the unit count. This should be set to the highest value
 * your layout will allow since this function will *always* work towards
 * reducing the count based on the context parameters that follow.
 *
 *  classType-unitCount
 *       grid-12
 *       push-4
 *       pull-12
 *
 * The rest of the parameters must be set in variable/numeric pairs. The
 * variable can be any PHP variable within a template file but it is most
 * often used with block region variables in the page.tpl.php file. If the
 * variable contains data, it will trigger the numeric side of the pair by
 * subtracting from the unit count set for the first parameter (default class).
 *
 * Examples:
 *
 *  class="<?php nsp('grid-16', $page['sidebar_first'], 4); ?>"
 *
 *  If the sidebar_first block region contains content, 4 will be subtracted
 *  from 'grid-16' giving us 'grid-12' for the class. When the region is empty,
 *  the full width of 16 grid units will be printed for the class. Once
 *  properly calculated and setup, columns will expand and shrink as needed.
 *
 *  There are no limits to number of variable/numeric pairs.
 *
 *  class="<?php nsp('grid-16', $var_a, 3, $var_b, 4, $var_c, 5); ?>"
 *
 *  Note that the print command is not used. The function prints out directly.
 *  If the data must be returned, use the ns() or ns_resolve_class() function.
 *
 *  There are cases where the default class needs to be reduced when a
 *  variable *does not* contain data. Simply placing a bang or exclamation
 *  point before the variable will accomplish this.
 *
 *  class="<?php nsp('push-4', !$page['sidebar_first'], 4); ?>"
 *
 *  The PHP AND operator can be used to check on multiple variables at once
 *  and subtract based on that. The next example shows that "if $var_a AND
 *  $var_b has content, then subtract 7 from grid-12".
 *
 *  class="<?php nsp('grid-16', $var_a && $var_b, 7); ?>"
 *
 *  Any PHP logical operators are valid. As long as it equates to a boolean
 *  (TRUE or FALSE) statements, it will "just work".
 *
 *  @see http://www.php.net/manual/en/language.operators.logical.php
 *
 *  There is one constant that can be added to the numeric side of the pair
 *  which will prevent any further reductions if the pair resolves.
 *
 *  class="<?php nsp('grid-16', $var_a, 4 + END, $var_b, 3); ?>
 *
 *  If $var_a contains content then 4 will be subtracted then stop evaluating
 *  any remaining pairs. If $var_a does not contain content then it will
 *  continue evaluating $var_b and 3.
 *
 *  Why is this even needed? Here is one use case:
 *
 *  <div class="container-16">
 *
 *    <div class="<?php nsp('grid-16, $var_a && $var_b, 6 + END, $var_a || $var_b, 4); ?>">
 *      ...
 *    </div>
 *
 *  <?php if ($var_a): ?>
 *    <div class="grid-3<?php nsp(' prefix-1, $var_b, 1); ?>">
 *      <?php print $var_a; ?>
 *    </div>
 *  <?php endif; ?>
 *
 *  <?php if ($var_b): ?>
 *    <div class="grid-3<?php nsp(' prefix-1, $var_a, 1); ?>">
 *      <?php print $var_b; ?>
 *    </div>
 *  <?php endif; ?>
 *
 *  </div><!-- .container-16 -->
 *
 *  This is getting out of hand. This will be moved into its own documentation.
 *
 * Mode 2:
 *
 * The second mode is detected with the first parameter does not follow the
 * pattern in the first mode. Any class can be used for this and all it does
 * is remove the class if the following parameters contain a value. Instead of
 * the variable/numeric pair, It must only be variables since there is no math
 * involved in this mode.
 *
 *  Examples:
 *
 *  class="<?php nsp('alpha', $var_a); ?>
 *
 *  If $var_a contains data, the alpha class will not print. The same rules
 *  apply when evaluating the variable and again, multiple variables can be
 *  set in a series. The important thing to remember is that this function
 *  always works one way and that is towards reducing or removing the default
 *  class.
 *
 * Speed test:
 *  This version:
 *  100,000 - 1.2751400470734 seconds.
 *      100 - 0.0012891292572021 seconds.
 *  Original version:
 *  100,000 - 1.1014170646667 seconds.
 *      100 - 0.0011289119720459 seconds.
 *
 * @see ns()
 * @see ns_resolve_class()
 */
function nsp() {
  $args = func_get_args();
  print ns_resolve_class(array_shift($args), $args);
}

/**
 * Serves the same purpose as the nsp() function but does not print directly.
 *
 * @see nsp()
 * @see ns_resolve_class()
 */
function ns() {
  $args = func_get_args();
  return ns_resolve_class(array_shift($args), $args);
}

/**
 * Process the $default class based on the $contexts.
 *
 * @see nsp()
 * @see ns()
 *
 * @param $default
 *  (required - string) The default class. classType-[int] will be processed
 *  differently from 'class-string'.
 * @param $contexts
 *  (required - array) Array of sequential $variable/numeric pairs when
 *  resolving grid units. - classType-[int]
 *    example: array($var1, 1, $var2, 2, [etc...])
 *
 *  When not resolving grid units, contexts must all be variables without the
 *  numbered pairs. First variable found containing data will trigger the
 *  removal of the $default class. - alpha, omega, 'class-string', etc...
 *    example: array($var1, $var2[, etc...])
 */
function ns_resolve_class($default, $contexts) {

  $units = NULL;
  if (strpos($default, DELIMIT) !== FALSE) {
    // Get the type of class, i.e., 'grid', 'pull', 'push', etc.
    // Also get the default unit count for the type to be procesed.
    list($type, $units) = explode(DELIMIT, $default);
  }

  if (is_numeric($units)) {
    // Process units based on context/numeric pairs.
    foreach ($contexts as $i => $c) {
      if (!($i%2)) {
        // $c == context variable.
        $has_data = !empty($c);
      }
      elseif ($has_data) {
        // $c == numeric paired to previous variable.
        if ($c > END) {
          $units = $units - ($c - END);
          break;
        }
        else {
          $units = $units - $c;
        }
      }
    }
    $output = $units > 0 ? $type . DELIMIT . $units : '';
  }
  else {
    // Process binary state of the default class based on the availability of
    // all contexts variables (not paired). First found will trigger its removal.
    $output = $default;
    foreach ($contexts as $c) {
      if (!empty($c)) {
        $output = '';
        break;
      }
    }
  }

  return $output;
}