<?php

/**
 * @file
 * Experimental "sketchy" code for gettext parsing and generating API.
 * For a world without failures, exceptions and certainly without users ;)
 */

/**
 * Example code import a po file into the database.
 *
 * Import a po file into the Database.
 * The file may be local, remote (via stream wrapper) or even XML.
 * The import has a small memory footprint.
 * The import may be split up to enable batch handling.
 */
  $file = new GettextPoFile('path/to/file/filename.po');
  gettext_import($file);

/**
 * Import translations from an external source into the database.
 */
function gettext_import($file) {
  // Get the language code from the file.
  $langcode = $file->getLangcode();

  // Set up database connection and set its language.
  $database = new GettextDatabase($langcode);

  // Transfer meta data and translations from the file to the database.
  gettext_transfer($file, $database);
}

/**
 * Example code to export translation data to a po file.
 *
 * Export gettext data to a PO file.
 * The file may be local, remote (via stream wrapper) or even XML.
 * The import has a small memory footprint.
 * The import may be split up to enable batch handling.
 */
  $file = new GettextPoFile('path/to/file/filename.po', $langcode);
  gettext_export($file);

/**
 * Exports translations from the database to a po file.
 */
function gettext_export($file) {
  // Get the language code from the file.
  $langcode = $file->getLangcode();

  // Set up database connection and set its language.
  $database = new GettextDatabase($langcode);

  // Transfer meta data and translations from the database to the file.
  gettext_transfer($database, $file);
}

/**
 * Transfers gettext data from source to target.
 */
function gettext_transfer($source, $target, $langcode) {
  // Transfer translations.
  // Use batch processing if both source and target support it and the source
  // is large enough. If not, process in once.
  if ($source->supportBatch() && $target->supportBatch() && $source->size() > $threshold) {
    // Process in batches
    // Built and execute batch.
    $batch = gettext_transfer_batch_setup($source, $target);
    batch_set($batch);
  }
  else {
    // Process in once.
    foreach($source as $translation)
    $target->set($translation);
  }
}

/**
 * Set up a batch process to transfer Gettext data.
 */
function gettext_transfer_batch_setup($source, $target) {
  $batch = array(
    'operations' => array(
      array('gettext_transfer_batch_op', array($source, $target)),
    ),
    'finished' => 'gettext_transfer_batch_finished',
  );
  return $batch;
}

/**
 * Batch operation transferring gettext data.
 *
 * @todo Add source filter conditions (context, language(?)) as parameter.
 */
function gettext_transfer_batch_op($source, $target) {
  // Initialize sandbox for batch reading.
  if (empty($context['sandbox'])) {
    $context['sandbox']['transfer'] = array(
      'chunk' => min($source->chunkSize(), $target->chunkSize()),
    );
  }

  // Execute one transfer cycle, which will process bite size 'chunks'.
  $success = gettext_transfer_execute($source, $target, $context['sandbox']['transfer']);

  // After a number of cycles executing gettext_transfer_execute() the transfer
  // is completed.
  // See gettextapi_import_batch_op() for details.
  if ($context['sandbox']['transfer']['finished']) {
    $context['finished'] = 1;
    
    if ($success) {
      // Collect statistics from $context['sandbox']['transfer']
      // and tell the world about what great work we did.
    }
  }
}

/**
 * Batch wrap-up for gettext data transfer.
 */
function gettext_transfer_batch_finished($success, $results, $operations) {
  if ($success) {
    // Call post processing handler defined by the target object.
    // Can we get the callback and arguments via $results?
    $post_process_callback = $results['post_process_callback'];
    $arguments = $results['post_process_arguments'];
    $post_process_callback($arguments);

    // We did it, Magoo! :)
  }
  else {
    // Sadly reporting where it went wrong.
  }
}

/**
 * Post processing for gettext language import into the database.
 *
 * To be called after successfull (batch) import.
 */
function gettext_post_process_import($langcode) {
  // After succesfull import we refresh all affected parts of the system.
  _locale_invalidate_js($langcode);
  cache_clear_all('locale:', 'cache', TRUE);
  menu_rebuild();
}

/**
 * Transfer gettext data from source to target in bite size chunks.
 */
function gettext_transfer_execute($source, $target, &$transfer) {
  // If transfer is not yet started we set the header data.
  // The header (if supported) is written before the first translation is written.
  if (!$target->inProgress()) {
    // Transfer translation header data.
    $target->setHeader($source->getHeader(), $langcode);
  }

  $chunk = $transfer['chunk'];
  // Transfer translations as long as valid data is available and
  // the bite size chunk is not yet swallowed.
  while ($source->valid() && $chunk > 0) {
  // Get one translation from source, write it to target.
    $translation = $source->read();
    $target->write($translation);
    $chunk--;
  }

  // Report the percentage of completion for progress reporting.
  // Ai, user interface. Why do we bother ;)
  $transfer['state']['percentage_of_completion'] = $source->poc();

  // Close connections when we are done and report the results.
  if ($source->finished()) {
    $target->finish();
    $transfer['finished'] = TRUE;
  }

  // Report statistics including errors and error log.
  $transfer['result'] = $target->statistics();
}

// Required methods of gettext object
//
// - inProgress(): Return TRUE if the file is opened or the transfer has started.
//
// - errorCallback(): Return the name of an error callback function
// - errorArguments(): Return arguments for an error callback function
// Do we need this for both source and target use of the object?
//
// - postProcessCallback(): Return the name of a post processing callback function
// - postProcessArguments(): Return arguments for a post processing callback function
// Do we need this for both source and target use of the object?
//
// - size(): Return the calculated or estimated size in number of translations. Zero for
//   unknown. To be generated without opening the connection. e.g. use file size
//   not number of lines.
//
// - biteSize() Return a bite size. Based on experience and size to be transfered within
//   a reasonable time. Size in number of source/translations pairs.
//   e.g. database records in locales_source or locales_target tables. A set of
//   plural's are counted as one.
//
// - langcode(): Return the language code as defined by the data (e.g. po header). Use
//   language filter (see below) as fallback.
//
// - setFilter(): Accept a set of data filter arguments: Language, Context
//
// - setWriteMode(): Accept write mode argument (replace, keep changes, skip existing)
//
// - valid(): Return Is valid. Valid data is available, not EOF, no errors, etc.
//
// - Internally log syntax errors
// - Internally log seturn syntax errors
//
// - poc(): Return percentage of completion (read)
//
// - statistics(): Return statistics (added, replaced, ignored, error, error log)
//
// - Internal: pointer where we are reading the content.
// - Internal: open a connection when first data is read or first data is written.
// - Internal: close connection when end of file is reached (reading) or
//
// - read(): Return next translation string (singular or plural)
// - readHeader(): Return header/meta data (language, plural formula)
//
// - write(): Write translation string (singular or plural)
// - writeHeader(): Write header/meta data (language, plural formula, etc.) Use defaults if not specified.