From e684a2178249b1f6a53a539e161a18482a4ef3fd Mon Sep 17 00:00:00 2001 From: Jackmcbarn Date: Mon, 2 Jun 2014 14:53:38 -0400 Subject: [PATCH] Restructure output of ApiExpandTemplates Create a new output format of ApiExpandTemplates and deprecate the old one. Change-Id: Id12cbe4aeaa39bea382cf3b78810589bb1c9368f --- RELEASE-NOTES-1.24 | 2 + includes/api/ApiExpandTemplates.php | 121 +++++++++++++++++++++------- includes/api/ApiFormatXml.php | 9 +++ includes/api/ApiResult.php | 36 +++++++-- 4 files changed, 135 insertions(+), 33 deletions(-) diff --git a/RELEASE-NOTES-1.24 b/RELEASE-NOTES-1.24 index 0389b7c1a5..ea2572bb2b 100644 --- a/RELEASE-NOTES-1.24 +++ b/RELEASE-NOTES-1.24 @@ -93,6 +93,8 @@ production. specified. * action=logevents has a new parameter, lenamespace, to allow filtering by namespace. +* action=expandtemplates has a new parameter, prop, and a new output format. + The old format is still used if prop isn't provided, but this is deprecated. === Languages updated in 1.24 === diff --git a/includes/api/ApiExpandTemplates.php b/includes/api/ApiExpandTemplates.php index 9a472f5318..e3be4e0d29 100644 --- a/includes/api/ApiExpandTemplates.php +++ b/includes/api/ApiExpandTemplates.php @@ -39,6 +39,15 @@ class ApiExpandTemplates extends ApiBase { // Get parameters $params = $this->extractRequestParams(); + $this->requireMaxOneParameter( $params, 'prop', 'generatexml' ); + + if ( $params['prop'] === null ) { + $this->setWarning( 'Because no values have been specified for the prop parameter, a legacy format has been used for the output.' + . ' This format is deprecated, and in the future, a default value will be set for the prop parameter, causing the new format to always be used.' ); + $prop = array(); + } else { + $prop = array_flip( $params['prop'] ); + } // Create title for parser $title_obj = Title::newFromText( $params['title'] ); @@ -56,7 +65,9 @@ class ApiExpandTemplates extends ApiBase { $options->setRemoveComments( false ); } - if ( $params['generatexml'] ) { + $retval = array(); + + if ( isset( $prop['parsetree'] ) || $params['generatexml'] ) { $wgParser->startExternalParse( $title_obj, $options, OT_PREPROCESS ); $dom = $wgParser->preprocessToDom( $params['text'] ); if ( is_callable( array( $dom, 'saveXML' ) ) ) { @@ -64,32 +75,50 @@ class ApiExpandTemplates extends ApiBase { } else { $xml = $dom->__toString(); } - $xml_result = array(); - ApiResult::setContent( $xml_result, $xml ); - $result->addValue( null, 'parsetree', $xml_result ); - } - $frame = $wgParser->getPreprocessor()->newFrame(); - $retval = $wgParser->preprocess( $params['text'], $title_obj, $options, null, $frame ); - $categories = $wgParser->getOutput()->getCategories(); - if ( !empty( $categories ) ) { - $categories_result = array(); - foreach ( $categories as $category => $sortkey ) { - $entry = array(); - $entry['sortkey'] = $sortkey; - ApiResult::setContent( $entry, $category ); - $categories_result[] = $entry; + if ( isset( $prop['parsetree'] ) ) { + unset( $prop['parsetree'] ); + $retval['parsetree'] = $xml; + } else { + // the old way + $xml_result = array(); + ApiResult::setContent( $xml_result, $xml ); + $result->addValue( null, 'parsetree', $xml_result ); } - $result->setIndexedTagName( $categories_result, 'category' ); - $result->addValue( null, 'categories', $categories_result ); } - // Return result - $retval_array = array(); - ApiResult::setContent( $retval_array, $retval ); - if ( $frame->isVolatile() ) { - $retval_array['volatile'] = ''; + // if they didn't want any output except (probably) the parse tree, + // then don't bother actually fully expanding it + if ( $prop || $params['prop'] === null ) { + $frame = $wgParser->getPreprocessor()->newFrame(); + $wikitext = $wgParser->preprocess( $params['text'], $title_obj, $options, null, $frame ); + if ( $params['prop'] === null ) { + // the old way + ApiResult::setContent( $retval, $wikitext ); + } else { + if ( isset( $prop['categories'] ) ) { + $categories = $wgParser->getOutput()->getCategories(); + if ( !empty( $categories ) ) { + $categories_result = array(); + foreach ( $categories as $category => $sortkey ) { + $entry = array(); + $entry['sortkey'] = $sortkey; + ApiResult::setContent( $entry, $category ); + $categories_result[] = $entry; + } + $result->setIndexedTagName( $categories_result, 'category' ); + $retval['categories'] = $categories_result; + } + } + if ( isset ( $prop['volatile'] ) && $frame->isVolatile() ) { + $retval['volatile'] = ''; + } + if ( isset ( $prop['wikitext'] ) ) { + $retval['wikitext'] = $wikitext; + } + } } - $result->addValue( null, $this->getModuleName(), $retval_array ); + $result->setSubelements( $retval, array( 'wikitext', 'parsetree' ) ); + $result->addValue( null, $this->getModuleName(), $retval ); } public function getAllowedParams() { @@ -101,8 +130,20 @@ class ApiExpandTemplates extends ApiBase { ApiBase::PARAM_TYPE => 'string', ApiBase::PARAM_REQUIRED => true, ), - 'generatexml' => false, + 'prop' => array( + ApiBase::PARAM_TYPE => array( + 'wikitext', + 'categories', + 'volatile', + 'parsetree', + ), + ApiBase::PARAM_ISMULTI => true, + ), 'includecomments' => false, + 'generatexml' => array( + ApiBase::PARAM_TYPE => 'boolean', + ApiBase::PARAM_DEPRECATED => true, + ), ); } @@ -110,16 +151,40 @@ class ApiExpandTemplates extends ApiBase { return array( 'text' => 'Wikitext to convert', 'title' => 'Title of page', - 'generatexml' => 'Generate XML parse tree', + 'prop' => array( + 'Which pieces of information to get', + ' wikitext - The expanded wikitext', + ' categories - Any categories present in the input that are not represented in the wikitext output', + ' volatile - Whether the output is volatile and should not be reused elsewhere within the page', + ' parsetree - The XML parse tree of the input', + 'Note that if no values are selected, the result will contain the wikitext,', + 'but the output will be in a deprecated format.', + ), 'includecomments' => 'Whether to include HTML comments in the output', + 'generatexml' => 'Generate XML parse tree (replaced by prop=parsetree)', ); } public function getResultProperties() { return array( - '' => array( - '*' => 'string' - ) + 'wikitext' => array( + 'wikitext' => 'string', + ), + 'categories' => array( + 'categories' => array( + ApiBase::PROP_TYPE => 'array', + ApiBase::PROP_NULLABLE => true, + ), + ), + 'volatile' => array( + 'volatile' => array( + ApiBase::PROP_TYPE => 'boolean', + ApiBase::PROP_NULLABLE => true, + ), + ), + 'parsetree' => array( + 'parsetree' => 'string', + ), ); } diff --git a/includes/api/ApiFormatXml.php b/includes/api/ApiFormatXml.php index 8e1d39d132..b3d5937950 100644 --- a/includes/api/ApiFormatXml.php +++ b/includes/api/ApiFormatXml.php @@ -147,6 +147,15 @@ class ApiFormatXml extends ApiFormatBase { $subElemIndName = null; } + if ( isset( $elemValue['_subelements'] ) ) { + foreach ( $elemValue['_subelements'] as $subElemId ) { + if ( isset( $elemValue[$subElemId] ) && !is_array( $elemValue[$subElemId] ) ) { + $elemValue[$subElemId] = array( '*' => $elemValue[$subElemId] ); + } + } + unset( $elemValue['_subelements'] ); + } + $indElements = array(); $subElements = array(); foreach ( $elemValue as $subElemId => & $subElemValue ) { diff --git a/includes/api/ApiResult.php b/includes/api/ApiResult.php index c351561cd8..2719f123b9 100644 --- a/includes/api/ApiResult.php +++ b/includes/api/ApiResult.php @@ -33,11 +33,13 @@ * 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 */ @@ -211,6 +213,30 @@ 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 -- 2.20.1