Adding xml output to HelpFormatter.

cakephp · Oct 20, 2010 · ad62e0e · ad62e0e
1 parent 52a4944
commit ad62e0e
Show file tree

Hide file tree

Showing 5 changed files with 298 additions and 4 deletions.
diff --git a/cake/console/libs/console_input_argument.php b/cake/console/libs/console_input_argument.php
@@ -123,4 +123,22 @@ public function validChoice($value) {
 		}
 		return true;
 	}
+
+/**
+ * Append this argument to the passed in SimpleXml object.
+ *
+ * @param SimpleXmlElement The parent element.
+ * @return SimpleXmlElement The parent with this argument appended.
+ */
+	public function xml(SimpleXmlElement $parent) {
+		$option = $parent->addChild('argument');
+		$option->addAttribute('name', $this->_name);
+		$option->addAttribute('help', $this->_help);
+		$option->addAttribute('required', $this->isRequired());
+		$choices = $option->addChild('choices');
+		foreach ($this->_choices as $valid) {
+			$choices->addChild('choice', $valid);
+		}
+		return $parent;
+	}
 }
diff --git a/cake/console/libs/console_input_option.php b/cake/console/libs/console_input_option.php
@@ -140,4 +140,27 @@ public function validChoice($value) {
 		}
 		return true;
 	}
+
+/**
+ * Append the option's xml into the parent.
+ *
+ * @param SimpleXmlElement The parent element.
+ * @return SimpleXmlElement The parent with this option appended.
+ */
+	public function xml(SimpleXmlElement $parent) {
+		$option = $parent->addChild('option');
+		$option->addAttribute('name', '--' . $this->_name);
+		$short = '';
+		if (strlen($this->_short)) {
+			$short = $this->_short;
+		}
+		$option->addAttribute('short', '-' . $short);
+		$option->addAttribute('boolean', $this->_boolean);
+		$option->addChild('default', $this->_default);
+		$choices = $option->addChild('choices');
+		foreach ($this->_choices as $valid) {
+			$choices->addChild('choice', $valid);
+		}
+		return $parent;
+	}
 }
diff --git a/cake/console/libs/console_input_subcommand.php b/cake/console/libs/console_input_subcommand.php
@@ -89,4 +89,17 @@ public function parser() {
 		}
 		return false;
 	}
+
+/**
+ * Append this subcommand to the Parent element
+ *
+ * @param SimpleXmlElement The parent element.
+ * @return SimpleXmlElement The parent with this subcommand appended.
+ */
+	public function xml(SimpleXmlElement $parent) {
+		$command = $parent->addChild('command');
+		$command->addAttribute('name', $this->_name);
+		$command->addAttribute('help', $this->_help);
+		return $parent;
+	}
 }
diff --git a/cake/console/libs/help_formatter.php b/cake/console/libs/help_formatter.php
@@ -1,7 +1,6 @@
 <?php
 /**
- * A class to format help for console shells.  Can format to either
- * text or XML formats
+ * HelpFormatter
  *
  * PHP 5
  *
@@ -18,6 +17,16 @@
  * @since         CakePHP(tm) v 2.0
  * @license       MIT License (http://www.opensource.org/licenses/mit-license.php)
  */
