// 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'] );
$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' ) ) ) {
} 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() {
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,
+ ),
);
}
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',
+ ),
);
}
* 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
*/
}
}
+ /**
+ * 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