Restructure output of ApiExpandTemplates

Create a new output format of ApiExpandTemplates and deprecate the old
one.

Change-Id: Id12cbe4aeaa39bea382cf3b78810589bb1c9368f

diff --git a/RELEASE-NOTES-1.24 b/RELEASE-NOTES-1.24
index 0389b7c..ea2572b 100644 (file)
--- 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 9a472f5..e3be4e0 100644 (file)
--- 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 8e1d39d..b3d5937 100644 (file)
--- 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 c351561..2719f12 100644 (file)
--- 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