+/**
+ * HelpFormatter formats help for console shells.  Can format to either
+ * text or XML formats.  Uses ConsoleOptionParser methods to generate help.
+ *
+ * Generally not directly used. Using $parser->help($command, 'xml'); is usually
+ * how you would access help.  Or via the `--help=xml` option on the command line.
+ *
+ * Xml output is useful for intergration with other tools like IDE's or other build tools.
+ *
+ */
 class HelpFormatter {
 /**
  * Build the help formatter for a an OptionParser
@@ -140,9 +149,28 @@ protected function _getMaxLength($collection) {
 /**
  * Get the help as an xml string.
  *
- * @return string
+ * @param boolean $string Return the SimpleXml object or a string.  Defaults to true.
+ * @return mixed. See $string
  */
-	public function xml() {
+	public function xml($string = false) {
+		$parser = $this->_parser;
+		$xml = new SimpleXmlElement('<shell></shell>');
+		$xml->addChild('commmand', $parser->command());
+		$xml->addChild('description', $parser->description());
 
+		$xml->addChild('epilog', $parser->epilog());
+		$subcommands = $xml->addChild('subcommands');
+		foreach ($parser->subcommands() as $command) {
+			$command->xml($subcommands);
+		}
+		$options = $xml->addChild('options');
+		foreach ($parser->options() as $option) {
+			$option->xml($options);
+		}
+		$arguments = $xml->addChild('arguments');
+		foreach ($parser->arguments() as $argument) {
+			$argument->xml($arguments);
+		}
+		return $xml->asXml();
 	}
 }
diff --git a/cake/tests/cases/console/libs/help_formatter.test.php b/cake/tests/cases/console/libs/help_formatter.test.php
@@ -209,4 +209,216 @@ function testHelpWithOptionsAndArguments() {
 TEXT;
 		$this->assertEquals($expected, $result, 'Help does not match');
 	}
+
+/**
+ * test help() with options and arguments that have choices.
+ *
+ * @return void
+ */
+	function testXmlHelpWithChoices() {
+		$parser = new ConsoleOptionParser('mycommand', false);
+		$parser->addOption('test', array('help' => 'A test option.', 'choices' => array('one', 'two')))
+			->addArgument('type', array(
+				'help' => 'Resource type.',
+				'choices' => array('aco', 'aro'),
+				'required' => true
+			))
+			->addArgument('other_longer', array('help' => 'Another argument.'));
+
+		$formatter = new HelpFormatter($parser);
+		$result = $formatter->xml();
+		$expected = <<<TEXT
+<?xml version="1.0"?>
+<shell>
+<name>mycommand</name>
+<description>Description text</description>
+<subcommands />
+<options>
+	<option name="--help" short="-h" help="Display this help." boolean="1">
+		<default></default>
+		<choices></choices>
+	</option>
+	<option name="--test" short="" help="A test option." boolean="0">
+		<default></default>
+		<choices>
+			<choice>one</choice>
+			<choice>two</choice>
+		</choices>
+	</option>
+</options>
+<arguments>
+	<argument name="type" help="Resource type." required="1">
+		<choices>
+			<choice>aco</choice>
+			<choice>aro</choice>
+		</choices>
+	</argument>
+</arguments>
+<epilog>epilog text</epilog>
+</shell>
+TEXT;
+		$this->assertEquals(new DomDocument($expected), new DomDocument($result), 'Help does not match');
+	}
+
+/**
+ * test description and epilog in the help
+ *
+ * @return void
+ */
+	function testXmlHelpDescriptionAndEpilog() {
+		$parser = new ConsoleOptionParser('mycommand', false);
+		$parser->description('Description text')
+			->epilog('epilog text')
+			->addOption('test', array('help' => 'A test option.'))
+			->addArgument('model', array('help' => 'The model to make.', 'required' => true));
+
+		$formatter = new HelpFormatter($parser);
+		$result = $formatter->xml();
+		$expected = <<<TEXT
+<?xml version="1.0"?>
+<shell>
+<name>mycommand</name>
+<description>Description text</description>
+<subcommands />
+<options>
+	<option name="--help" short="-h" help="Display this help." boolean="1">
+		<default></default>
+		<choices></choices>
+	</option>
+	<option name="--test" short="" help="A test option." boolean="0">
+		<default></default>
+		<choices></choices>
+	</option>
+</options>
+<arguments>
+	<argument name="model" help="The model to make." required="1">
+		<choices></choices>
+	</argument>
+</arguments>
+<epilog>epilog text</epilog>
+</shell>
+TEXT;
+		$this->assertEquals(new DomDocument($expected), new DomDocument($result), 'Help does not match');
+	}
+
+/**
+ * test that help() outputs subcommands.
+ *
+ * @return void
+ */
+	function testXmlHelpSubcommand() {
+		$parser = new ConsoleOptionParser('mycommand', false);
+		$parser->addSubcommand('method', array('help' => 'This is another command'))
+			->addOption('test', array('help' => 'A test option.'));
+
+		$formatter = new HelpFormatter($parser);
+		$result = $formatter->xml();
+		$expected = <<<TEXT
+<?xml version="1.0"?>
+<shell>
+<name>mycommand</name>
+<description/>
+<subcommands>
+	<command name="method" help="This is another command" />
+</subcommands>
+<options>
+	<option name="--help" short="-h" help="Display this help." boolean="1">
+		<default></default>
+		<choices></choices>
+	</option>
+	<option name="--test" short="" help="A test option." boolean="0">
+		<default></default>
+		<choices></choices>
+	</option>
+</options>
+<arguments/>
+<epilog/>
+</shell>
+TEXT;
+		$this->assertEquals(new DomDocument($expected), new DomDocument($result), 'Help does not match');
+	}
+
+/**
+ * test getting help with defined options.
+ *
+ * @return void
+ */
+	function testXmlHelpWithOptions() {
+		$parser = new ConsoleOptionParser('mycommand', false);
+		$parser->addOption('test', array('help' => 'A test option.'))
+			->addOption('connection', array(
+				'short' => 'c', 'help' => 'The connection to use.', 'default' => 'default'
+			));
+
+		$formatter = new HelpFormatter($parser);
+		$result = $formatter->xml();
+		$expected = <<<TEXT
+<?xml version="1.0"?>
+<shell>
+<name>mycommand</name>
+<description/>
+<subcommands/>
+<options>
+	<option name="--help" short="-h" help="Display this help." boolean="1">
+		<default></default>
+		<choices></choices>
+	</option>
+	<option name="--test" short="" help="A test option." boolean="0">
+		<default></default>
+		<choices></choices>
+	</option>
+	<option name="--connection" short="-c" help="The connection to use." boolean="0">
+		<default>default</default>
+		<choices></choices>
+	</option>
+</options>
+<arguments/>
+<epilog/>
+</shell>
+TEXT;
+		$this->assertEquals(new DomDocument($expected), new DomDocument($result), 'Help does not match');
+	}
+
+/**
+ * test getting help with defined options.
+ *
+ * @return void
+ */
+	function testXmlHelpWithOptionsAndArguments() {
+		$parser = new ConsoleOptionParser('mycommand', false);
+		$parser->addOption('test', array('help' => 'A test option.'))
+			->addArgument('model', array('help' => 'The model to make.', 'required' => true))
+			->addArgument('other_longer', array('help' => 'Another argument.'));
+
+		$formatter = new HelpFormatter($parser);
+		$result = $formatter->xml();
+		$expected = <<<TEXT
+<?xml version="1.0"?>
+<shell>
+	<name>mycommand</name>
+	<description/>
+	<subcommands/>
+	<options>
+		<option name="--help" short="-h" help="Display this help." boolean="1">
+			<default></default>
+			<choices></choices>
+		</option>
+		<option name="--test" short="" help="A test option." boolean="0">
+			<default></default>
+			<choices></choices>
+		</option>
+	</options>
+	<arguments>
+		<argument name="model" help="The model to make." required="1">
+			<choices></choices>
+		</argument>
+		<argument name="other_longer" help="Another argument." required="0">
+			<choices></choices>
+		</argument>
+	</arguments>
+	<epilog/>
+</shell>
+TEXT;
+		$this->assertEquals(new DomDocument($expected), new DomDocument($result), 'Help does not match');
+	}
 }