Merge branch 'archwiki'

# Conflicts:
#	skins/ArchLinux.php
#	skins/ArchLinux/archlogo.gif

1 files changed, 271 insertions, 43 deletions

diff --git a/includes/api/ApiResult.php b/includes/api/ApiResult.php
index 39c114b8..2e80447e 100644
--- a/includes/api/ApiResult.php
+++ b/includes/api/ApiResult.php
@@ -26,18 +26,20 @@
 
 /**
  * This class represents the result of the API operations.
- * It simply wraps a nested array() structure, adding some functions to simplify array's modifications.
- * As various modules execute, they add different pieces of information to this result,
- * structuring it as it will be given to the client.
+ * It simply wraps a nested array() structure, adding some functions to simplify
+ * array's modifications. As various modules execute, they add different pieces
+ * of information to this result, structuring it as it will be given to the client.
  *
  * Each subarray may either be a dictionary - key-value pairs with unique keys,
  * or lists, where the items are added using $data[] = $value notation.
  *
- * There are two special key values that change how XML output is generated:
- *   '_element' This key sets the tag name for the rest of the elements in the current array.
- *              It is only inserted if the formatter returned true for getNeedsRawData()
- *   '*'        This key has special meaning only to the XML formatter, and is outputted as is
- *              for all others. In XML it becomes the content of the current element.
+ * There are three special key values that change how XML output is generated:
+ *   '_element'     This key sets the tag name for the rest of the elements in the current array.
+ *                  It is only inserted if the formatter returned true for getNeedsRawData()
+ *   '_subelements' This key causes the specified elements to be returned as subelements rather than attributes.
+ *                  It is only inserted if the formatter returned true for getNeedsRawData()
+ *   '*'            This key has special meaning only to the XML formatter, and is outputted as is
+ *                  for all others. In XML it becomes the content of the current element.
  *
  * @ingroup API
  */
