Rename Macro -> Helper.

A few people think that Macro is the wrong term to use as it implies
C/C++/Lisp macros which is nothing like this feature. By using Helper,
we can better convey what the classes are for (helping in shells). I've
kept the shortform output() method, and also made it possible to get
a helper instance in case someone wants to get instances and call
non-output() methods on it.

src/Console/ConsoleIo.php

@@ -16,7 +16,7 @@
 
 use Cake\Console\ConsoleInput;
 use Cake\Console\ConsoleOutput;
-use Cake\Console\MacroRegistry;
+use Cake\Console\HelperRegistry;
 use Cake\Log\Engine\ConsoleLog;
 use Cake\Log\Log;
 
@@ -54,9 +54,9 @@ class ConsoleIo
     /**
      * The macro registry.
      *
-     * @var \Cake\Console\MacroRegistry
+     * @var \Cake\Console\HelperRegistry
      */
-    protected $_macros;
+    protected $_helpers;
 
     /**
      * Output constant making verbose shells.
@@ -100,14 +100,14 @@ class ConsoleIo
      * @param \Cake\Console\ConsoleOutput|null $out A ConsoleOutput object for stdout.
      * @param \Cake\Console\ConsoleOutput|null $err A ConsoleOutput object for stderr.
      * @param \Cake\Console\ConsoleInput|null $in A ConsoleInput object for stdin.
-     * @param \Cake\Console\MacroRegistry|null $macros A MacroRegistry instance
+     * @param \Cake\Console\HelperRegistry|null $helpers A HelperRegistry instance
      */
-    public function __construct(ConsoleOutput $out = null, ConsoleOutput $err = null, ConsoleInput $in = null, MacroRegistry $macros = null)
+    public function __construct(ConsoleOutput $out = null, ConsoleOutput $err = null, ConsoleInput $in = null, HelperRegistry $helpers = null)
     {
         $this->_out = $out ? $out : new ConsoleOutput('php://stdout');
         $this->_err = $err ? $err : new ConsoleOutput('php://stderr');
         $this->_in = $in ? $in : new ConsoleInput('php://stdin');
-        $this->_macros = $macros ? $macros : new MacroRegistry($this);
+        $this->_helpers = $helpers ? $helpers : new HelperRegistry($this);
     }
 
     /**
@@ -375,20 +375,18 @@ public function setLoggers($enable)
     }
 
     /**
-     * Render a Console Macro
+     * Render a Console Helper
      *
      * Create and render the output for a macro object. If the macro
      * object has not already been loaded, it will be loaded and constructed.
      *
      * @param string $name The name of the macro to render
-     * @param array $args The arguments for the macro output.
-     * @return void
+     * @return Cake\Console\Helper The created helper instance.
      */
-    public function macro($name, $args = [])
+    public function helper($name)
     {
         $name = ucfirst($name);
-        $macro = $this->_macros->load($name);
-        return $macro->output($args);
+        return $this->_helpers->load($name);
     }
 
     /**
@@ -400,6 +398,7 @@ public function macro($name, $args = [])
      */
     public function __call($method, $args)
     {
-        return $this->macro($method, $args);
+        $helper = $this->helper($method, $args);
+        return $helper->output($args);
     }
 }

src/Console/Exception/MissingMacroException.php → src/Console/Exception/MissingHelperException.php

@@ -15,11 +15,11 @@
 use Cake\Core\Exception\Exception;
 
 /**
- * Used when a Macro cannot be found.
+ * Used when a Helper cannot be found.
  *
  */
-class MissingMacroException extends Exception
+class MissingHelperException extends Exception
 {
 
-    protected $_messageTemplate = 'Macro class %s could not be found.';
+    protected $_messageTemplate = 'Helper class %s could not be found.';
 }

src/Console/Macro.php → src/Console/Helper.php

@@ -17,13 +17,13 @@
 use Cake\Console\ConsoleIo;
 
 /**
- * Base class for Macros.
+ * Base class for Helpers.
  *
- * Console Macros allow you to package up reusable blocks
+ * Console Helpers allow you to package up reusable blocks
  * of Console output logic. For example creating tables,
  * progress bars or ascii art.
  */
