Comments and improvements

CHANGELOG.md

@@ -0,0 +1,10 @@
+Changelog and Upgrade Instructions
+==================================
+
+## 0.2.x to 0.3.x
+
+Major changes:
+
+ * The `Shell::EV_*` constants have been renamed to `Shell::EVT_*`.
+ * The `configure` method has been removed.
+ * Events are now dispatched using the *NoccyLabs/TinyEvent* library.

examples/timers.php

@@ -24,7 +24,7 @@ class MyShell extends Shell
 
     protected $seq = 0;
 
-    protected function configure()
+    public function __construct()
     {
         $context = new MyContext();
         $this->pushContext($context);

lib/Shell.php

@@ -32,21 +32,48 @@ class Shell
      * @var Context[] The stack of parent contexts
      */
     protected $contextStack = [];
-    
+    /**
-    protected $listeners = [];
+     * @var object[] Created timers
-    
+     */    
     protected $timers = [];
-
+    /** 
+     * @var object[] Running subtasks
+     */
     protected $tasks = [];
-
+    /**
+     * @var string The prompt string
+     */
     protected $prompt = ">";
-
+    /**
+     * @var Style The style applied to the prompt
+     */
     protected $prompt_style = null;
-
+    /**
+     * @var Style The style applied to the input text
+     */
     protected $input_style = null;
 
+    /**
+     * Constructor
+     *
+     */
     public function __construct()
     {
+        $t = $this;
+        register_shutdown_function(function () use (&$t) {
+            if ($t) unset($t);
+        });
+    }
+
+    /**
+     * Destructor
+     *
+     */
+    public function __destruct()
+    {
+        if ($this->lineReader) {
+            $this->lineReader = null;
+        }
     }
 
     /**
@@ -159,6 +186,11 @@ class Shell
         });
     }
 
+    /**
+     * Set the prompt text 
+     *
+     * @param string $text The text
+     */
     public function setPrompt($text)
     {
         $this->prompt = $text;
@@ -168,6 +200,11 @@ class Shell
         }
     }
 
+    /**
+     * Set the prompt style
+     *
+     * @param Style $style The style to apply to the prompt
+     */
     public function setPromptStyle(Style $style)
     {
         $this->prompt_style = $style;
@@ -177,6 +214,11 @@ class Shell
         }
     }
 
+    /**
+     * Set the input style
+     *
+     * @param Style $style The style to apply to the text
+     */
     public function setInputStyle(Style $style)
     {
         $this->input_style = $style;
@@ -220,7 +262,7 @@ class Shell
      * Execute a command with arguments.
      *
      * @param string $command The command name to execute
-     * @param string $args Arguments
+     * @param string ...$args Arguments
      * @return mixed 
      * @throws Exception\BadCommandExcception
      */
@@ -248,6 +290,13 @@ class Shell
         throw new Exception\BadCommandException("Command {$command} not found");
     }
 
+    /**
+     * Execute a built-in command
+     *
+     * @param string $command Command name
+     * @param mixed ...$args Arguments
+     * @return bool True if the command was handled OK
+     */
     public function executeBuiltin($command, ...$args)
     {
         switch ($command) {
@@ -322,6 +371,10 @@ class Shell
         }
     }
 
+    /**
+     * Start the shell
+     *
+     */
     public function run()
     {
         try {
@@ -391,7 +444,12 @@ class Shell
         $this->lineReader = null;
 
     }
-
+    /**
+     * Helper function to emit an event with shell instance and context included.
+     *
+     * @param string $type The event type
+     * @param array[] $data The userdata of the event
+     */
     private function dispatchEvent($type, array $data=[])
     {
         $data['shell'] = $this;
@@ -400,6 +458,10 @@ class Shell
         $this->emitEvent($type, $event);
     }
 
+    /**
+     * Stop the shell; calling this method will cause the main run() to return.
+     *
+     */
     public function stop()
     {
         $this->running = false;