API: Deprecate generatexml of modules revisions/deletedrevisions/parse

Deprecate 'generatexml=' by adding 'prop=parsetree' to revisions,
deletedrevisions and action=parse.
'generatexml' of action=expandtemplates is already deprecated and
replaced by 'prop=parsetree'.

Reason: Api parameter to control the output of a module usually gets
added as type to prop=, not added as new parameter. New parameter
usually used as input parameter for the module.

For revisions and deletedrevisions this allows to get the parsetree
without getting the whole content (makes the result smaller, when just
one is needed)

Change-Id: I7403110d7bd07e9eb2a10e1b398d97f0f40298be

diff --git a/includes/api/ApiParse.php b/includes/api/ApiParse.php
index fa6f30e..577b525 100644 (file)
--- a/includes/api/ApiParse.php
+++ b/includes/api/ApiParse.php
@@ -410,9 +410,12 @@ class ApiParse extends ApiBase {
                        $result_array[ApiResult::META_BC_SUBELEMENTS][] = 'limitreporthtml';
                }
 
-               if ( $params['generatexml'] ) {
+               if ( isset( $prop['parsetree'] ) || $params['generatexml'] ) {
+                       if ( !isset( $prop['parsetree'] ) ) {
+                               $this->logFeatureUsage( 'action=parse&generatexml' );
+                       }
                        if ( $this->content->getModel() != CONTENT_MODEL_WIKITEXT ) {
-                               $this->dieUsage( "generatexml is only supported for wikitext content", "notwikitext" );
+                               $this->dieUsage( "parsetree is only supported for wikitext content", "notwikitext" );
                        }
 
                        $wgParser->startExternalParse( $titleObj, $popts, Parser::OT_PREPROCESS );
@@ -745,8 +748,11 @@ class ApiParse extends ApiBase {
                                        'properties',
                                        'limitreportdata',
                                        'limitreporthtml',
+                                       'parsetree',
+                               ),
+                               ApiBase::PARAM_HELP_MSG_PER_VALUE => array(
+                                       'parsetree' => array( 'apihelp-parse-paramvalue-prop-parsetree', CONTENT_MODEL_WIKITEXT ),
                                ),
-                               ApiBase::PARAM_HELP_MSG_PER_VALUE => array(),
                        ),
                        'pst' => false,
                        'onlypst' => false,
@@ -762,6 +768,7 @@ class ApiParse extends ApiBase {
                                ApiBase::PARAM_HELP_MSG => array(
                                        'apihelp-parse-param-generatexml', CONTENT_MODEL_WIKITEXT
                                ),
+                               ApiBase::PARAM_DEPRECATED => true,
                        ),
                        'preview' => false,
                        'sectionpreview' => false,

diff --git a/includes/api/ApiQueryRevisionsBase.php b/includes/api/ApiQueryRevisionsBase.php
index 64f6120..76da0db 100644 (file)
--- a/includes/api/ApiQueryRevisionsBase.php
+++ b/includes/api/ApiQueryRevisionsBase.php
@@ -37,7 +37,7 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
        protected $fld_ids = false, $fld_flags = false, $fld_timestamp = false,
                $fld_size = false, $fld_sha1 = false, $fld_comment = false,
                $fld_parsedcomment = false, $fld_user = false, $fld_userid = false,
-               $fld_content = false, $fld_tags = false, $fld_contentmodel = false;
+               $fld_content = false, $fld_tags = false, $fld_contentmodel = false, $fld_parsetree = false;
 
        public function execute() {
                $this->run();
@@ -104,6 +104,7 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                $this->fld_userid = isset( $prop['userid'] );
                $this->fld_user = isset( $prop['user'] );
                $this->fld_tags = isset( $prop['tags'] );
+               $this->fld_parsetree = isset( $prop['parsetree'] );
 
                if ( !empty( $params['contentformat'] ) ) {
                        $this->contentFormat = $params['contentformat'];
@@ -112,7 +113,7 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                $this->limit = $params['limit'];
 
                $this->fetchContent = $this->fld_content || !is_null( $this->diffto )
-                       || !is_null( $this->difftotext );
+                       || !is_null( $this->difftotext ) || $this->fld_parsetree;
 
                $smallLimit = false;
                if ( $this->fetchContent ) {
@@ -273,10 +274,11 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                                $vals['textmissing'] = true;
                        }
                }
-               if ( $this->fld_content && $content ) {
-                       $text = null;
-
-                       if ( $this->generateXML ) {
+               if ( $this->fld_parsetree || ( $this->fld_content && $this->generateXML ) ) {
+                       if ( !$this->fld_parsetree ) {
+                               $this->logFeatureUsage( 'action=query&prop=revisions+base&generatexml' );
+                       }
+                       if ( $content ) {
                                if ( $content->getModel() === CONTENT_MODEL_WIKITEXT ) {
                                        $t = $content->getNativeData(); # note: don't set $text
 
@@ -299,6 +301,10 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                                                " uses content model " . $content->getModel() );
                                }
                        }
+               }
+
+               if ( $this->fld_content && $content ) {
+                       $text = null;
 
                        if ( $this->expandTemplates && !$this->parseContent ) {
                                #XXX: implement template expansion for all content types in ContentHandler?
@@ -431,7 +437,8 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                                        'comment',
                                        'parsedcomment',
                                        'content',
-                                       'tags'
+                                       'tags',
+                                       'parsetree',
                                ),
                                ApiBase::PARAM_HELP_MSG => 'apihelp-query+revisions+base-param-prop',
                        ),
@@ -448,6 +455,7 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
                        ),
                        'generatexml' => array(
                                ApiBase::PARAM_DFLT => false,
+                               ApiBase::PARAM_DEPRECATED => true,
                                ApiBase::PARAM_HELP_MSG => 'apihelp-query+revisions+base-param-generatexml',
                        ),
                        'parse' => array(

diff --git a/includes/api/i18n/en.json b/includes/api/i18n/en.json
index 6d1b1ec..3eb2499 100644 (file)
--- a/includes/api/i18n/en.json
+++ b/includes/api/i18n/en.json
@@ -304,6 +304,7 @@
        "apihelp-parse-paramvalue-prop-properties": "Gives various properties defined in the parsed wikitext.",
        "apihelp-parse-paramvalue-prop-limitreportdata": "Gives the limit report in a structured way. Gives no data, when <var>$1disablepp</var> is set.",
        "apihelp-parse-paramvalue-prop-limitreporthtml": "Gives the HTML version of the limit report. Gives no data, when <var>$1disablepp</var> is set.",
+       "apihelp-parse-paramvalue-prop-parsetree": "The XML parse tree of revision content (requires content model <code>$1</code>)",
        "apihelp-parse-param-pst": "Do a pre-save transform on the input before parsing it. Only valid when used with text.",
        "apihelp-parse-param-onlypst": "Do a pre-save transform (PST) on the input, but don't parse it. Returns the same wikitext, after a PST has been applied. Only valid when used with <var>$1text</var>.",
        "apihelp-parse-param-effectivelanglinks": "Includes language links supplied by extensions (for use with <kbd>$1prop=langlinks</kbd>).",
@@ -311,7 +312,7 @@
        "apihelp-parse-param-sectiontitle": "New section title when <var>section</var> is <kbd>new</kbd>.\n\nUnlike page editing, this does not fall back to <var>summary</var> when omitted or empty.",
        "apihelp-parse-param-disablepp": "Disable the PP Report from the parser output.",
        "apihelp-parse-param-disableeditsection": "Disable edit section links from the parser output.",
-       "apihelp-parse-param-generatexml": "Generate XML parse tree (requires content model <code>$1</code>).",
+       "apihelp-parse-param-generatexml": "Generate XML parse tree (requires content model <code>$1</code>; replaced by <kbd>$2prop=parsetree</kbd>).",
        "apihelp-parse-param-preview": "Parse in preview mode.",
        "apihelp-parse-param-sectionpreview": "Parse in section preview mode (enables preview mode too).",
        "apihelp-parse-param-disabletoc": "Disable table of contents in output.",
@@ -887,10 +888,10 @@
        "apihelp-query+revisions-example-first5-after": "Get first 5 revisions of the <kbd>Main Page</kbd> made after 2006-05-01.",
        "apihelp-query+revisions-example-first5-not-localhost": "Get first 5 revisions of the <kbd>Main Page</kbd> that were not made by anonymous user <kbd>127.0.0.1</kbd>.",
        "apihelp-query+revisions-example-first5-user": "Get first 5 revisions of the <kbd>Main Page</kbd> that were made by the user <kbd>MediaWiki default</kbd>.",
-       "apihelp-query+revisions+base-param-prop": "Which properties to get for each revision:\n;ids:The ID of the revision.\n;flags:Revision flags (minor).\n;timestamp:The timestamp of the revision.\n;user:User that made the revision.\n;userid:User ID of the revision creator.\n;size:Length (bytes) of the revision.\n;sha1:SHA-1 (base 16) of the revision.\n;contentmodel:Content model ID of the revision.\n;comment:Comment by the user for the revision.\n;parsedcomment:Parsed comment by the user for the revision.\n;content:Text of the revision.\n;tags:Tags for the revision.",
+       "apihelp-query+revisions+base-param-prop": "Which properties to get for each revision:\n;ids:The ID of the revision.\n;flags:Revision flags (minor).\n;timestamp:The timestamp of the revision.\n;user:User that made the revision.\n;userid:User ID of the revision creator.\n;size:Length (bytes) of the revision.\n;sha1:SHA-1 (base 16) of the revision.\n;contentmodel:Content model ID of the revision.\n;comment:Comment by the user for the revision.\n;parsedcomment:Parsed comment by the user for the revision.\n;content:Text of the revision.\n;tags:Tags for the revision.\n;parsetree:The XML parse tree of revision content.",
        "apihelp-query+revisions+base-param-limit": "Limit how many revisions will be returned.",
        "apihelp-query+revisions+base-param-expandtemplates": "Expand templates in revision content (requires $1prop=content).",
-       "apihelp-query+revisions+base-param-generatexml": "Generate XML parse tree for revision content (requires $1prop=content).",
+       "apihelp-query+revisions+base-param-generatexml": "Generate XML parse tree for revision content (requires $1prop=content; replaced by <kbd>$1prop=parsetree</kbd>).",
        "apihelp-query+revisions+base-param-parse": "Parse revision content (requires $1prop=content). For performance reasons, if this option is used, $1limit is enforced to 1.",
        "apihelp-query+revisions+base-param-section": "Only retrieve the content of this section number.",
        "apihelp-query+revisions+base-param-diffto": "Revision ID to diff each revision to. Use <kbd>prev</kbd>, <kbd>next</kbd> and <kbd>cur</kbd> for the previous, next and current revision respectively.",

diff --git a/includes/api/i18n/qqq.json b/includes/api/i18n/qqq.json
index c436d4f..2fc558e 100644 (file)
--- a/includes/api/i18n/qqq.json
+++ b/includes/api/i18n/qqq.json
@@ -286,6 +286,7 @@
        "apihelp-parse-paramvalue-prop-properties": "{{doc-apihelp-paramvalue|parse|prop|properties}}",
        "apihelp-parse-paramvalue-prop-limitreportdata": "{{doc-apihelp-paramvalue|parse|prop|limitreportdata}}",
        "apihelp-parse-paramvalue-prop-limitreporthtml": "{{doc-apihelp-paramvalue|parse|prop|limitreporthtml}}",
+       "apihelp-parse-paramvalue-prop-parsetree": "{{doc-apihelp-paramvalue|parse|prop|parsetree|params=* $1 - Value of the constant CONTENT_MODEL_WIKITEXT|paramstart=2}}",
        "apihelp-parse-param-pst": "{{doc-apihelp-param|parse|pst}}",
        "apihelp-parse-param-onlypst": "{{doc-apihelp-param|parse|onlypst}}",
        "apihelp-parse-param-effectivelanglinks": "{{doc-apihelp-param|parse|effectivelanglinks}}",