-abstract class Macro
+abstract class Helper
 {
     public function __construct(ConsoleIo $io)
     {

src/Console/MacroRegistry.php → src/Console/HelperRegistry.php

@@ -14,16 +14,16 @@
  */
 namespace Cake\Console;
 
-use Cake\Console\Exception\MissingMacroException;
+use Cake\Console\Exception\MissingHelperException;
 use Cake\Core\App;
 use Cake\Core\ObjectRegistry;
 use Cake\Console\ConsoleIo;
 
 /**
- * Registry for Macros. Provides features
- * for lazily loading macros.
+ * Registry for Helpers. Provides features
+ * for lazily loading helpers.
  */
-class MacroRegistry extends ObjectRegistry
+class HelperRegistry extends ObjectRegistry
 {
 
     /**
@@ -44,7 +44,7 @@ public function __construct(ConsoleIo $io)
     }
 
     /**
-     * Resolve a macro classname.
+     * Resolve a helper classname.
      *
      * Part of the template method for Cake\Core\ObjectRegistry::load()
      *
@@ -53,36 +53,36 @@ public function __construct(ConsoleIo $io)
      */
     protected function _resolveClassName($class)
     {
-        return App::className($class, 'Shell/Macro', 'Macro');
+        return App::className($class, 'Shell/Helper', 'Helper');
     }
 
     /**
-     * Throws an exception when a macro is missing.
+     * Throws an exception when a helper is missing.
      *
      * Part of the template method for Cake\Core\ObjectRegistry::load()
      *
      * @param string $class The classname that is missing.
-     * @param string $plugin The plugin the macro is missing in.
+     * @param string $plugin The plugin the helper is missing in.
      * @return void
-     * @throws \Cake\Console\Exception\MissingMacroException
+     * @throws \Cake\Console\Exception\MissingHelperException
      */
     protected function _throwMissingClassError($class, $plugin)
     {
-        throw new MissingMacroException([
+        throw new MissingHelperException([
             'class' => $class,
             'plugin' => $plugin
         ]);
     }
 
     /**
-     * Create the macro instance.
+     * Create the helper instance.
      *
      * Part of the template method for Cake\Core\ObjectRegistry::load()
      *
      * @param string $class The classname to create.
-     * @param string $alias The alias of the macro.
-     * @param array $settings An array of settings to use for the macro.
-     * @return \Cake\Console\Macro The constructed macro class.
+     * @param string $alias The alias of the helper.
+     * @param array $settings An array of settings to use for the helper.
+     * @return \Cake\Console\Helper The constructed helper class.
      */
     protected function _create($class, $alias, $settings)
     {

src/Shell/Macro/TableMacro.php → src/Shell/Helper/TableHelper.php

@@ -12,15 +12,15 @@
  * @since         3.1.0
  * @license       http://www.opensource.org/licenses/mit-license.php MIT License
  */
-namespace Cake\Shell\Macro;
+namespace Cake\Shell\Helper;
 
-use Cake\Console\Macro;
+use Cake\Console\Helper;
 
 /**
  * Create a visually pleasing ASCII art table
  * from 2 dimensional array data.
  */
-class TableMacro extends Macro
+class TableHelper extends Helper
 {
     /**
      * Calculate the column widths
@@ -81,6 +81,9 @@ protected function _render($row, $widths)
      */
     public function output($rows)
     {
+        if (count($rows) === 1) {
+            $rows = $rows[0];
+        }
         $widths = $this->_calculateWidths($rows);
 
         $this->_rowSeparator($widths);

src/Shell/RoutesShell.php

@@ -40,7 +40,7 @@ public function main()
         foreach (Router::routes() as $route) {
             $output[] = [$route->getName(), $route->template, json_encode($route->defaults)];
         }
-        $this->_io->macro('table', $output);
+        $this->_io->table($output);
     }
 
     /**
@@ -57,7 +57,7 @@ public function check($url)
                 ['Route name', 'URI template', 'Defaults'],
                 ['', $url, json_encode($route)]
             ];
-            $this->_io->macro('table', $output);
+            $this->_io->table($output);
         } catch (MissingRouteException $e) {
             $this->err("<warning>'$url' did not match any routes.</warning>");
             return false;

tests/TestCase/Console/ConsoleIoTest.php

@@ -359,16 +359,30 @@ public function testStyles()
     }
 
     /**
-     * Test the macro method.
+     * Test the helper method.
      *
      * @return void
      */
-    public function testMacro()
+    public function testHelper()
     {
-        $this->out->expects($this->exactly(2))
+        $this->out->expects($this->once())
+            ->method('write')
+            ->with('It works!well ish');
+        $helper = $this->io->helper('simple');
+        $this->assertInstanceOf('Cake\Console\Helper', $helper);
+        $helper->output(['well', 'ish']);
+    }
+
+    /**
+     * Test the helper __call.
+     *
+     * @return void
+     */
+    public function testHelperCall()
+    {
+        $this->out->expects($this->once())
             ->method('write')
             ->with('It works!well ish');
-        $this->io->macro('simple', ['well', 'ish']);
-        $this->io->simple('well', 'ish');
+        $helper = $this->io->simple('well', 'ish');
     }
 }

tests/TestCase/Console/MacroRegistryTest.php → tests/TestCase/Console/HelperRegistryTest.php

@@ -14,16 +14,16 @@
  */
 namespace Cake\Test\TestCase\Console;
 
-use Cake\Console\MacroRegistry;
+use Cake\Console\HelperRegistry;
 use Cake\Core\Configure;
 use Cake\Core\Plugin;
 use Cake\TestSuite\TestCase;
 
 /**
- * Class MacroRegistryTest
+ * Class HelperRegistryTest
  *
  */
-class MacroRegistryTest extends TestCase
+class HelperRegistryTest extends TestCase
 {
 
     /**
@@ -36,7 +36,7 @@ public function setUp()
         parent::setUp();
         Configure::write('App.namespace', 'TestApp');
         $io = $this->getMock('Cake\Console\ConsoleIo', [], [], '', false);
-        $this->macros = new MacroRegistry($io);
+        $this->helpers = new HelperRegistry($io);
     }
 
     /**
@@ -46,7 +46,7 @@ public function setUp()
      */
     public function tearDown()
     {
-        unset($this->macros);
+        unset($this->helpers);
         parent::tearDown();
     }
 
@@ -57,23 +57,23 @@ public function tearDown()
      */
     public function testLoad()
     {
-        $result = $this->macros->load('Simple');
-        $this->assertInstanceOf('TestApp\Shell\Macro\SimpleMacro', $result);
-        $this->assertInstanceOf('TestApp\Shell\Macro\SimpleMacro', $this->macros->Simple);
+        $result = $this->helpers->load('Simple');
+        $this->assertInstanceOf('TestApp\Shell\Helper\SimpleHelper', $result);
+        $this->assertInstanceOf('TestApp\Shell\Helper\SimpleHelper', $this->helpers->Simple);
 
-        $result = $this->macros->loaded();
+        $result = $this->helpers->loaded();
         $this->assertEquals(['Simple'], $result, 'loaded() results are wrong.');
     }
 
     /**
      * test missingtask exception
      *
-     * @expectedException \Cake\Console\Exception\MissingMacroException
+     * @expectedException \Cake\Console\Exception\MissingHelperException
      * @return void
      */
-    public function testLoadMissingMacro()
+    public function testLoadMissingHelper()
     {
-        $this->macros->load('ThisTaskShouldAlwaysBeMissing');
+        $this->helpers->load('ThisTaskShouldAlwaysBeMissing');
     }
 
     /**
@@ -85,18 +85,18 @@ public function testLoadWithAlias()
     {
         Plugin::load('TestPlugin');
 
-        $result = $this->macros->load('SimpleAliased', ['className' => 'Simple']);
-        $this->assertInstanceOf('TestApp\Shell\Macro\SimpleMacro', $result);
-        $this->assertInstanceOf('TestApp\Shell\Macro\SimpleMacro', $this->macros->SimpleAliased);
+        $result = $this->helpers->load('SimpleAliased', ['className' => 'Simple']);
+        $this->assertInstanceOf('TestApp\Shell\Helper\SimpleHelper', $result);
+        $this->assertInstanceOf('TestApp\Shell\Helper\SimpleHelper', $this->helpers->SimpleAliased);
 
-        $result = $this->macros->loaded();
+        $result = $this->helpers->loaded();
         $this->assertEquals(['SimpleAliased'], $result, 'loaded() results are wrong.');
 
-        $result = $this->macros->load('SomeMacro', ['className' => 'TestPlugin.Example']);
-        $this->assertInstanceOf('TestPlugin\Shell\Macro\ExampleMacro', $result);
-        $this->assertInstanceOf('TestPlugin\Shell\Macro\ExampleMacro', $this->macros->SomeMacro);
+        $result = $this->helpers->load('SomeHelper', ['className' => 'TestPlugin.Example']);
+        $this->assertInstanceOf('TestPlugin\Shell\Helper\ExampleHelper', $result);
+        $this->assertInstanceOf('TestPlugin\Shell\Helper\ExampleHelper', $this->helpers->SomeHelper);
 
-        $result = $this->macros->loaded();
-        $this->assertEquals(['SimpleAliased', 'SomeMacro'], $result, 'loaded() results are wrong.');
+        $result = $this->helpers->loaded();
+        $this->assertEquals(['SimpleAliased', 'SomeHelper'], $result, 'loaded() results are wrong.');
     }
 }