Inline docs for wp-diff.php. Props jacobsantos. fixes #7662

git-svn-id: http://svn.automattic.com/wordpress/trunk@8866 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
ryan 2008-09-11 17:46:42 +00:00
parent 231d08add2
commit 68f9ff53b9
1 changed files with 170 additions and 17 deletions

View File

@ -1,55 +1,144 @@
<?php <?php
/**
* WordPress Diff bastard child of old MediaWiki Diff Formatter.
*
* Basically all that remains is the table structure and some method names.
*
* @package WordPress
* @subpackage Diff
*/
if ( !class_exists( 'Text_Diff' ) ) { if ( !class_exists( 'Text_Diff' ) ) {
/** Text_Diff class */
require( dirname(__FILE__).'/Text/Diff.php' ); require( dirname(__FILE__).'/Text/Diff.php' );
/** Text_Diff_Renderer class */
require( dirname(__FILE__).'/Text/Diff/Renderer.php' ); require( dirname(__FILE__).'/Text/Diff/Renderer.php' );
/** Text_Diff_Renderer_inline class */
require( dirname(__FILE__).'/Text/Diff/Renderer/inline.php' ); require( dirname(__FILE__).'/Text/Diff/Renderer/inline.php' );
} }
/**
/* Descendent of a bastard child of piece of an old MediaWiki Diff Formatter * Table renderer to display the diff lines.
* *
* Basically all that remains is the table structure and some method names. * @since 2.6.0
* @uses Text_Diff_Renderer Extends
*/ */
class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer { class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
/**
* @see Text_Diff_Renderer::_leading_context_lines
* @var int
* @access protected
* @since 2.6.0
*/
var $_leading_context_lines = 10000; var $_leading_context_lines = 10000;
/**
* @see Text_Diff_Renderer::_trailing_context_lines
* @var int
* @access protected
* @since 2.6.0
*/
var $_trailing_context_lines = 10000; var $_trailing_context_lines = 10000;
/**
* {@internal Missing Description}}
*
* @var float
* @access protected
* @since 2.6.0
*/
var $_diff_threshold = 0.6; var $_diff_threshold = 0.6;
/**
* Inline display helper object name.
*
* @var string
* @access protected
* @since 2.6.0
*/
var $inline_diff_renderer = 'WP_Text_Diff_Renderer_inline'; var $inline_diff_renderer = 'WP_Text_Diff_Renderer_inline';
/**
* PHP4 Constructor - Call parent constructor with params array.
*
* This will set class properties based on the key value pairs in the array.
*
* @since unknown
*
* @param array $params
*/
function Text_Diff_Renderer_Table( $params = array() ) { function Text_Diff_Renderer_Table( $params = array() ) {
$parent = get_parent_class($this); $parent = get_parent_class($this);
$this->$parent( $params ); $this->$parent( $params );
} }
/**
* @ignore
*
* @param string $header
* @return string
*/
function _startBlock( $header ) { function _startBlock( $header ) {
return ''; return '';
} }
/**
* @ignore
*
* @param array $lines
* @param string $prefix
*/
function _lines( $lines, $prefix=' ' ) { function _lines( $lines, $prefix=' ' ) {
} }
// HTML-escape parameter before calling this /**
* @ignore
*
* @param string $line HTML-escape the value.
* @return string
*/
function addedLine( $line ) { function addedLine( $line ) {
return "<td>+</td><td class='diff-addedline'>{$line}</td>"; return "<td>+</td><td class='diff-addedline'>{$line}</td>";
} }
// HTML-escape parameter before calling this /**
* @ignore
*
* @param string $line HTML-escape the value.
* @return string
*/
function deletedLine( $line ) { function deletedLine( $line ) {
return "<td>-</td><td class='diff-deletedline'>{$line}</td>"; return "<td>-</td><td class='diff-deletedline'>{$line}</td>";
} }
// HTML-escape parameter before calling this /**
* @ignore
*
* @param string $line HTML-escape the value.
* @return string
*/
function contextLine( $line ) { function contextLine( $line ) {
return "<td> </td><td class='diff-context'>{$line}</td>"; return "<td> </td><td class='diff-context'>{$line}</td>";
} }
/**
* @ignore
*
* @return string
*/
function emptyLine() { function emptyLine() {
return '<td colspan="2">&nbsp;</td>'; return '<td colspan="2">&nbsp;</td>';
} }
/**
* @ignore
* @access private
*
* @param array $lines
* @param bool $encode
* @return string
*/
function _added( $lines, $encode = true ) { function _added( $lines, $encode = true ) {
$r = ''; $r = '';
foreach ($lines as $line) { foreach ($lines as $line) {
@ -60,6 +149,14 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
return $r; return $r;
} }
/**
* @ignore
* @access private
*
* @param array $lines
* @param bool $encode
* @return string
*/
function _deleted( $lines, $encode = true ) { function _deleted( $lines, $encode = true ) {
$r = ''; $r = '';
foreach ($lines as $line) { foreach ($lines as $line) {
@ -70,6 +167,14 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
return $r; return $r;
} }
/**
* @ignore
* @access private
*
* @param array $lines
* @param bool $encode
* @return string
*/
function _context( $lines, $encode = true ) { function _context( $lines, $encode = true ) {
$r = ''; $r = '';
foreach ($lines as $line) { foreach ($lines as $line) {
@ -81,9 +186,19 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
return $r; return $r;
} }
// Process changed lines to do word-by-word diffs for extra highlighting (TRAC style) /**
// sometimes these lines can actually be deleted or added rows - we do additional processing * Process changed lines to do word-by-word diffs for extra highlighting.
// to figure that out *
* (TRAC style) sometimes these lines can actually be deleted or added rows.
* We do additional processing to figure that out
*
* @access private
* @since 2.6.0
*
* @param array $orig
* @param array $final
* @return string
*/
function _changed( $orig, $final ) { function _changed( $orig, $final ) {
$r = ''; $r = '';
@ -151,10 +266,20 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
return $r; return $r;
} }
// Takes changed blocks and matches which rows in orig turned into which rows in final. /**
// Returns * Takes changed blocks and matches which rows in orig turned into which rows in final.
// *_matches ( which rows match with which ) *
// *_rows ( order of rows in each column interleaved with blank rows as necessary ) * Returns
* *_matches ( which rows match with which )
* *_rows ( order of rows in each column interleaved with blank rows as
* necessary )
*
* @since 2.6.0
*
* @param unknown_type $orig
* @param unknown_type $final
* @return unknown
*/
function interleave_changed_lines( $orig, $final ) { function interleave_changed_lines( $orig, $final ) {
// Contains all pairwise string comparisons. Keys are such that this need only be a one dimensional array. // Contains all pairwise string comparisons. Keys are such that this need only be a one dimensional array.
@ -279,8 +404,15 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
*/ */
} }
/**
// Computes a number that is intended to reflect the "distance" between two strings. * Computes a number that is intended to reflect the "distance" between two strings.
*
* @since 2.6.0
*
* @param string $string1
* @param string $string2
* @return int
*/
function compute_string_distance( $string1, $string2 ) { function compute_string_distance( $string1, $string2 ) {
// Vectors containing character frequency for all chars in each string // Vectors containing character frequency for all chars in each string
$chars1 = count_chars($string1); $chars1 = count_chars($string1);
@ -297,15 +429,36 @@ class WP_Text_Diff_Renderer_Table extends Text_Diff_Renderer {
return $difference / strlen($string1); return $difference / strlen($string1);
} }
/**
* @ignore
* @since 2.6.0
*
* @param int $a
* @param int $b
* @return int
*/
function difference( $a, $b ) { function difference( $a, $b ) {
return abs( $a - $b ); return abs( $a - $b );
} }
} }
// Better word splitting than the PEAR package provides /**
* Better word splitting than the PEAR package provides.
*
* @since 2.6.0
* @uses Text_Diff_Renderer_inline Extends
*/
class WP_Text_Diff_Renderer_inline extends Text_Diff_Renderer_inline { class WP_Text_Diff_Renderer_inline extends Text_Diff_Renderer_inline {
/**
* @ignore
* @since 2.6.0
*
* @param string $string
* @param string $newlineEscape
* @return string
*/
function _splitOnWords($string, $newlineEscape = "\n") { function _splitOnWords($string, $newlineEscape = "\n") {
$string = str_replace("\0", '', $string); $string = str_replace("\0", '', $string);
$words = preg_split( '/([^\w])/u', $string, -1, PREG_SPLIT_DELIM_CAPTURE ); $words = preg_split( '/([^\w])/u', $string, -1, PREG_SPLIT_DELIM_CAPTURE );