From 4cd5cc2620dc35c380131975b0ad24a0ac34c449 Mon Sep 17 00:00:00 2001
From: Christopher Vagnetoft <cvagnetoft@gmail.com>
Date: Tue, 24 Jan 2017 00:49:13 +0100
Subject: [PATCH] Comments and improvements

---
 CHANGELOG.md        | 10 ++++++
 examples/timers.php |  2 +-
 lib/Shell.php       | 80 ++++++++++++++++++++++++++++++++++++++++-----
 3 files changed, 82 insertions(+), 10 deletions(-)
 create mode 100644 CHANGELOG.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..75d7bf8
--- /dev/null
+++ b/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.
diff --git a/examples/timers.php b/examples/timers.php
index 913ece0..e7a41b5 100644
--- a/examples/timers.php
+++ b/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);
diff --git a/lib/Shell.php b/lib/Shell.php
index 72cf3f6..926126a 100644
--- a/lib/Shell.php
+++ b/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;