@@ -56,13 +58,27 @@ class ApiResult extends ApiBase {
 	 */
 	const ADD_ON_TOP = 2;
 
+	/**
+	 * For addValue() and setElement(), do not check size while adding a value
+	 * Don't use this unless you REALLY know what you're doing.
+	 * Values added while the size checking was disabled will never be counted
+	 * @since 1.24
+	 */
+	const NO_SIZE_CHECK = 4;
+
 	private $mData, $mIsRawMode, $mSize, $mCheckingSize;
 
+	private $continueAllModules = array();
+	private $continueGeneratedModules = array();
+	private $continuationData = array();
+	private $generatorContinuationData = array();
+	private $generatorParams = array();
+	private $generatorDone = false;
+
 	/**
-	 * Constructor
-	 * @param $main ApiMain object
+	 * @param ApiMain $main
 	 */
-	public function __construct( $main ) {
+	public function __construct( ApiMain $main ) {
 		parent::__construct( $main, 'result' );
 		$this->mIsRawMode = false;
 		$this->mCheckingSize = true;
@@ -80,9 +96,11 @@ class ApiResult extends ApiBase {
 	/**
 	 * Call this function when special elements such as '_element'
 	 * are needed by the formatter, for example in XML printing.
+	 * @since 1.23 $flag parameter added
+	 * @param bool $flag Set the raw mode flag to this state
 	 */
-	public function setRawMode() {
-		$this->mIsRawMode = true;
+	public function setRawMode( $flag = true ) {
+		$this->mIsRawMode = $flag;
 	}
 
 	/**
@@ -104,7 +122,7 @@ class ApiResult extends ApiBase {
 	/**
 	 * Get the 'real' size of a result item. This means the strlen() of the item,
 	 * or the sum of the strlen()s of the elements if the item is an array.
-	 * @param $value mixed
+	 * @param mixed $value
 	 * @return int
 	 */
 	public static function size( $value ) {
@@ -117,6 +135,7 @@ class ApiResult extends ApiBase {
 			// Objects can't always be cast to string
 			$s = strlen( $value );
 		}
+
 		return $s;
 	}
 
@@ -132,6 +151,7 @@ class ApiResult extends ApiBase {
 	 * Disable size checking in addValue(). Don't use this unless you
 	 * REALLY know what you're doing. Values added while size checking
 	 * was disabled will not be counted (ever)
+	 * @deprecated since 1.24, use ApiResult::NO_SIZE_CHECK
 	 */
 	public function disableSizeCheck() {
 		$this->mCheckingSize = false;
@@ -139,6 +159,7 @@ class ApiResult extends ApiBase {
 
 	/**
 	 * Re-enable size checking in addValue()
+	 * @deprecated since 1.24, use ApiResult::NO_SIZE_CHECK
 	 */
 	public function enableSizeCheck() {
 		$this->mCheckingSize = true;
@@ -147,17 +168,20 @@ class ApiResult extends ApiBase {
 	/**
 	 * Add an output value to the array by name.
 	 * Verifies that value with the same name has not been added before.
-	 * @param array $arr to add $value to
+	 * @param array $arr To add $value to
 	 * @param string $name Index of $arr to add $value at
-	 * @param $value mixed
-	 * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. This parameter used to be
-	 *        boolean, and the value of OVERRIDE=1 was specifically chosen so that it would be backwards
-	 *        compatible with the new method signature.
+	 * @param mixed $value
+	 * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
+	 *    This parameter used to be boolean, and the value of OVERRIDE=1 was
+	 *    specifically chosen so that it would be backwards compatible with the
+	 *    new method signature.
 	 *
 	 * @since 1.21 int $flags replaced boolean $override
 	 */
 	public static function setElement( &$arr, $name, $value, $flags = 0 ) {
-		if ( $arr === null || $name === null || $value === null || !is_array( $arr ) || is_array( $name ) ) {
+		if ( $arr === null || $name === null || $value === null
+			|| !is_array( $arr ) || is_array( $name )
+		) {
 			ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
 		}
 
@@ -176,16 +200,19 @@ class ApiResult extends ApiBase {
 				ApiBase::dieDebug( __METHOD__, "Attempting to merge element $name" );
 			}
 		} else {
-			ApiBase::dieDebug( __METHOD__, "Attempting to add element $name=$value, existing value is {$arr[$name]}" );
+			ApiBase::dieDebug(
+				__METHOD__,
+				"Attempting to add element $name=$value, existing value is {$arr[$name]}"
+			);
 		}
 	}
 
 	/**
 	 * Adds a content element to an array.
 	 * Use this function instead of hardcoding the '*' element.
-	 * @param array $arr to add the content element to
-	 * @param $value Mixed
-	 * @param string $subElemName when present, content element is created
+	 * @param array $arr To add the content element to
+	 * @param mixed $value
+	 * @param string $subElemName When present, content element is created
 	 *  as a sub item of $arr. Use this parameter to create elements in
 	 *  format "<elem>text</elem>" without attributes.
 	 */
@@ -204,10 +231,34 @@ class ApiResult extends ApiBase {
 	}
 
 	/**
+	 * Causes the elements with the specified names to be output as
+	 * subelements rather than attributes.
+	 * @param array $arr
+	 * @param array|string $names The element name(s) to be output as subelements
+	 */
+	public function setSubelements( &$arr, $names ) {
+		// In raw mode, add the '_subelements', otherwise just ignore
+		if ( !$this->getIsRawMode() ) {
+			return;
+		}
+		if ( $arr === null || $names === null || !is_array( $arr ) ) {
+			ApiBase::dieDebug( __METHOD__, 'Bad parameter' );
+		}
+		if ( !is_array( $names ) ) {
+			$names = array( $names );
+		}
+		if ( !isset( $arr['_subelements'] ) ) {
+			$arr['_subelements'] = $names;
+		} else {
+			$arr['_subelements'] = array_merge( $arr['_subelements'], $names );
+		}
+	}
+
+	/**
 	 * In case the array contains indexed values (in addition to named),
 	 * give all indexed values the given tag name. This function MUST be
 	 * called on every array that has numerical indexes.
-	 * @param $arr array
+	 * @param array $arr
 	 * @param string $tag Tag name
 	 */
 	public function setIndexedTagName( &$arr, $tag ) {
@@ -224,7 +275,7 @@ class ApiResult extends ApiBase {
 
 	/**
 	 * Calls setIndexedTagName() on each sub-array of $arr
-	 * @param $arr array
+	 * @param array $arr
 	 * @param string $tag Tag name
 	 */
 	public function setIndexedTagName_recursive( &$arr, $tag ) {
@@ -245,7 +296,7 @@ class ApiResult extends ApiBase {
 	 * Don't specify a path to a value that's not in the result, or
 	 * you'll get nasty errors.
 	 * @param array $path Path to the array, like addValue()'s $path
-	 * @param $tag string
+	 * @param string $tag
 	 */
 	public function setIndexedTagName_internal( $path, $tag ) {
 		$data = &$this->mData;
@@ -268,26 +319,26 @@ class ApiResult extends ApiBase {
 	 * If $path is null, the value will be inserted at the data root.
 	 * If $name is empty, the $value is added as a next list element data[] = $value.
 	 *
-	 * @param $path array|string|null
-	 * @param $name string
-	 * @param $value mixed
-	 * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP. This parameter used to be
-	 *        boolean, and the value of OVERRIDE=1 was specifically chosen so that it would be backwards
-	 *        compatible with the new method signature.
+	 * @param array|string|null $path
+	 * @param string $name
+	 * @param mixed $value
+	 * @param int $flags Zero or more OR-ed flags like OVERRIDE | ADD_ON_TOP.
+	 *   This parameter used to be boolean, and the value of OVERRIDE=1 was specifically
+	 *   chosen so that it would be backwards compatible with the new method signature.
 	 * @return bool True if $value fits in the result, false if not
 	 *
 	 * @since 1.21 int $flags replaced boolean $override
 	 */
 	public function addValue( $path, $name, $value, $flags = 0 ) {
-		global $wgAPIMaxResultSize;
-
 		$data = &$this->mData;
-		if ( $this->mCheckingSize ) {
+		if ( $this->mCheckingSize && !( $flags & ApiResult::NO_SIZE_CHECK ) ) {
 			$newsize = $this->mSize + self::size( $value );
-			if ( $newsize > $wgAPIMaxResultSize ) {
+			$maxResultSize = $this->getConfig()->get( 'APIMaxResultSize' );
+			if ( $newsize > $maxResultSize ) {
 				$this->setWarning(
 					"This result was truncated because it would otherwise be larger than the " .
-							"limit of {$wgAPIMaxResultSize} bytes" );
+						"limit of {$maxResultSize} bytes" );
+
 				return false;
 			}
 			$this->mSize = $newsize;
@@ -322,14 +373,15 @@ class ApiResult extends ApiBase {
 			// Add named element
 			self::setElement( $data, $name, $value, $flags );
 		}
+
 		return true;
 	}
 
 	/**
 	 * Add a parsed limit=max to the result.
 	 *
-	 * @param $moduleName string
-	 * @param $limit int
+	 * @param string $moduleName
+	 * @param int $limit
 	 */
 	public function setParsedLimit( $moduleName, $limit ) {
 		// Add value, allowing overwriting
@@ -340,8 +392,8 @@ class ApiResult extends ApiBase {
 	 * Unset a value previously added to the result set.
 	 * Fails silently if the value isn't found.
 	 * For parameters, see addValue()
-	 * @param $path array|null
-	 * @param $name string
+	 * @param array|null $path
+	 * @param string $name
 	 */
 	public function unsetValue( $path, $name ) {
 		$data = &$this->mData;
@@ -367,7 +419,7 @@ class ApiResult extends ApiBase {
 	/**
 	 * Callback function for cleanUpUTF8()
 	 *
-	 * @param $s string
+	 * @param string $s
 	 */
 	private static function cleanUp_helper( &$s ) {
 		if ( !is_string( $s ) ) {
@@ -394,10 +446,186 @@ class ApiResult extends ApiBase {
 			$result[] = $error;
 		}
 		$this->setIndexedTagName( $result, $errorType );
+
 		return $result;
 	}
 
 	public function execute() {
 		ApiBase::dieDebug( __METHOD__, 'execute() is not supported on Result object' );
 	}
+
+	/**
+	 * Parse a 'continue' parameter and return status information.
+	 *
+	 * This must be balanced by a call to endContinuation().
+	 *
+	 * @since 1.24
+	 * @param string|null $continue The "continue" parameter, if any
+	 * @param ApiBase[] $allModules Contains ApiBase instances that will be executed
+	 * @param array $generatedModules Names of modules that depend on the generator
+	 * @return array Two elements: a boolean indicating if the generator is done,
+	 *   and an array of modules to actually execute.
+	 */
+	public function beginContinuation(
+		$continue, array $allModules = array(), array $generatedModules = array()
+	) {
+		$this->continueGeneratedModules = $generatedModules
+			? array_combine( $generatedModules, $generatedModules )
+			: array();
+		$this->continuationData = array();
+		$this->generatorContinuationData = array();
+		$this->generatorParams = array();
+
+		$skip = array();
+		if ( is_string( $continue ) && $continue !== '' ) {
+			$continue = explode( '||', $continue );
+			$this->dieContinueUsageIf( count( $continue ) !== 2 );
+			$this->generatorDone = ( $continue[0] === '-' );
+			if ( !$this->generatorDone ) {
+				$this->generatorParams = explode( '|', $continue[0] );
+			}
+			$skip = explode( '|', $continue[1] );
+		}
+
+		$this->continueAllModules = array();
+		$runModules = array();
+		foreach ( $allModules as $module ) {
+			$name = $module->getModuleName();
+			if ( in_array( $name, $skip ) ) {
+				$this->continueAllModules[$name] = false;
+				// Prevent spurious "unused parameter" warnings
+				$module->extractRequestParams();
+			} else {
+				$this->continueAllModules[$name] = true;
+				$runModules[] = $module;
+			}
+		}
+
+		return array(
+			$this->generatorDone,
+			$runModules,
+		);
+	}
+
+	/**
+	 * Set the continuation parameter for a module
+	 *
+	 * @since 1.24
+	 * @param ApiBase $module
+	 * @param string $paramName
+	 * @param string|array $paramValue
+	 */
+	public function setContinueParam( ApiBase $module, $paramName, $paramValue ) {
+		$name = $module->getModuleName();
+		if ( !isset( $this->continueAllModules[$name] ) ) {
+			throw new MWException(
+				"Module '$name' called ApiResult::setContinueParam but was not " .
+				'passed to ApiResult::beginContinuation'
+			);
+		}
+		if ( !$this->continueAllModules[$name] ) {
+			throw new MWException(
+				"Module '$name' was not supposed to have been executed, but " .
+				'it was executed anyway'
+			);
+		}
+		$paramName = $module->encodeParamName( $paramName );
+		if ( is_array( $paramValue ) ) {
+			$paramValue = join( '|', $paramValue );
+		}
+		$this->continuationData[$name][$paramName] = $paramValue;
+	}
+
+	/**
+	 * Set the continuation parameter for the generator module
+	 *
+	 * @since 1.24
+	 * @param ApiBase $module
+	 * @param string $paramName
+	 * @param string|array $paramValue
+	 */
+	public function setGeneratorContinueParam( ApiBase $module, $paramName, $paramValue ) {
+		$name = $module->getModuleName();
+		$paramName = $module->encodeParamName( $paramName );
+		if ( is_array( $paramValue ) ) {
+			$paramValue = join( '|', $paramValue );
+		}
+		$this->generatorContinuationData[$name][$paramName] = $paramValue;
+	}
+
+	/**
+	 * Close continuation, writing the data into the result
+	 *
+	 * @since 1.24
+	 * @param string $style 'standard' for the new style since 1.21, 'raw' for
+	 *   the style used in 1.20 and earlier.
+	 */
+	public function endContinuation( $style = 'standard' ) {
+		if ( $style === 'raw' ) {
+			$key = 'query-continue';
+			$data = array_merge_recursive(
+				$this->continuationData, $this->generatorContinuationData
+			);
+		} else {
+			$key = 'continue';
+			$data = array();
+
+			$finishedModules = array_diff(
+				array_keys( $this->continueAllModules ),
+				array_keys( $this->continuationData )
+			);
+
+			// First, grab the non-generator-using continuation data
+			$continuationData = array_diff_key(
+				$this->continuationData, $this->continueGeneratedModules
+			);
+			foreach ( $continuationData as $module => $kvp ) {
+				$data += $kvp;
+			}
+
+			// Next, handle the generator-using continuation data
+			$continuationData = array_intersect_key(
+				$this->continuationData, $this->continueGeneratedModules
+			);
+			if ( $continuationData ) {
+				// Some modules are unfinished: include those params, and copy
+				// the generator params.
+				foreach ( $continuationData as $module => $kvp ) {
+					$data += $kvp;
+				}
+				$data += array_intersect_key(
+					$this->getMain()->getRequest()->getValues(),
+					array_flip( $this->generatorParams )
+				);
+			} elseif ( $this->generatorContinuationData ) {
+				// All the generator-using modules are complete, but the
+				// generator isn't. Continue the generator and restart the
+				// generator-using modules
+				$this->generatorParams = array();
+				foreach ( $this->generatorContinuationData as $kvp ) {
+					$this->generatorParams = array_merge(
+						$this->generatorParams, array_keys( $kvp )
+					);
+					$data += $kvp;
+				}
+				$finishedModules = array_diff(
+					$finishedModules, $this->continueGeneratedModules
+				);
+			} else {
+				// Generator and prop modules are all done. Mark it so.
+				$this->generatorDone = true;
+			}
+
+			// Set 'continue' if any continuation data is set or if the generator
+			// still needs to run
+			if ( $data || !$this->generatorDone ) {
+				$data['continue'] =
+					( $this->generatorDone ? '-' : join( '|', $this->generatorParams ) ) .
+					'||' . join( '|', $finishedModules );
+			}
+		}
+		if ( $data ) {
+			$this->addValue( null, $key, $data, ApiResult::ADD_ON_TOP | ApiResult::NO_SIZE_CHECK );
+		}
+	}
 }